1 .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are
7 .\" Redistributions of source code and documentation must retain the above
8 .\" copyright notice, this list of conditions and the following
11 .\" Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
18 .\" This product includes software developed or owned by Caldera
19 .\" International, Inc. Neither the name of Caldera International, Inc.
20 .\" nor the names of other contributors may be used to endorse or promote
21 .\" products derived from this software without specific prior written
24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
25 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28 .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 .\" @(#)p9 8.1 (Berkeley) 6/8/93
44 Appendix \(em The Standard I/O Library
48 AT&T Bell Laboratories
51 The standard I/O library
52 was designed with the following goals in mind.
54 It must be as efficient as possible, both in time and in space,
55 so that there will be no hesitation in using it
56 no matter how critical the application.
58 It must be simple to use, and also free of the magic
59 numbers and mysterious calls
60 whose use mars the understandability and portability
61 of many programs using older packages.
63 The interface provided should be applicable on all machines,
64 whether or not the programs which implement it are directly portable
66 or to machines other than the PDP-11 running a version of
71 Each program using the library must have the line
75 which defines certain macros and variables.
76 The routines are in the normal C library,
77 so no special library argument is needed for loading.
78 All names in the include file intended only for internal use begin
81 to reduce the possibility
82 of collision with a user name.
83 The names intended to be visible outside the package are
85 The name of the standard input file
87 The name of the standard output file
89 The name of the standard error file
91 is actually \-1, and is the value returned by
92 the read routines on end-of-file or error.
94 is a notation for the null pointer, returned by
95 pointer-valued functions
102 shorthand when declaring pointers
105 is a number (viz. 512)
106 of the size suitable for an I/O buffer supplied by the user.
110 .IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
112 are defined as macros.
113 Their actions are described below;
114 they are mentioned here
115 to point out that it is not possible to
117 and that they are not actually functions;
118 thus, for example, they may not have breakpoints set on them.
120 The routines in this package
121 offer the convenience of automatic buffer allocation
122 and output flushing where appropriate.
128 are in effect constants and may not be assigned to.
133 .UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
137 opens the file and, if needed, allocates a buffer for it.
139 is a character string specifying the name.
141 is a character string (not a single character).
148 intent to read, write, or append.
149 The value returned is a file pointer.
152 the attempt to open failed.
156 .UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
162 is closed, if necessary, and then reopened
165 If the attempt to open fails,
170 which will now refer to the new file.
171 Often the reopened stream is
177 .UL int\ getc(ioptr)\ FILE\ *ioptr;
180 returns the next character from the stream named by
182 which is a pointer to a file such as returned by
188 is returned on end-of-file or when
192 is a legal character.
195 .UL int\ fgetc(ioptr)\ FILE\ *ioptr;
201 but is a genuine function,
203 so it can be pointed to, passed as an argument, etc.
206 .UL putc(c,\ ioptr)\ FILE\ *ioptr;
213 on the output stream named by
215 which is a value returned from
221 The character is returned as value,
224 is returned on error.
227 .UL fputc(c,\ ioptr)\ FILE\ *ioptr;
234 function, not a macro.
237 .UL fclose(ioptr)\ FILE\ *ioptr;
241 The file corresponding to
243 is closed after any buffers are emptied.
244 A buffer allocated by the I/O system is freed.
246 is automatic on normal termination of the program.
249 .UL fflush(ioptr)\ FILE\ *ioptr;
253 Any buffered information on the (output) stream named by
256 Output files are normally buffered
257 if and only if they are not directed to the terminal;
260 always starts off unbuffered and remains so unless
262 is used, or unless it is reopened.
269 terminates the process and returns its argument as status
271 This is a special version of the routine
274 for each output file.
275 To terminate without flushing,
280 .UL feof(ioptr)\ FILE\ *ioptr;
284 returns non-zero when end-of-file
285 has occurred on the specified input stream.
288 .UL ferror(ioptr)\ FILE\ *ioptr;
292 returns non-zero when an error has occurred while reading
293 or writing the named stream.
294 The error indication lasts until the file has been closed.
310 .UL putc(c,\ stdout) .
315 .UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
321 characters from the stream
323 into the character pointer
325 The read terminates with a newline character.
326 The newline character is placed in the buffer
327 followed by a null character.
329 returns the first argument,
332 if error or end-of-file occurred.
336 .UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
340 writes the null-terminated string (character array)
344 No newline is appended.
345 No value is returned.
348 .UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
352 The argument character
354 is pushed back on the input stream named by
356 Only one character may be pushed back.
360 .UL printf(format,\ a1,\ ...)\ char\ *format;
362 .UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
364 .UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
369 writes on the standard output.
371 writes on the named output stream.
373 puts characters in the character array (string)
376 The specifications are as described in section
385 .UL scanf(format,\ a1,\ ...)\ char\ *format;
387 .UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
389 .UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
394 reads from the standard input.
396 reads from the named input stream.
398 reads from the character string
402 reads characters, interprets
403 them according to a format, and stores the results in its arguments.
404 Each routine expects as arguments
407 and a set of arguments,
409 each of which must be a pointer,
411 indicating where the converted input should be stored.
414 returns as its value the number of successfully matched and assigned input
416 This can be used to decide how many input items were found.
419 is returned; note that this is different
420 from 0, which means that the next input character does not
421 match what was called for in the control string.
424 .UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
434 No advance notification
435 that binary I/O is being done is required;
436 when, for portability reasons,
437 it becomes required, it will be done
438 by adding an additional character to the mode-string on the
443 .UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
449 but in the other direction.
452 .UL rewind(ioptr)\ FILE\ *ioptr;
459 It is not very useful except on input,
460 since a rewound output file is still open only for output.
463 .UL system(string)\ char\ *string;
469 is executed by the shell as if typed at the terminal.
472 .UL getw(ioptr)\ FILE\ *ioptr;
476 returns the next word from the input stream named by
479 is returned on end-of-file or error,
480 but since this a perfectly good
486 A ``word'' is 16 bits on the
490 .UL putw(w,\ ioptr)\ FILE\ *ioptr;
496 on the named output stream.
499 .UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
504 may be used after a stream has been opened
505 but before I/O has started.
510 the stream will be unbuffered.
511 Otherwise the buffer supplied will be used.
512 It must be a character array of sufficient size:
518 .UL fileno(ioptr)\ FILE\ *ioptr;
522 returns the integer file descriptor associated with the file.
525 .UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
529 The location of the next byte in the stream
537 is 0, the offset is measured from the beginning of the file;
540 is 1, the offset is measured from the current read or
544 is 2, the offset is measured from the end of the file.
545 The routine accounts properly for any buffering.
546 (When this routine is used on
549 the offset must be a value returned from
551 and the ptrname must be 0).
555 .UL long\ ftell(ioptr)\ FILE\ *ioptr;
559 The byte offset, measured from the beginning of the file,
560 associated with the named stream is returned.
561 Any buffering is properly accounted for.
564 systems the value of this call is useful only
567 so as to position the file to the same place it was when
572 .UL getpw(uid,\ buf)\ char\ *buf;
576 The password file is searched for the given integer user ID.
577 If an appropriate line is found, it is copied into
581 If no line is found corresponding to the user ID
585 .UL char\ *malloc(num);
592 The pointer returned is sufficiently well aligned to be usable for any purpose.
594 is returned if no space is available.
597 .UL char\ *calloc(num,\ size);
605 The space is guaranteed to be set to 0 and the pointer is
606 sufficiently well aligned to be usable for any purpose.
608 is returned if no space is available .
611 .UL cfree(ptr)\ char\ *ptr;
615 Space is returned to the pool used by
617 Disorder can be expected if the pointer was not obtained
622 The following are macros whose definitions may be obtained by including
627 returns non-zero if the argument is alphabetic.
631 returns non-zero if the argument is upper-case alphabetic.
635 returns non-zero if the argument is lower-case alphabetic.
639 returns non-zero if the argument is a digit.
643 returns non-zero if the argument is a spacing character:
644 tab, newline, carriage return, vertical tab,
649 returns non-zero if the argument is
650 any punctuation character, i.e., not a space, letter,
651 digit or control character.
655 returns non-zero if the argument is a letter or a digit.
659 returns non-zero if the argument is printable \(em
660 a letter, digit, or punctuation character.
664 returns non-zero if the argument is a control character.
668 returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
672 returns the upper-case character corresponding to the lower-case
678 returns the lower-case character corresponding to the upper-case
projects / FreeBSD / releng / 9.2.git / blob