man/libpc.7

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