.\" @(#)p9 6.1 (Berkeley) 4/25/86
Appendix \(em The Standard I/O Library
was designed with the following goals in mind.
It must be as efficient as possible, both in time and in space,
so that there will be no hesitation in using it
no matter how critical the application.
It must be simple to use, and also free of the magic
numbers and mysterious calls
whose use mars the understandability and portability
of many programs using older packages.
The interface provided should be applicable on all machines,
whether or not the programs which implement it are directly portable
or to machines other than the PDP-11 running a version of
Each program using the library must have the line
which defines certain macros and variables.
The routines are in the normal C library,
so no special library argument is needed for loading.
All names in the include file intended only for internal use begin
to reduce the possibility
of collision with a user name.
The names intended to be visible outside the package are
The name of the standard input file
The name of the standard output file
The name of the standard error file
is actually \-1, and is the value returned by
the read routines on end-of-file or error.
is a notation for the null pointer, returned by
shorthand when declaring pointers
of the size suitable for an I/O buffer supplied by the user.
.IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
Their actions are described below;
to point out that it is not possible to
and that they are not actually functions;
thus, for example, they may not have breakpoints set on them.
The routines in this package
offer the convenience of automatic buffer allocation
and output flushing where appropriate.
are in effect constants and may not be assigned to.
.UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
opens the file and, if needed, allocates a buffer for it.
is a character string specifying the name.
is a character string (not a single character).
intent to read, write, or append.
The value returned is a file pointer.
the attempt to open failed.
.UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
is closed, if necessary, and then reopened
If the attempt to open fails,
which will now refer to the new file.
Often the reopened stream is
.UL int\ getc(ioptr)\ FILE\ *ioptr;
returns the next character from the stream named by
which is a pointer to a file such as returned by
is returned on end-of-file or when
.UL int\ fgetc(ioptr)\ FILE\ *ioptr;
but is a genuine function,
so it can be pointed to, passed as an argument, etc.
.UL putc(c,\ ioptr)\ FILE\ *ioptr;
on the output stream named by
which is a value returned from
The character is returned as value,
.UL fputc(c,\ ioptr)\ FILE\ *ioptr;
.UL fclose(ioptr)\ FILE\ *ioptr;
The file corresponding to
is closed after any buffers are emptied.
A buffer allocated by the I/O system is freed.
is automatic on normal termination of the program.
.UL fflush(ioptr)\ FILE\ *ioptr;
Any buffered information on the (output) stream named by
Output files are normally buffered
if and only if they are not directed to the terminal;
always starts off unbuffered and remains so unless
is used, or unless it is reopened.
terminates the process and returns its argument as status
This is a special version of the routine
To terminate without flushing,
.UL feof(ioptr)\ FILE\ *ioptr;
returns non-zero when end-of-file
has occurred on the specified input stream.
.UL ferror(ioptr)\ FILE\ *ioptr;
returns non-zero when an error has occurred while reading
or writing the named stream.
The error indication lasts until the file has been closed.
.UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
characters from the stream
into the character pointer
The read terminates with a newline character.
The newline character is placed in the buffer
followed by a null character.
returns the first argument,
if error or end-of-file occurred.
.UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
writes the null-terminated string (character array)
.UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
is pushed back on the input stream named by
Only one character may be pushed back.
.UL printf(format,\ a1,\ ...)\ char\ *format;
.UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
.UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
writes on the standard output.
writes on the named output stream.
puts characters in the character array (string)
The specifications are as described in section
.UL scanf(format,\ a1,\ ...)\ char\ *format;
.UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
.UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
reads from the standard input.
reads from the named input stream.
reads from the character string
reads characters, interprets
them according to a format, and stores the results in its arguments.
Each routine expects as arguments
each of which must be a pointer,
indicating where the converted input should be stored.
returns as its value the number of successfully matched and assigned input
This can be used to decide how many input items were found.
is returned; note that this is different
from 0, which means that the next input character does not
match what was called for in the control string.
.UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
that binary I/O is being done is required;
when, for portability reasons,
it becomes required, it will be done
by adding an additional character to the mode-string on the
.UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
but in the other direction.
.UL rewind(ioptr)\ FILE\ *ioptr;
It is not very useful except on input,
since a rewound output file is still open only for output.
.UL system(string)\ char\ *string;
is executed by the shell as if typed at the terminal.
.UL getw(ioptr)\ FILE\ *ioptr;
returns the next word from the input stream named by
is returned on end-of-file or error,
but since this a perfectly good
A ``word'' is 16 bits on the
.UL putw(w,\ ioptr)\ FILE\ *ioptr;
on the named output stream.
.UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
may be used after a stream has been opened
but before I/O has started.
the stream will be unbuffered.
Otherwise the buffer supplied will be used.
It must be a character array of sufficient size:
.UL fileno(ioptr)\ FILE\ *ioptr;
returns the integer file descriptor associated with the file.
.UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
The location of the next byte in the stream
is 0, the offset is measured from the beginning of the file;
is 1, the offset is measured from the current read or
is 2, the offset is measured from the end of the file.
The routine accounts properly for any buffering.
(When this routine is used on
the offset must be a value returned from
and the ptrname must be 0).
.UL long\ ftell(ioptr)\ FILE\ *ioptr;
The byte offset, measured from the beginning of the file,
associated with the named stream is returned.
Any buffering is properly accounted for.
systems the value of this call is useful only
so as to position the file to the same place it was when
.UL getpw(uid,\ buf)\ char\ *buf;
The password file is searched for the given integer user ID.
If an appropriate line is found, it is copied into
If no line is found corresponding to the user ID
The pointer returned is sufficiently well aligned to be usable for any purpose.
is returned if no space is available.
.UL char\ *calloc(num,\ size);
The space is guaranteed to be set to 0 and the pointer is
sufficiently well aligned to be usable for any purpose.
is returned if no space is available .
.UL cfree(ptr)\ char\ *ptr;
Space is returned to the pool used by
Disorder can be expected if the pointer was not obtained
The following are macros whose definitions may be obtained by including
returns non-zero if the argument is alphabetic.
returns non-zero if the argument is upper-case alphabetic.
returns non-zero if the argument is lower-case alphabetic.
returns non-zero if the argument is a digit.
returns non-zero if the argument is a spacing character:
tab, newline, carriage return, vertical tab,
returns non-zero if the argument is
any punctuation character, i.e., not a space, letter,
digit or control character.
returns non-zero if the argument is a letter or a digit.
returns non-zero if the argument is printable \(em
a letter, digit, or punctuation character.
returns non-zero if the argument is a control character.
returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
returns the upper-case character corresponding to the lower-case
returns the lower-case character corresponding to the upper-case