Commit | Line | Data |
---|---|---|
05841234 TL |
1 | .de sr |
2 | .sp 1 | |
3 | .ft I | |
4 | .ne 2 | |
5 | \\$1 | |
6 | .if t .sp .2 | |
7 | .br | |
8 | .ft R | |
9 | .. | |
10 | .de it | |
11 | \fI\\$1\fR | |
12 | .. | |
13 | .TL | |
14 | A New Input-Output Package | |
15 | .AU | |
16 | D. M. Ritchie | |
17 | .PP | |
18 | A new package of IO routines is available under the Unix system. | |
19 | It was designed with the following goals in mind. | |
20 | .IP 1. | |
21 | It should be similar in spirit to the earlier Portable | |
22 | Library, and, to the extent possible, be compatible with it. | |
23 | At the same time a few dubious design choices | |
24 | in the Portable Library will be corrected. | |
25 | .IP 2. | |
26 | It must be as efficient as possible, both in time and in space, | |
27 | so that there will be no hesitation in using it | |
28 | no matter how critical the application. | |
29 | .IP 3. | |
30 | It must be simple to use, and also free of the magic | |
31 | numbers and mysterious calls the use | |
32 | of which mars the understandability and portability | |
33 | of many programs using older packages. | |
34 | .IP 4. | |
35 | The interface provided should be applicable on all machines, | |
36 | whether or not the programs which implement it are directly portable | |
37 | to other systems, | |
38 | or to machines other than the PDP11 running a version of Unix. | |
39 | .PP | |
40 | It is intended that this package replace the Portable Library. | |
41 | Although it is not directly compatible, as discussed below, | |
42 | it is sufficiently similar that | |
43 | a set of relatively small, inexpensive adaptor routines | |
44 | exist which make it appear identical to the current Portable Library | |
45 | except in some very obscure details. | |
46 | .PP | |
47 | The most crucial difference between this package and the Portable | |
48 | Library is that the current offering names streams in terms | |
49 | of pointers rather than by | |
50 | the integers known as `file descriptors.' | |
51 | Thus, for example, the routine which opens a named file | |
52 | returns a pointer to a certain structure rather than a number; | |
53 | the routine which reads an open file | |
54 | takes as an argument the pointer returned from the open call. | |
55 | .SH | |
56 | General Usage | |
57 | .RT | |
58 | Each program using the library must have the line | |
59 | .DS | |
60 | #include <stdio.h> | |
61 | .DE | |
62 | which defines certain macros and variables. | |
63 | The library containing the routines is `/usr/lib/libS.a,' | |
64 | so the command to compile is | |
65 | .DS | |
66 | cc . . . \-lS | |
67 | .DE | |
68 | All names in the include file intended only for internal use begin | |
69 | with an underscore `\_' to reduce the possibility | |
70 | of collision with a user name. | |
71 | The names intended to be visible outside the package are | |
72 | .IP stdin 10 | |
73 | The name of the standard input file | |
74 | .IP stdout 10 | |
75 | The name of the standard output file | |
76 | .IP stderr 10 | |
77 | The name of the standard error file | |
78 | .IP EOF 10 | |
79 | is actually \-1, and is the value returned by | |
80 | the read routines on end-of-file or error. | |
81 | .IP NULL 10 | |
82 | is a notation for the null pointer, returned by | |
83 | pointer-valued functions | |
84 | to indicate an error | |
85 | .IP FILE 10 | |
86 | expands to `struct \_iob' and is a useful | |
87 | shorthand when declaring pointers | |
88 | to streams. | |
89 | .IP BUFSIZ | |
90 | is a number (viz. 512) | |
91 | of the size suitable for an IO buffer supplied by the user. | |
92 | See | |
93 | .it setbuf, | |
94 | below. | |
95 | .IP "getc, getchar, putc, putchar, feof, ferror, fileno" 10 | |
96 | ||
97 | .br | |
98 | are defined as macros. | |
99 | Their actions are described below; | |
100 | they are mentioned here | |
101 | to point out that it is not possible to | |
102 | redeclare them | |
103 | and that they are not actually functions; | |
104 | thus, for example, they may not have breakpoints set on them. | |
105 | .PP | |
106 | The routines in this package, like the current Portable | |
107 | Library, | |
108 | offer the convenience of automatic buffer allocation | |
109 | and output flushing where appropriate. | |
110 | Absent, however, is the facility | |
111 | of changing the default input and output streams | |
112 | by assigning to `cin' and `cout.' | |
113 | The names `stdin,' stdout,' and `stderr' | |
114 | are in effect constants and may not be assigned to. | |
115 | .SH | |
116 | Calls | |
117 | .RT | |
118 | The routines in the library are in nearly one-to-one | |
119 | correspondence with those in the Portable Library. | |
120 | In several cases the name has been changed. | |
121 | This is an attempt to reduce confusion. | |
122 | If the attempt is judged to fail the names may be made identical even | |
123 | though | |
124 | the arguments may be different. | |
125 | The order of this list generally follows the order | |
126 | used in the Portable Library document. | |
127 | .sr "FILE *fopen(filename, type)" | |
128 | .it Fopen | |
129 | opens the file and, if needed, allocates a buffer for it. | |
130 | .it Filename | |
131 | is a character string specifying the name. | |
132 | .it Type | |
133 | is a character string (not a single character). | |
134 | It may be `"r",' `"w",' or `"a"' to indicate | |
135 | intent to read, write, or append. | |
136 | The value returned is a file pointer. | |
137 | If it is null the attempt to open failed. | |
138 | .sr "int getc(ioptr)" | |
139 | returns the next character from the stream named by | |
140 | .it ioptr, | |
141 | which is a pointer to a file such as returned by | |
142 | .it fopen, | |
143 | or the name | |
144 | .it stdin. | |
145 | The integer EOF is returned on end-of-file or when | |
146 | an error occurs. | |
147 | The null character is a legal character. | |
148 | .sr "putc(c, ioptr)" | |
149 | .it Putc | |
150 | writes the character | |
151 | .it c | |
152 | on the output stream named by | |
153 | .it ioptr, | |
154 | which is a value returned from | |
155 | .it fopen | |
156 | or perhaps | |
157 | .it stdout | |
158 | or | |
159 | .it stderr. | |
160 | The character is returned as value, | |
161 | but EOF is returned on error. | |
162 | .sr fclose(ioptr) | |
163 | The file corresponding to | |
164 | .it ioptr | |
165 | is closed after any buffers are emptied. | |
166 | A buffer allocated by the IO system is freed. | |
167 | .it Fclose | |
168 | is automatic on normal termination of the program. | |
169 | .sr fflush(ioptr) | |
170 | Any buffered information on the (output) stream named by | |
171 | .it ioptr | |
172 | is written out. | |
173 | Output files are normally buffered | |
174 | if and only if they are not directed to the terminal, | |
175 | but | |
176 | .it stderr | |
177 | is unbuffered unless | |
178 | .it setbuf | |
179 | is used. | |
180 | .sr exit(errcode) | |
181 | .it Exit | |
182 | terminates the process and returns its argument as status | |
183 | to the parent. | |
184 | This is a special version of the routine | |
185 | which calls | |
186 | .it fflush | |
187 | for each output file. | |
188 | To terminate without flushing, | |
189 | use | |
190 | .it \_exit. | |
191 | .sr feof(ioptr) | |
192 | returns non-zero when end-of-file | |
193 | has occurred on the specified input stream. | |
194 | .sr ferror(ioptr) | |
195 | returns non-zero when an error has occurred while reading | |
196 | or writing the named stream. | |
197 | The error indication lasts until the file has been closed. | |
198 | .sr "getchar( )" | |
199 | is identical to `getc(stdin)'. | |
200 | .sr "putchar(c)" | |
201 | is identical to `putc(c, stdout)'. | |
202 | .sr "char *gets(s)" | |
203 | reads characters up to a new-line from the standard input. | |
204 | The new-line character is replaced by a null character. | |
205 | It is the user's responsibility to make sure that the character array | |
206 | .it s | |
207 | is large enough. | |
208 | .it Gets | |
209 | returns its argument, or null if end-of-file or error occurred. | |
210 | .sr "char *fgets(s, n, ioptr)" | |
211 | reads up to | |
212 | .it n | |
213 | characters from the stream | |
214 | .it ioptr | |
215 | into the character pointer | |
216 | .it s. | |
217 | The read terminates with a new-line character. | |
218 | The new-line character is placed in the buffer | |
219 | followed by a null pointer. | |
220 | The first argument, | |
221 | or a null pointer if error or end-of-file occurred, | |
222 | is returned. | |
223 | .sr puts(s) | |
224 | writes the null-terminated string (character array) | |
225 | .it s | |
226 | on the standard output. | |
227 | A new-line is appended. | |
228 | No value is returned. | |
229 | .sr "fputs(s, ioptr)" | |
230 | writes the null-terminated string (character array) | |
231 | on the stream | |
232 | .it s. | |
233 | No new-line is appended. | |
234 | No value is returned. | |
235 | .sr "ungetc(c, ioptr)" | |
236 | The argument character | |
237 | .it c | |
238 | is pushed back on the input stream named by | |
239 | .it ioptr. | |
240 | Only one character may be pushed back. | |
241 | .sr "printf(format, a1, . . .)" | |
242 | .sr "fprintf(ioptr, format, a1, . . .)" | |
243 | .sr "sprintf(s, format, a1, . . .)" | |
244 | .it Printf | |
245 | writes on the standard output. | |
246 | .it Fprintf | |
247 | writes on the named output stream. | |
248 | .it Sprintf | |
249 | puts characters in the character array (string) | |
250 | named by | |
251 | .it s. | |
252 | The specifications are as usual. | |
253 | .sr "scanf(format, a1, . . .)" | |
254 | .sr "fscanf(ioptr, format, a1, . . .)" | |
255 | .sr "sscanf(s, format, a1, . . .)" | |
256 | .it Scanf | |
257 | reads from the standard input. | |
258 | .it Fscanf | |
259 | reads from the named input stream. | |
260 | .it Sscanf | |
261 | reads from the character string | |
262 | supplied as | |
263 | .it s. | |
264 | The specifications are identical | |
265 | to those of the Portable Library. | |
266 | .sr "fread(ptr, sizeof(*ptr), nitems, ioptr)" | |
267 | writes | |
268 | .it nitems | |
269 | of data beginning at | |
270 | .it ptr | |
271 | on file | |
272 | .it ioptr. | |
273 | It behaves identically to the Portable Library's | |
274 | .it cread. | |
275 | No advance notification | |
276 | that binary IO is being done is required; | |
277 | when, for portability reasons, | |
278 | it becomes required, it will be done | |
279 | by adding an additional character to the mode-string on the | |
280 | fopen call. | |
281 | .sr "fwrite(ptr, sizeof(*ptr), nitems, ioptr)" | |
282 | Like | |
283 | .it fread, | |
284 | but in the other direction. | |
285 | .sr rewind(ioptr) | |
286 | rewinds the stream | |
287 | named by | |
288 | .it ioptr. | |
289 | It is not very useful except on input, | |
290 | since a rewound output file is still open only for output. | |
291 | .sr system(string) | |
292 | .sr atof(s) | |
293 | .sr tmpnam(s) | |
294 | .sr abort(code) | |
295 | .sr "intss( )" | |
296 | .sr "cfree(ptr)" | |
297 | .sr "wdleng( )" | |
298 | are available with specifications identical to those | |
299 | described for the Portable Library. | |
300 | .sr "char *calloc(n, sizeof(object))" | |
301 | returns null when no space is available. | |
302 | The space is guaranteed to be 0. | |
303 | .sr ftoa | |
304 | is not implemented but there are plausible alternatives. | |
305 | .sr "nargs( )" | |
306 | is not implemented. | |
307 | .sr getw(ioptr) | |
308 | returns the next word from the input stream named by | |
309 | .it ioptr. | |
310 | EOF is returned on end-of-file or error, | |
311 | but since this a perfectly good | |
312 | integer | |
313 | .it feof | |
314 | and | |
315 | .it ferror | |
316 | should be used. | |
317 | .sr "putw(w, ioptr)" | |
318 | writes the integer | |
319 | .it w | |
320 | on the named output stream. | |
321 | .sr "setbuf(ioptr, buf)" | |
322 | .it Setbuf | |
323 | may be used after a stream has been opened | |
324 | but before IO has started. | |
325 | If | |
326 | .it buf | |
327 | is null, | |
328 | the stream will be unbuffered. | |
329 | Otherwise the buffer supplied will be used. | |
330 | It is a character array of sufficient size: | |
331 | .DS | |
332 | char buf[BUFSIZ]; | |
333 | .DE | |
334 | .sr "fileno(ioptr)" | |
335 | returns the integer file descriptor associated with the file. | |
336 | .PP | |
337 | Several additional routines are available. | |
338 | .sr "fseek(ioptr, offset, ptrname)" | |
339 | The location of the next byte in the stream | |
340 | named by | |
341 | .it ioptr | |
342 | is adjusted. | |
343 | .it Offset | |
344 | is a long integer. | |
345 | If | |
346 | .it ptrname | |
347 | is 0, the offset is measured from the beginning of the file; | |
348 | if | |
349 | .it ptrname | |
350 | is 1, the offset is measured from the current read or | |
351 | write pointer; | |
352 | if | |
353 | .it ptrname | |
354 | is 2, the offset is measured from the end of the file. | |
355 | The routine accounts properly for any buffering. | |
356 | .sr "long ftell(iop)" | |
357 | The byte offset, measured from the beginning of the file, | |
358 | associated with the named stream is returned. | |
359 | Any buffering is properly accounted for. | |
360 | .sr "getpw(uid, buf)" | |
361 | The password file is searched for the given integer user ID. | |
362 | If an appropriate line is found, it is copied into | |
363 | the character array | |
364 | .it buf, | |
365 | and 0 is returned. | |
366 | If no line is found corresponding to the user ID | |
367 | then 1 is returned. | |
368 | .sr "strcat(s1, s2)" | |
369 | .it S1 | |
370 | and | |
371 | .it s2 | |
372 | are character pointers. | |
373 | The end (null byte) | |
374 | of the | |
375 | .it s1 | |
376 | string is found and | |
377 | .it s2 | |
378 | is copied to | |
379 | .it s1 | |
380 | starting there. | |
381 | The space pointed to by | |
382 | .it s1 | |
383 | must be large enough. | |
384 | .sr "strcmp(s1, s2)" | |
385 | The character strings | |
386 | .it s1 | |
387 | and | |
388 | .it s2 | |
389 | are compared. | |
390 | The result is positive, zero, or negative according as | |
391 | .it s1 | |
392 | is greater than, equal to, or less than | |
393 | .it s2 | |
394 | in ASCII collating sequence. | |
395 | .sr "strcpy(s1, s2) | |
396 | The null-terminated character string | |
397 | .it s2 | |
398 | is copied to the location pointed to by | |
399 | .it s1. | |
400 | .sr "strlen(s)" | |
401 | The number of bytes in s up to a null byte | |
402 | is returned. | |
403 | .it S | |
404 | is a character pointer. | |
405 | .sr "gcvt(num, ndig, buf)" | |
406 | .it Num | |
407 | is a floating or double quantity. | |
408 | .it Ndig | |
409 | significant digits are converted to ASCII and placed | |
410 | into the character array | |
411 | .it buf. | |
412 | The conversion is in Fortran | |
413 | .it e | |
414 | or | |
415 | .it f | |
416 | style, whichever yields the shorter string. | |
417 | Insignificant trailing zeros are eliminated. |