![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ios.r CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 3BSD / libc / stdio|
Return to ios.r CVS log | Up to [CSRG BSD Unix] / 3BSD / libc / stdio |
1.1 root 1: .de s
2: .sp .5v
3: ..
4: .de sr
5: .ft I
6: .ne 2
7: \\$1
8: .if t .sp .2
9: .br
10: .ft R
11: ..
12: .de it
13: \fI\\$1\fR
14: ..
15: .TL
16: A New Input-Output Package
17: .AU
18: D. M. Ritchie
19: .AI
20: .MH
21: .PP
22: A new package of IO routines is available.
23: It was designed with the following goals in mind.
24: .IP 1.
25: It should be similar in spirit to the earlier Portable
26: Library, and, to the extent possible, be compatible with it.
27: At the same time a few dubious design choices
28: in the Portable Library will be corrected.
29: .IP 2.
30: It must be as efficient as possible, both in time and in space,
31: so that there will be no hesitation in using it
32: no matter how critical the application.
33: .IP 3.
34: It must be simple to use, and also free of the magic
35: numbers and mysterious calls the use
36: of which mars the understandability and portability
37: of many programs using older packages.
38: .IP 4.
39: The interface provided should be applicable on all machines,
40: whether or not the programs which implement it are directly portable
41: to other systems,
42: or to machines other than the PDP11 running a version of Unix.
43: .PP
44: It is intended that this package replace the Portable Library.
45: Although it is not directly compatible, as discussed below,
46: it is sufficiently similar that
47: modifying programs to use it should be a simple exercise.
48: .PP
49: The most crucial difference between this package and the Portable
50: Library is that the current offering names streams in terms
51: of pointers rather than by
52: the integers known as `file descriptors.'
53: Thus, for example, the routine which opens a named file
54: returns a pointer to a certain structure rather than a number;
55: the routine which reads an open file
56: takes as an argument the pointer returned from the open call.
57: .SH
58: General Usage
59: .PP
60: Each program using the library must have the line
61: .DS
62: #include <stdio.h>
63: .DE
64: which defines certain macros and variables.
65: The library containing the routines is `/usr/lib/libS.a,'
66: so the command to compile is
67: .DS
68: cc . . . \-lS
69: .DE
70: All names in the include file intended only for internal use begin
71: with an underscore `\_' to reduce the possibility
72: of collision with a user name.
73: The names intended to be visible outside the package are
74: .IP stdin 10
75: The name of the standard input file
76: .IP stdout 10
77: The name of the standard output file
78: .IP stderr 10
79: The name of the standard error file
80: .IP EOF 10
81: is actually \-1, and is the value returned by
82: the read routines on end-of-file or error.
83: .IP NULL 10
84: is a notation for the null pointer, returned by
85: pointer-valued functions
86: to indicate an error
87: .IP FILE 10
88: expands to `struct \_iob' and is a useful
89: shorthand when declaring pointers
90: to streams.
91: .IP BUFSIZ
92: is a number (viz. 512)
93: of the size suitable for an IO buffer supplied by the user.
94: See
95: .it setbuf,
96: below.
97: .IP "getc, getchar, putc, putchar, feof, ferror, fileno" 10
98:
99: .br
100: are defined as macros.
101: Their actions are described below;
102: they are mentioned here
103: to point out that it is not possible to
104: redeclare them
105: and that they are not actually functions;
106: thus, for example, they may not have breakpoints set on them.
107: .PP
108: The routines in this package, like the Portable
109: Library,
110: offer the convenience of automatic buffer allocation
111: and output flushing where appropriate.
112: Absent, however, is the facility
113: of changing the default input and output streams
114: by assigning to `cin' and `cout.'
115: The names `stdin,' stdout,' and `stderr'
116: are in effect constants and may not be assigned to.
117: .SH
118: Calls
119: .PP
120: The routines in the library are in nearly one-to-one
121: correspondence with those in the Portable Library.
122: In several cases the name has been changed.
123: This is an attempt to reduce confusion.
124: .s
125: .sr "FILE *fopen(filename, type) char *filename, *type"
126: .it Fopen
127: opens the file and, if needed, allocates a buffer for it.
128: .it Filename
129: is a character string specifying the name.
130: .it Type
131: is a character string (not a single character).
132: It may be `"r",' `"w",' or `"a"' to indicate
133: intent to read, write, or append.
134: The value returned is a file pointer.
135: If it is NULL the attempt to open failed.
136: .s
137: .sr "FILE *freopen(filename, type, ioptr) char *filename, *type; FILE *ioptr
138: The stream named by
139: .it ioptr
140: is closed, if necessary, and then reopened
141: as if by
142: .it fopen.
143: If the attempt to open fails, NULL is returned,
144: otherwise
145: .it ioptr,
146: which will now refer to the new file.
147: Often the reopened stream is
148: .it stdin
149: or
150: .it stdout.
151: .s
152: .sr "int getc(ioptr) FILE *ioptr
153: returns the next character from the stream named by
154: .it ioptr,
155: which is a pointer to a file such as returned by
156: .it fopen,
157: or the name
158: .it stdin.
159: The integer EOF is returned on end-of-file or when
160: an error occurs.
161: The null character \(aa\e0\(aa is a legal character.
162: .s
163: .sr "int fgetc(ioptr) FILE *ioptr
164: acts like
165: .it getc
166: but is a genuine function,
167: not a macro.
168: .s
169: .sr "putc(c, ioptr) FILE *ioptr
170: .it Putc
171: writes the character
172: .it c
173: on the output stream named by
174: .it ioptr,
175: which is a value returned from
176: .it fopen
177: or perhaps
178: .it stdout
179: or
180: .it stderr.
181: The character is returned as value,
182: but EOF is returned on error.
183: .s
184: .sr "fputc(c, ioptr) FILE *ioptr
185: .it Fputc
186: acts like
187: .it putc
188: but is a genuine
189: function, not a macro.
190: .s
191: .sr "fclose(ioptr) FILE *ioptr
192: The file corresponding to
193: .it ioptr
194: is closed after any buffers are emptied.
195: A buffer allocated by the IO system is freed.
196: .it Fclose
197: is automatic on normal termination of the program.
198: .s
199: .sr "fflush(ioptr) FILE *ioptr
200: Any buffered information on the (output) stream named by
201: .it ioptr
202: is written out.
203: Output files are normally buffered
204: if and only if they are not directed to the terminal,
205: but
206: .it stderr
207: is unbuffered unless
208: .it setbuf
209: is used.
210: .s
211: .sr exit(errcode)
212: .it Exit
213: terminates the process and returns its argument as status
214: to the parent.
215: This is a special version of the routine
216: which calls
217: .it fflush
218: for each output file.
219: To terminate without flushing,
220: use
221: .it \_exit.
222: .s
223: .sr "feof(ioptr) FILE *ioptr
224: returns non-zero when end-of-file
225: has occurred on the specified input stream.
226: .s
227: .sr "ferror(ioptr) FILE *ioptr
228: returns non-zero when an error has occurred while reading
229: or writing the named stream.
230: The error indication lasts until the file has been closed.
231: .s
232: .sr "getchar( )"
233: is identical to
234: .it "getc(stdin).
235: .s
236: .sr "putchar(c)"
237: is identical to
238: .it "putc(c, stdout).
239: .s
240: .sr "char *gets(s) char *s
241: reads characters up to a new-line from the standard input.
242: The new-line character is replaced by a null character.
243: It is the user's responsibility to make sure that the character array
244: .it s
245: is large enough.
246: .it Gets
247: returns its argument, or NULL if end-of-file or error occurred.
248: Note that this routine is not compatible with
249: .it fgets;
250: it is included for downward compatibility.
251: .s
252: .sr "char *fgets(s, n, ioptr) char *s; FILE *ioptr
253: reads up to
254: .it n
255: characters from the stream
256: .it ioptr
257: into the character pointer
258: .it s.
259: The read terminates with a new-line character.
260: The new-line character is placed in the buffer
261: followed by a null character.
262: The first argument,
263: or NULL if error or end-of-file occurred,
264: is returned.
265: .s
266: .sr "puts(s) char *s
267: writes the null-terminated string (character array)
268: .it s
269: on the standard output.
270: A new-line is appended.
271: No value is returned.
272: Note that this routine
273: is not compatible with
274: .it fputs;
275: it is included for downward compatibility.
276: .s
277: .sr "*fputs(s, ioptr) char *s; FILE *ioptr
278: writes the null-terminated string (character array)
279: .it s
280: on the stream
281: .it ioptr.
282: No new-line is appended.
283: No value is returned.
284: .s
285: .sr "ungetc(c, ioptr) FILE *ioptr
286: The argument character
287: .it c
288: is pushed back on the input stream named by
289: .it ioptr.
290: Only one character may be pushed back.
291: .s
292: .sr "printf(format, a1, . . .) char *format
293: .sr "fprintf(ioptr, format, a1, . . .) FILE *ioptr; char *format
294: .sr "sprintf(s, format, a1, . . .)char *s, *format
295: .it Printf
296: writes on the standard output.
297: .it Fprintf
298: writes on the named output stream.
299: .it Sprintf
300: puts characters in the character array (string)
301: named by
302: .it s.
303: The specifications are as described in section
304: .it "printf
305: (III)
306: of the Unix Programmer's Manual.
307: There is a new conversion:
308: .it %m.n\fB\|g\fI
309: converts a double argument in the style of
310: .it e
311: or
312: .it f
313: as most appropriate.
314: .s
315: .sr "scanf(format, a1, . . .) char *format
316: .sr "fscanf(ioptr, format, a1, . . .) FILE *ioptr; char *format
317: .sr "sscanf(s, format, a1, . . .) char *s, *format
318: .it Scanf
319: reads from the standard input.
320: .it Fscanf
321: reads from the named input stream.
322: .it Sscanf
323: reads from the character string
324: supplied as
325: .it s.
326: The specifications are identical
327: to those of the Portable Library.
328: .it Scanf
329: reads characters, interprets
330: them according to a format, and stores the results in its arguments.
331: It expects as arguments
332: a control string
333: .it format,
334: described below,
335: and a set of arguments,
336: .I
337: each of which must be a pointer,
338: .R
339: indicating where the converted input should be stored.
340: .PP
341: The
342: control string
343: usually contains
344: conversion specifications, which are used to direct interpretation
345: of input sequences.
346: The control string may contain:
347: .IP 1.
348: Blanks, tabs or newlines, which are ignored.
349: .IP 2.
350: Ordinary characters (not %) which are expected to match
351: the next non-space character of the input stream
352: (where space characters are defined as blank, tab or newline).
353: .IP 3.
354: Conversion specifications, consisting of the
355: character %, an optional assignment suppressing character \**,
356: an optional numerical maximum field width, and a conversion
357: character.
358: .PP
359: A conversion specification is used to direct the conversion of the
360: next input field; the result
361: is placed in the variable pointed to by the corresponding argument,
362: unless assignment suppression was
363: indicated by the \** character.
364: An input field is defined as a string of non-space characters;
365: it extends either to the next space character or until the field
366: width, if specified, is exhausted.
367: .PP
368: The conversion character indicates the interpretation of the
369: input field; the corresponding pointer argument must
370: usually be of a restricted type.
371: The following conversion characters are legal:
372: .IP %
373: indicates that a single % character is expected
374: in the input stream at this point;
375: no assignment is done.
376: .IP d
377: indicates that a decimal integer is expected
378: in the input stream;
379: the corresponding argument should be an integer pointer.
380: .IP o
381: indicates that an octal integer is expected in the
382: input stream; the corresponding argument should be a integer pointer.
383: .IP x
384: indicates that a hexadecimal integer is expected in the input stream;
385: the corresponding argument should be an integer pointer.
386: .ti -0.2i
387: .IP s
388: indicates that a character string is expected;
389: the corresponding argument should be a character pointer
390: pointing to an array of characters large enough to accept the
391: string and a terminating `\e0', which will be added.
392: The input field is terminated by a space character
393: or a newline.
394: .IP c
395: indicates that a character is expected; the
396: corresponding argument should be a character pointer;
397: the next input character is placed at the indicated spot.
398: The normal skip over space characters is suppressed
399: in this case;
400: to read the next non-space character, try
401: .I
402: %1s.
403: .R
404: If a field width is given, the corresponding argument
405: should refer to a character array, and the
406: indicated number of characters is read.
407: .IP e
408: (or
409: .I f\|\fR)
410: .R
411: indicates that a floating point number is expected in the input stream;
412: the next field is converted accordingly and stored through the
413: corresponding argument, which should be a pointer to a
414: .it float.
415: The input format for
416: floating point numbers is
417: an optionally signed
418: string of digits
419: possibly containing a decimal point, followed by an optional
420: exponent field beginning with an E or e followed by an optionally signed integer.
421: .IP [
422: indicates a string not to be delimited by space characters.
423: The left bracket is followed by a set of characters and a right
424: bracket; the characters between the brackets define a set
425: of characters making up the string.
426: If the first character
427: is not circumflex (\|^\|), the input field
428: is all characters until the first character not in the set between
429: the brackets; if the first character
430: after the left bracket is ^, the input field is all characters
431: until the first character which is in the remaining set of characters
432: between the brackets.
433: The corresponding argument must point to a character array.
434: .PP
435: The conversion characters
436: .I
437: d, o
438: .R
439: and
440: .I
441: x
442: .R
443: may be capitalized or preceded
444: by
445: .I
446: l
447: .R
448: to indicate that a pointer to
449: .I
450: long
451: .R
452: rather than
453: .I
454: int
455: .R
456: is expected.
457: Similarly, the conversion characters
458: .I
459: e
460: .R
461: or
462: .I
463: f
464: .R
465: may be capitalized or
466: preceded by
467: .I
468: l
469: .R
470: to indicate that a pointer to
471: .I
472: double
473: .R
474: rather than
475: .I
476: float
477: .R
478: is in the argument list.
479: The character
480: .I
481: h
482: .R
483: will function similarly in the future to indicate
484: .I
485: short
486: .R
487: data items.
488: .PP
489: For example, the call
490: .DS
491: int i; float x; char name[50];
492: scanf( "%d%f%s", &i, &x, name);
493: .DE
494: with the input line
495: .DS
496: 25 54.32E\(mi1 thompson
497: .DE
498: will assign to
499: .it i
500: the value
501: 25,
502: .it x
503: the value 5.432, and
504: .it name
505: will contain
506: .it ``thompson\e0''.
507: Or,
508: .DS
509: int i; float x; char name[50];
510: scanf("%2d%f%\**d%[1234567890]", &i, &x, name);
511: .DE
512: with input
513: .DS
514: 56789 0123 56a72
515: .DE
516: will assign 56 to
517: .it i,
518: 789.0 to
519: .it x,
520: skip ``0123'',
521: and place the string ``56\e0'' in
522: .it name.
523: The next call to
524: .it getchar
525: will return `a'.
526: .PP
527: .it Scanf
528: returns as its value the number of successfully matched and assigned input
529: items.
530: This can be used to decide how many input items were found.
531: On end of file, EOF is returned; note that this is different
532: from 0, which means that the next input character does not
533: match what was called for in the control string.
534: .s
535: .sr "fread(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr
536: reads
537: .it nitems
538: of data beginning at
539: .it ptr
540: from file
541: .it ioptr.
542: It behaves identically to the Portable Library's
543: .it cread.
544: No advance notification
545: that binary IO is being done is required;
546: when, for portability reasons,
547: it becomes required, it will be done
548: by adding an additional character to the mode-string on the
549: fopen call.
550: .s
551: .sr "fwrite(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr
552: Like
553: .it fread,
554: but in the other direction.
555: .s
556: .sr "rewind(ioptr) FILE *ioptr
557: rewinds the stream
558: named by
559: .it ioptr.
560: It is not very useful except on input,
561: since a rewound output file is still open only for output.
562: .s
563: .sr "system(string) char *string
564: The
565: .it string
566: is executed by the shell as if typed at the terminal.
567: .s
568: .sr "getw(ioptr) FILE *ioptr
569: returns the next word from the input stream named by
570: .it ioptr.
571: EOF is returned on end-of-file or error,
572: but since this a perfectly good
573: integer
574: .it feof
575: and
576: .it ferror
577: should be used.
578: .s
579: .sr "putw(w, ioptr) FILE *ioptr
580: writes the integer
581: .it w
582: on the named output stream.
583: .s
584: .sr "setbuf(ioptr, buf) FILE *ioptr; char *buf
585: .it Setbuf
586: may be used after a stream has been opened
587: but before IO has started.
588: If
589: .it buf
590: is NULL,
591: the stream will be unbuffered.
592: Otherwise the buffer supplied will be used.
593: It is a character array of sufficient size:
594: .DS
595: char buf[BUFSIZ];
596: .DE
597: .s
598: .sr "fileno(ioptr) FILE *ioptr
599: returns the integer file descriptor associated with the file.
600: .s
601: .sr "fseek(ioptr, offset, ptrname) FILE *ioptr; long offset
602: The location of the next byte in the stream
603: named by
604: .it ioptr
605: is adjusted.
606: .it Offset
607: is a long integer.
608: If
609: .it ptrname
610: is 0, the offset is measured from the beginning of the file;
611: if
612: .it ptrname
613: is 1, the offset is measured from the current read or
614: write pointer;
615: if
616: .it ptrname
617: is 2, the offset is measured from the end of the file.
618: The routine accounts properly for any buffering.
619: (When this routine is used on non-Unix systems,
620: the offset must be a value returned from
621: .it ftell
622: and the ptrname must be 0).
623: .s
624: .sr "long ftell(ioptr) FILE *ioptr
625: The byte offset, measured from the beginning of the file,
626: associated with the named stream is returned.
627: Any buffering is properly accounted for.
628: (On non-Unix systems the value of this call is useful only
629: for handing to
630: .it fseek,
631: so as to position the file to the same place it was when
632: .it ftell
633: was called.)
634: .s
635: .sr "getpw(uid, buf) char *buf
636: The password file is searched for the given integer user ID.
637: If an appropriate line is found, it is copied into
638: the character array
639: .it buf,
640: and 0 is returned.
641: If no line is found corresponding to the user ID
642: then 1 is returned.
643: .s
644: .sr "char *calloc(num, size)
645: allocates space for
646: .it num
647: items each of size
648: .it size.
649: The space is guaranteed to be set to 0 and the pointer is
650: sufficiently well aligned to be usable for any purpose.
651: NULL is returned if no space is available.
652: .s
653: .sr "cfree(ptr) char *ptr
654: Space is returned to the pool used by
655: .it calloc.
656: Disorder can be expected if the pointer was not obtained
657: from
658: .it calloc.
659: .LP
660: The following are macros defined by stdio.h.
661: .s
662: .sr isalpha(c)
663: returns non-zero if the argument is alphabetic.
664: .s
665: .sr isupper(c)
666: returns non-zero if the argument is upper-case alphabetic.
667: .s
668: .sr islower(c)
669: returns non-zero if the argument is lower-case alphabetic.
670: .s
671: .sr isdigit(c)
672: returns non-zero if the argument is a digit.
673: .s
674: .sr isspace(c)
675: returns non-zero if the argument is a spacing character:
676: tab, new-line, carriage return, vertical tab,
677: form feed, space.
678: .s
679: .sr toupper(c)
680: returns the upper-case character corresponding to the lower-case
681: letter c.
682: .s
683: .sr tolower(c)
684: returns the lower-case character corresponding to the upper-case
685: letter c.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.