![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to p9 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog|
Return to p9 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog |
1.1 root 1: .\" @(#)p9 6.1 (Berkeley) 4/25/86
2: .\"
3: .sp 100
4: .TL
5: .ft R
6: Appendix \(em The Standard I/O Library
7: .AU
8: D. M. Ritchie
9: .AI
10: .MH
11: .PP
12: The standard I/O library
13: was designed with the following goals in mind.
14: .IP 1.
15: It must be as efficient as possible, both in time and in space,
16: so that there will be no hesitation in using it
17: no matter how critical the application.
18: .IP 2.
19: It must be simple to use, and also free of the magic
20: numbers and mysterious calls
21: whose use mars the understandability and portability
22: of many programs using older packages.
23: .IP 3.
24: The interface provided should be applicable on all machines,
25: whether or not the programs which implement it are directly portable
26: to other systems,
27: or to machines other than the PDP-11 running a version of
28: .UC UNIX .
29: .SH
30: 1. General Usage
31: .PP
32: Each program using the library must have the line
33: .P1
34: #include <stdio.h>
35: .P2
36: which defines certain macros and variables.
37: The routines are in the normal C library,
38: so no special library argument is needed for loading.
39: All names in the include file intended only for internal use begin
40: with an underscore
41: .UL _
42: to reduce the possibility
43: of collision with a user name.
44: The names intended to be visible outside the package are
45: .IP \f3stdin\f1 10
46: The name of the standard input file
47: .IP \f3stdout\f1 10
48: The name of the standard output file
49: .IP \f3stderr\f1 10
50: The name of the standard error file
51: .IP \f3EOF\f1 10
52: is actually \-1, and is the value returned by
53: the read routines on end-of-file or error.
54: .IP \f3NULL\f1 10
55: is a notation for the null pointer, returned by
56: pointer-valued functions
57: to indicate an error
58: .IP \f3FILE\f1 10
59: expands to
60: .UL struct
61: .UL _iob
62: and is a useful
63: shorthand when declaring pointers
64: to streams.
65: .IP \f3BUFSIZ\f1 10
66: is a number (viz. 512)
67: of the size suitable for an I/O buffer supplied by the user.
68: See
69: .UL setbuf ,
70: below.
71: .IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
72: .br
73: are defined as macros.
74: Their actions are described below;
75: they are mentioned here
76: to point out that it is not possible to
77: redeclare them
78: and that they are not actually functions;
79: thus, for example, they may not have breakpoints set on them.
80: .PP
81: The routines in this package
82: offer the convenience of automatic buffer allocation
83: and output flushing where appropriate.
84: The names
85: .UL stdin ,
86: .UL stdout ,
87: and
88: .UL stderr
89: are in effect constants and may not be assigned to.
90: .SH
91: 2. Calls
92: .nr PD .4v
93: .LP
94: .UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
95: .nr PD 0
96: .IP
97: .br
98: opens the file and, if needed, allocates a buffer for it.
99: .UL filename
100: is a character string specifying the name.
101: .UL type
102: is a character string (not a single character).
103: It may be
104: .UL \&"r" ,
105: .UL \&"w" ,
106: or
107: .UL \&"a"
108: to indicate
109: intent to read, write, or append.
110: The value returned is a file pointer.
111: If it is
112: .UL NULL
113: the attempt to open failed.
114: .ne 3
115: .nr PD .4v
116: .LP
117: .UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
118: .nr PD 0
119: .IP
120: .br
121: The stream named by
122: .UL ioptr
123: is closed, if necessary, and then reopened
124: as if by
125: .UL fopen .
126: If the attempt to open fails,
127: .UL NULL
128: is returned,
129: otherwise
130: .UL ioptr ,
131: which will now refer to the new file.
132: Often the reopened stream is
133: .UL stdin
134: or
135: .UL stdout .
136: .nr PD .4v
137: .LP
138: .UL int\ getc(ioptr)\ FILE\ *ioptr;
139: .nr PD 0
140: .IP
141: returns the next character from the stream named by
142: .UL ioptr ,
143: which is a pointer to a file such as returned by
144: .UL fopen ,
145: or the name
146: .UL stdin .
147: The integer
148: .UL EOF
149: is returned on end-of-file or when
150: an error occurs.
151: The null character
152: .UL \e0
153: is a legal character.
154: .nr PD .4v
155: .LP
156: .UL int\ fgetc(ioptr)\ FILE\ *ioptr;
157: .nr PD 0
158: .IP
159: .br
160: acts like
161: .UL getc
162: but is a genuine function,
163: not a macro,
164: so it can be pointed to, passed as an argument, etc.
165: .nr PD .4v
166: .LP
167: .UL putc(c,\ ioptr)\ FILE\ *ioptr;
168: .nr PD 0
169: .IP
170: .br
171: .UL putc
172: writes the character
173: .UL c
174: on the output stream named by
175: .UL ioptr ,
176: which is a value returned from
177: .UL fopen
178: or perhaps
179: .UL stdout
180: or
181: .UL stderr .
182: The character is returned as value,
183: but
184: .UL EOF
185: is returned on error.
186: .nr PD .4v
187: .LP
188: .UL fputc(c,\ ioptr)\ FILE\ *ioptr;
189: .nr PD 0
190: .IP
191: .br
192: acts like
193: .UL putc
194: but is a genuine
195: function, not a macro.
196: .nr PD .4v
197: .LP
198: .UL fclose(ioptr)\ FILE\ *ioptr;
199: .nr PD 0
200: .IP
201: .br
202: The file corresponding to
203: .UL ioptr
204: is closed after any buffers are emptied.
205: A buffer allocated by the I/O system is freed.
206: .UL fclose
207: is automatic on normal termination of the program.
208: .nr PD .4v
209: .LP
210: .UL fflush(ioptr)\ FILE\ *ioptr;
211: .nr PD 0
212: .IP
213: .br
214: Any buffered information on the (output) stream named by
215: .UL ioptr
216: is written out.
217: Output files are normally buffered
218: if and only if they are not directed to the terminal;
219: however,
220: .UL stderr
221: always starts off unbuffered and remains so unless
222: .UL setbuf
223: is used, or unless it is reopened.
224: .nr PD .4v
225: .LP
226: .UL exit(errcode);
227: .nr PD 0
228: .IP
229: .br
230: terminates the process and returns its argument as status
231: to the parent.
232: This is a special version of the routine
233: which calls
234: .UL fflush
235: for each output file.
236: To terminate without flushing,
237: use
238: .UL _exit .
239: .nr PD .4v
240: .LP
241: .UL feof(ioptr)\ FILE\ *ioptr;
242: .nr PD 0
243: .IP
244: .br
245: returns non-zero when end-of-file
246: has occurred on the specified input stream.
247: .nr PD .4v
248: .LP
249: .UL ferror(ioptr)\ FILE\ *ioptr;
250: .nr PD 0
251: .IP
252: .br
253: returns non-zero when an error has occurred while reading
254: or writing the named stream.
255: The error indication lasts until the file has been closed.
256: .nr PD .4v
257: .LP
258: .UL getchar();
259: .nr PD 0
260: .IP
261: .br
262: is identical to
263: .UL getc(stdin) .
264: .nr PD .4v
265: .LP
266: .UL putchar(c);
267: .nr PD 0
268: .IP
269: .br
270: is identical to
271: .UL putc(c,\ stdout) .
272: .nr PD .4v
273: .nr PD .4v
274: .ne 2
275: .LP
276: .UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
277: .nr PD 0
278: .IP
279: .br
280: reads up to
281: .UL n-1
282: characters from the stream
283: .UL ioptr
284: into the character pointer
285: .UL s .
286: The read terminates with a newline character.
287: The newline character is placed in the buffer
288: followed by a null character.
289: .UL fgets
290: returns the first argument,
291: or
292: .UL NULL
293: if error or end-of-file occurred.
294: .nr PD .4v
295: .nr PD .4v
296: .LP
297: .UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
298: .nr PD 0
299: .IP
300: .br
301: writes the null-terminated string (character array)
302: .UL s
303: on the stream
304: .UL ioptr .
305: No newline is appended.
306: No value is returned.
307: .nr PD .4v
308: .LP
309: .UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
310: .nr PD 0
311: .IP
312: .br
313: The argument character
314: .UL c
315: is pushed back on the input stream named by
316: .UL ioptr .
317: Only one character may be pushed back.
318: .ne 5
319: .nr PD .4v
320: .LP
321: .UL printf(format,\ a1,\ ...)\ char\ *format;
322: .br
323: .UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
324: .br
325: .UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
326: .br
327: .nr PD 0
328: .IP
329: .UL printf
330: writes on the standard output.
331: .UL fprintf
332: writes on the named output stream.
333: .UL sprintf
334: puts characters in the character array (string)
335: named by
336: .UL s .
337: The specifications are as described in section
338: .UL printf (3)
339: of the
340: .ul
341: .UC UNIX
342: .ul
343: Programmer's Manual.
344: .nr PD .4v
345: .LP
346: .UL scanf(format,\ a1,\ ...)\ char\ *format;
347: .br
348: .UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
349: .br
350: .UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
351: .nr PD 0
352: .IP
353: .br
354: .UL scanf
355: reads from the standard input.
356: .UL fscanf
357: reads from the named input stream.
358: .UL sscanf
359: reads from the character string
360: supplied as
361: .UL s .
362: .UL scanf
363: reads characters, interprets
364: them according to a format, and stores the results in its arguments.
365: Each routine expects as arguments
366: a control string
367: .UL format ,
368: and a set of arguments,
369: .I
370: each of which must be a pointer,
371: .R
372: indicating where the converted input should be stored.
373: .if t .sp .4v
374: .UL scanf
375: returns as its value the number of successfully matched and assigned input
376: items.
377: This can be used to decide how many input items were found.
378: On end of file,
379: .UL EOF
380: is returned; note that this is different
381: from 0, which means that the next input character does not
382: match what was called for in the control string.
383: .RE
384: .nr PD .4v
385: .LP
386: .UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
387: .nr PD 0
388: .IP
389: .br
390: reads
391: .UL nitems
392: of data beginning at
393: .UL ptr
394: from file
395: .UL ioptr .
396: No advance notification
397: that binary I/O is being done is required;
398: when, for portability reasons,
399: it becomes required, it will be done
400: by adding an additional character to the mode-string on the
401: .UL fopen
402: call.
403: .nr PD .4v
404: .LP
405: .UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
406: .nr PD 0
407: .IP
408: .br
409: Like
410: .UL fread ,
411: but in the other direction.
412: .nr PD .4v
413: .LP
414: .UL rewind(ioptr)\ FILE\ *ioptr;
415: .nr PD 0
416: .IP
417: .br
418: rewinds the stream
419: named by
420: .UL ioptr .
421: It is not very useful except on input,
422: since a rewound output file is still open only for output.
423: .nr PD .4v
424: .LP
425: .UL system(string)\ char\ *string;
426: .nr PD 0
427: .IP
428: .br
429: The
430: .UL string
431: is executed by the shell as if typed at the terminal.
432: .nr PD .4v
433: .LP
434: .UL getw(ioptr)\ FILE\ *ioptr;
435: .nr PD 0
436: .IP
437: .br
438: returns the next word from the input stream named by
439: .UL ioptr .
440: .UL EOF
441: is returned on end-of-file or error,
442: but since this a perfectly good
443: integer
444: .UL feof
445: and
446: .UL ferror
447: should be used.
448: A ``word'' is 16 bits on the
449: .UC PDP-11.
450: .nr PD .4v
451: .LP
452: .UL putw(w,\ ioptr)\ FILE\ *ioptr;
453: .nr PD 0
454: .IP
455: .br
456: writes the integer
457: .UL w
458: on the named output stream.
459: .nr PD .4v
460: .LP
461: .UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
462: .nr PD 0
463: .IP
464: .br
465: .UL setbuf
466: may be used after a stream has been opened
467: but before I/O has started.
468: If
469: .UL buf
470: is
471: .UL NULL ,
472: the stream will be unbuffered.
473: Otherwise the buffer supplied will be used.
474: It must be a character array of sufficient size:
475: .P1
476: char buf[BUFSIZ];
477: .P2
478: .nr PD .4v
479: .LP
480: .UL fileno(ioptr)\ FILE\ *ioptr;
481: .nr PD 0
482: .IP
483: .br
484: returns the integer file descriptor associated with the file.
485: .nr PD .4v
486: .LP
487: .UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
488: .nr PD 0
489: .IP
490: .br
491: The location of the next byte in the stream
492: named by
493: .UL ioptr
494: is adjusted.
495: .UL offset
496: is a long integer.
497: If
498: .UL ptrname
499: is 0, the offset is measured from the beginning of the file;
500: if
501: .UL ptrname
502: is 1, the offset is measured from the current read or
503: write pointer;
504: if
505: .UL ptrname
506: is 2, the offset is measured from the end of the file.
507: The routine accounts properly for any buffering.
508: (When this routine is used on
509: .UC UNIX \& non-
510: systems,
511: the offset must be a value returned from
512: .UL ftell
513: and the ptrname must be 0).
514: .ne 3
515: .nr PD .4v
516: .LP
517: .UL long\ ftell(ioptr)\ FILE\ *ioptr;
518: .nr PD 0
519: .IP
520: .br
521: The byte offset, measured from the beginning of the file,
522: associated with the named stream is returned.
523: Any buffering is properly accounted for.
524: (On
525: .UC UNIX \& non-
526: systems the value of this call is useful only
527: for handing to
528: .UL fseek ,
529: so as to position the file to the same place it was when
530: .UL ftell
531: was called.)
532: .nr PD .4v
533: .LP
534: .UL getpw(uid,\ buf)\ char\ *buf;
535: .nr PD 0
536: .IP
537: .br
538: The password file is searched for the given integer user ID.
539: If an appropriate line is found, it is copied into
540: the character array
541: .UL buf ,
542: and 0 is returned.
543: If no line is found corresponding to the user ID
544: then 1 is returned.
545: .nr PD .4v
546: .LP
547: .UL char\ *malloc(num);
548: .nr PD 0
549: .IP
550: .br
551: allocates
552: .UL num
553: bytes.
554: The pointer returned is sufficiently well aligned to be usable for any purpose.
555: .UL NULL
556: is returned if no space is available.
557: .nr PD .4v
558: .LP
559: .UL char\ *calloc(num,\ size);
560: .nr PD 0
561: .IP
562: .br
563: allocates space for
564: .UL num
565: items each of size
566: .UL size .
567: The space is guaranteed to be set to 0 and the pointer is
568: sufficiently well aligned to be usable for any purpose.
569: .UL NULL
570: is returned if no space is available .
571: .nr PD .4v
572: .LP
573: .UL cfree(ptr)\ char\ *ptr;
574: .nr PD 0
575: .IP
576: .br
577: Space is returned to the pool used by
578: .UL calloc .
579: Disorder can be expected if the pointer was not obtained
580: from
581: .UL calloc .
582: .nr PD .4v
583: .LP
584: The following are macros whose definitions may be obtained by including
585: .UL <ctype.h> .
586: .nr PD .4v
587: .LP
588: .UL isalpha(c)
589: returns non-zero if the argument is alphabetic.
590: .nr PD .4v
591: .LP
592: .UL isupper(c)
593: returns non-zero if the argument is upper-case alphabetic.
594: .nr PD .4v
595: .LP
596: .UL islower(c)
597: returns non-zero if the argument is lower-case alphabetic.
598: .nr PD .4v
599: .LP
600: .UL isdigit(c)
601: returns non-zero if the argument is a digit.
602: .nr PD .4v
603: .LP
604: .UL isspace(c)
605: returns non-zero if the argument is a spacing character:
606: tab, newline, carriage return, vertical tab,
607: form feed, space.
608: .nr PD .4v
609: .LP
610: .UL ispunct(c)
611: returns non-zero if the argument is
612: any punctuation character, i.e., not a space, letter,
613: digit or control character.
614: .nr PD .4v
615: .LP
616: .UL isalnum(c)
617: returns non-zero if the argument is a letter or a digit.
618: .nr PD .4v
619: .LP
620: .UL isprint(c)
621: returns non-zero if the argument is printable \(em
622: a letter, digit, or punctuation character.
623: .nr PD .4v
624: .LP
625: .UL iscntrl(c)
626: returns non-zero if the argument is a control character.
627: .nr PD .4v
628: .LP
629: .UL isascii(c)
630: returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
631: .nr PD .4v
632: .LP
633: .UL toupper(c)
634: returns the upper-case character corresponding to the lower-case
635: letter
636: .UL c.
637: .nr PD .4v
638: .LP
639: .UL tolower(c)
640: returns the lower-case character corresponding to the upper-case
641: letter
642: .UL c .
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.