libpc.7 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299
  1. .\" $Header$
  2. .TH LIBPC VII
  3. .ad
  4. .SH NAME
  5. libpc \- library of external routines for Pascal programs
  6. .SH SYNOPSIS
  7. .ta 11
  8. const bufsize = ?;
  9. .br
  10. type br1 = 1..bufsize;
  11. .br
  12. br2 = 0..bufsize;
  13. .br
  14. br3 = -1..bufsize;
  15. .br
  16. ok = -1..0;
  17. .br
  18. buf = packed array[br1] of char;
  19. .br
  20. alfa = packed array[1..8] of char;
  21. .br
  22. string = ^packed array[1..?] of char;
  23. .br
  24. filetype = file of ?;
  25. .br
  26. long = record high,low:integer end;
  27. {all routines must be declared extern}
  28. function argc:integer;
  29. .br
  30. function argv(i:integer):string;
  31. .br
  32. function environ(i:integer):string;
  33. .br
  34. procedure argshift;
  35. procedure buff(var f:filetype);
  36. .br
  37. procedure nobuff(var f:filetype);
  38. .br
  39. procedure notext(var f:text);
  40. .br
  41. procedure diag(var f:text);
  42. .br
  43. procedure pcreat(var f:text; s:string);
  44. .br
  45. procedure popen(var f:text; s:string);
  46. .br
  47. procedure pclose(var f:filetype);
  48. procedure trap(err:integer);
  49. .br
  50. procedure encaps(procedure p; procedure q(n:integer));
  51. function perrno:integer;
  52. .br
  53. function uread(fd:integer; var b:buf; len:br1):br3;
  54. .br
  55. function uwrite(fd:integer; var b:buf; len:br1):br3;
  56. function strbuf(var b:buf):string;
  57. .br
  58. function strtobuf(s:string; var b:buf; len:br1):br2;
  59. .br
  60. function strlen(s:string):integer;
  61. .br
  62. function strfetch(s:string; i:integer):char;
  63. .br
  64. procedure strstore(s:string; i:integer; c:char);
  65. function clock:integer;
  66. .SH DESCRIPTION
  67. This library contains some often used external routines for Pascal programs.
  68. Two versions exist: one for the EM interpreter and another one
  69. that is used when programs are translated into PDP-11 code.
  70. The routines can be divided into several categories:
  71. .PP
  72. Argument control:
  73. .RS
  74. .IP argc 10
  75. Gives the number of arguments provided when the program is called.
  76. .PD 0
  77. .IP argv
  78. Selects the specified argument from the argument list and returns a
  79. pointer to it.
  80. This pointer is nil if the index is out of bounds (<0 or >=argc).
  81. .IP environ
  82. Returns a pointer to the i-th environment string (i>=0). Returns nil
  83. if i is beyond the end of the environment list (UNIX version 7).
  84. .IP argshift
  85. Effectively deletes the first argument from the argument list.
  86. Its function is equivalent to 'shift' in the UNIX shell: argv[2] becomes
  87. argv[1], argv[3] becomes argv[2], etc.
  88. It is a useful procedure to skip optional flag arguments.
  89. Note that the matching of arguments and files
  90. is done at the time a file is opened by a call to reset or rewrite.
  91. .PD
  92. .PP
  93. .RE
  94. Additional file handling routines:
  95. .RS
  96. .IP buff 10
  97. Turn on buffering of a file. Not very useful, because all
  98. files are buffered except standard output to a terminal and diagnostic output.
  99. Input files are always buffered.
  100. .PD 0
  101. .IP nobuff
  102. Turn off buffering of an output file. It causes the current contents of the
  103. buffer to be flushed.
  104. .IP notext
  105. Only useful for input files.
  106. End of line characters are not replaced by a space and character codes out of
  107. the ASCII range (0..127) do not cause an error message.
  108. .IP diag
  109. Initialize a file for output on the diagnostic output stream (fd=2).
  110. Output is not buffered.
  111. .IP pcreat
  112. The same as rewrite(f), except that you must provide the filename yourself.
  113. The name must be zero terminated. Only text files are allowed.
  114. .IP popen
  115. The same as reset(f), except that you must provide the filename yourself.
  116. The name must be zero terminated. Only text files are allowed.
  117. .IP pclose
  118. Gives you the opportunity to close files hidden in records or arrays.
  119. All other files are closed automatically.
  120. .PD
  121. .PP
  122. .RE
  123. String handling:
  124. .RS
  125. .IP strbuf 10
  126. Type conversion from character array to string.
  127. It is your own responsibility that the string is zero terminated.
  128. .PD 0
  129. .IP strtobuf
  130. Copy string into buffer until the string terminating zero byte
  131. is found or until the buffer if full, whatever comes first.
  132. The zero byte is also copied.
  133. The number of copied characters, excluding the zero byte, is returned. So if
  134. the result is equal to the buffer length, then the end of buffer is reached
  135. before the end of string.
  136. .IP strlen
  137. Returns the string length excluding the terminating zero byte.
  138. .IP strfetch
  139. Fetches the i-th character from a string.
  140. There is no check against the string length.
  141. .IP strstore
  142. Stores a character in a string. There is no check against
  143. string length, so this is a dangerous procedure.
  144. .PD
  145. .PP
  146. .RE
  147. Trap handling:
  148. .RS
  149. These routines allow you to handle almost all
  150. the possible error situations yourself.
  151. You may define your own trap handler, written in Pascal, instead of the
  152. default handler that produces an error message and quits.
  153. You may also generate traps yourself.
  154. .IP trap 10
  155. Trap generates the trap passed as argument (0..252).
  156. The trap numbers 128..252 may be used freely. The others are reserved.
  157. .PD 0
  158. .IP encaps
  159. Encapsulate the execution of 'p' with the trap handler 'q'.
  160. Encaps replaces the previous trap handler by 'q', calls 'p' and restores
  161. the previous handler when 'p' returns.
  162. If, during the execution of 'p', a trap occurs,
  163. then 'q' is called with the trap number as parameter.
  164. For the duration of 'q' the previous trap handler is restored, so that
  165. you may handle only some of the errors in 'q'. All the other errors must
  166. then be raised again by a call to 'trap'.
  167. .br
  168. Encapsulations may be nested: you may encapsulate a procedure while executing
  169. an encapsulated routine.
  170. .br
  171. Jumping out of an encapsulated procedure (non-local goto) is dangerous,
  172. because the previous trap handler must be restored.
  173. Therefore, you may only jump out of procedure 'p' from inside 'q' and
  174. you may only jump out of one level of encapsulation.
  175. If you want to exit several levels of encapsulation, use traps.
  176. See pc_emlib(VII) and pc_prlib(VII) for lists of trap numbers
  177. for EM machine errors and Pascal run time system errors.
  178. Note that 'p' may not have parameters.
  179. .PD
  180. .PP
  181. .RE
  182. UNIX system calls:
  183. .RS
  184. The routines of this category require global variables or routines
  185. of the monitor library libmon(VII).
  186. .IP uread 10
  187. Equal to the read system call.
  188. Its normal name is blocked by the standard Pascal routine read.
  189. .PD 0
  190. .IP uwrite
  191. As above but for write(II).
  192. .IP perrno
  193. Because external data references are not possible in Pascal,
  194. this routine returns the global variable errno, indicating the result of
  195. the last system call.
  196. .PD
  197. .PP
  198. .RE
  199. Miscellaneous:
  200. .RS
  201. .IP clock 10
  202. Return the number of ticks of user and system time consumed by the program.
  203. .PD
  204. .PP
  205. .RE
  206. The following program presents an example of how these routines can be used.
  207. This program is equivalent to the UNIX command cat(I).
  208. .nf
  209. {$c+}
  210. program cat(input,inp,output);
  211. var inp:text;
  212. s:string;
  213. function argc:integer; extern;
  214. function argv(i:integer):string; extern;
  215. procedure argshift; extern;
  216. function strlen(s:string):integer; extern;
  217. function strfetch(s:string; i:integer):char; extern;
  218. procedure copy(var fi:text);
  219. var c:char;
  220. begin reset(fi);
  221. while not eof(fi) do
  222. begin
  223. while not eoln(fi) do
  224. begin
  225. read(fi,c);
  226. write(c)
  227. end;
  228. readln(fi);
  229. writeln
  230. end
  231. end;
  232. begin {main}
  233. if argc = 1 then
  234. copy(input)
  235. else
  236. repeat
  237. s := argv(1);
  238. if (strlen(s) = 1) and (strfetch(s,1) = '-')
  239. then copy(input)
  240. else copy(inp);
  241. argshift;
  242. until argc <= 1;
  243. end.
  244. .fi
  245. .PP
  246. Another example gives some idea of the way to manage trap handling:
  247. .nf
  248. program bigreal(output);
  249. const EFOVFL=4;
  250. var trapped:boolean;
  251. procedure encaps(procedure p;
  252. procedure q(n:integer)); extern;
  253. procedure trap(n:integer); extern;
  254. procedure traphandler(n:integer);
  255. begin if n=EFOVFL then trapped:=true else trap(n) end;
  256. procedure work;
  257. var i,j:real;
  258. begin trapped:=false; i:=1;
  259. while not trapped do
  260. begin j:=i; i:=i*2 end;
  261. writeln('bigreal = ',j);
  262. end;
  263. begin
  264. encaps(work,traphandler);
  265. end.
  266. .fi
  267. .SH FILES
  268. .IP /usr/em/mach/*/lib/tail_pc 20
  269. .PD
  270. .SH "SEE ALSO"
  271. ack(I), pc_pem(VI), pc_prlib(VII), libmon(VII)
  272. .SH DIAGNOSTICS
  273. Two routines may cause fatal error messages to be generated.
  274. These are:
  275. .IP pcreat 10
  276. Rewrite error (trap 77) if the file cannot be created.
  277. .PD 0
  278. .IP popen
  279. Reset error (trap 76) if the file cannot be opened for reading
  280. .PD
  281. .SH AUTHOR
  282. Johan Stevenson, Vrije Universiteit.
  283. .br
  284. encaps: Ed Keizer, Vrije Universiteit.