%sccs.include.proprietary.roff%

@(#)p9 6.2 (Berkeley) 04/17/91

Appendix \(em The Standard I/O Library .AU D. M. Ritchie .AI AT&T Bell Laboratories Murray Hill, NJ 07974

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 to other systems, or to machines other than the PDP-11 running a version of C UNIX . 1. General Usage

Each program using the library must have the line

1 #include <stdio.h>

2 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 with an underscore _ 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 pointer-valued functions to indicate an error expands to struct _iob and is a useful shorthand when declaring pointers to streams. is a number (viz. 512) of the size suitable for an I/O buffer supplied by the user. See setbuf , below.

are defined as macros. Their actions are described below; they are mentioned here to point out that it is not possible to redeclare them 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. The names stdin , stdout , and stderr are in effect constants and may not be assigned to.

2. Calls .nr PD .4v

FILE *fopen(filename, type) char *filename, *type; .nr PD 0

opens the file and, if needed, allocates a buffer for it. filename is a character string specifying the name. type is a character string (not a single character). It may be "r" , "w" , or "a" to indicate intent to read, write, or append. The value returned is a file pointer. If it is NULL the attempt to open failed. .nr PD .4v

FILE *freopen(filename, type, ioptr) char *filename, *type; FILE *ioptr; .nr PD 0

The stream named by ioptr is closed, if necessary, and then reopened as if by fopen . If the attempt to open fails, NULL is returned, otherwise ioptr , which will now refer to the new file. Often the reopened stream is stdin or stdout . .nr PD .4v

int getc(ioptr) FILE *ioptr; .nr PD 0

returns the next character from the stream named by ioptr , which is a pointer to a file such as returned by fopen , or the name stdin . The integer EOF is returned on end-of-file or when an error occurs. The null character \e0 is a legal character. .nr PD .4v

int fgetc(ioptr) FILE *ioptr; .nr PD 0

acts like getc but is a genuine function, not a macro, so it can be pointed to, passed as an argument, etc. .nr PD .4v

putc(c, ioptr) FILE *ioptr; .nr PD 0

putc writes the character c on the output stream named by ioptr , which is a value returned from fopen or perhaps stdout or stderr . The character is returned as value, but EOF is returned on error. .nr PD .4v

fputc(c, ioptr) FILE *ioptr; .nr PD 0

acts like putc but is a genuine function, not a macro. .nr PD .4v

fclose(ioptr) FILE *ioptr; .nr PD 0

The file corresponding to ioptr is closed after any buffers are emptied. A buffer allocated by the I/O system is freed. fclose is automatic on normal termination of the program. .nr PD .4v

fflush(ioptr) FILE *ioptr; .nr PD 0

Any buffered information on the (output) stream named by ioptr is written out. Output files are normally buffered if and only if they are not directed to the terminal; however, stderr always starts off unbuffered and remains so unless setbuf is used, or unless it is reopened. .nr PD .4v

exit(errcode); .nr PD 0

terminates the process and returns its argument as status to the parent. This is a special version of the routine which calls fflush for each output file. To terminate without flushing, use _exit . .nr PD .4v

feof(ioptr) FILE *ioptr; .nr PD 0

returns non-zero when end-of-file has occurred on the specified input stream. .nr PD .4v

ferror(ioptr) FILE *ioptr; .nr PD 0

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. .nr PD .4v

getchar(); .nr PD 0

is identical to getc(stdin) . .nr PD .4v

putchar(c); .nr PD 0

is identical to putc(c, stdout) . .nr PD .4v .nr PD .4v

char *fgets(s, n, ioptr) char *s; FILE *ioptr; .nr PD 0

reads up to n-1 characters from the stream ioptr into the character pointer s . The read terminates with a newline character. The newline character is placed in the buffer followed by a null character. fgets returns the first argument, or NULL if error or end-of-file occurred. .nr PD .4v .nr PD .4v

fputs(s, ioptr) char *s; FILE *ioptr; .nr PD 0

writes the null-terminated string (character array) s on the stream ioptr . No newline is appended. No value is returned. .nr PD .4v

ungetc(c, ioptr) FILE *ioptr; .nr PD 0

The argument character c is pushed back on the input stream named by ioptr . Only one character may be pushed back. .nr PD .4v

printf(format, a1, ...) char *format;

fprintf(ioptr, format, a1, ...) FILE *ioptr; char *format;

sprintf(s, format, a1, ...)char *s, *format;

.nr PD 0

printf writes on the standard output. fprintf writes on the named output stream. sprintf puts characters in the character array (string) named by s . The specifications are as described in section printf (3) of the .ul C UNIX .ul Programmer's Manual. .nr PD .4v

scanf(format, a1, ...) char *format;

fscanf(ioptr, format, a1, ...) FILE *ioptr; char *format;

sscanf(s, format, a1, ...) char *s, *format; .nr PD 0

scanf reads from the standard input. fscanf reads from the named input stream. sscanf reads from the character string supplied as s . scanf reads characters, interprets them according to a format, and stores the results in its arguments. Each routine expects as arguments a control string format , and a set of arguments, each of which must be a pointer, .R indicating where the converted input should be stored. scanf returns as its value the number of successfully matched and assigned input items. This can be used to decide how many input items were found. On end of file, EOF 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. .nr PD .4v

fread(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr; .nr PD 0

reads nitems of data beginning at ptr from file ioptr . No advance notification 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 fopen call. .nr PD .4v

fwrite(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr; .nr PD 0

Like fread , but in the other direction. .nr PD .4v

rewind(ioptr) FILE *ioptr; .nr PD 0

rewinds the stream named by ioptr . It is not very useful except on input, since a rewound output file is still open only for output. .nr PD .4v

system(string) char *string; .nr PD 0

The string is executed by the shell as if typed at the terminal. .nr PD .4v

getw(ioptr) FILE *ioptr; .nr PD 0

returns the next word from the input stream named by ioptr . EOF is returned on end-of-file or error, but since this a perfectly good integer feof and ferror should be used. A ``word'' is 16 bits on the C PDP-11. .nr PD .4v

putw(w, ioptr) FILE *ioptr; .nr PD 0

writes the integer w on the named output stream. .nr PD .4v

setbuf(ioptr, buf) FILE *ioptr; char *buf; .nr PD 0

setbuf may be used after a stream has been opened but before I/O has started. If buf is NULL , the stream will be unbuffered. Otherwise the buffer supplied will be used. It must be a character array of sufficient size:

1 char buf[BUFSIZ];

2 .nr PD .4v

fileno(ioptr) FILE *ioptr; .nr PD 0

returns the integer file descriptor associated with the file. .nr PD .4v

fseek(ioptr, offset, ptrname) FILE *ioptr; long offset; .nr PD 0

The location of the next byte in the stream named by ioptr is adjusted. offset is a long integer. If ptrname is 0, the offset is measured from the beginning of the file; if ptrname is 1, the offset is measured from the current read or write pointer; if ptrname 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 C UNIX non- systems, the offset must be a value returned from ftell and the ptrname must be 0). .nr PD .4v

long ftell(ioptr) FILE *ioptr; .nr PD 0

The byte offset, measured from the beginning of the file, associated with the named stream is returned. Any buffering is properly accounted for. (On C UNIX non- systems the value of this call is useful only for handing to fseek , so as to position the file to the same place it was when ftell was called.) .nr PD .4v

getpw(uid, buf) char *buf; .nr PD 0

The password file is searched for the given integer user ID. If an appropriate line is found, it is copied into the character array buf , and 0 is returned. If no line is found corresponding to the user ID then 1 is returned. .nr PD .4v

char *malloc(num); .nr PD 0

allocates num bytes. The pointer returned is sufficiently well aligned to be usable for any purpose. NULL is returned if no space is available. .nr PD .4v

char *calloc(num, size); .nr PD 0

allocates space for num items each of size size . The space is guaranteed to be set to 0 and the pointer is sufficiently well aligned to be usable for any purpose. NULL is returned if no space is available . .nr PD .4v

cfree(ptr) char *ptr; .nr PD 0

Space is returned to the pool used by calloc . Disorder can be expected if the pointer was not obtained from calloc . .nr PD .4v

The following are macros whose definitions may be obtained by including <ctype.h> . .nr PD .4v

isalpha(c) returns non-zero if the argument is alphabetic. .nr PD .4v

isupper(c) returns non-zero if the argument is upper-case alphabetic. .nr PD .4v

islower(c) returns non-zero if the argument is lower-case alphabetic. .nr PD .4v

isdigit(c) returns non-zero if the argument is a digit. .nr PD .4v

isspace(c) returns non-zero if the argument is a spacing character: tab, newline, carriage return, vertical tab, form feed, space. .nr PD .4v

ispunct(c) returns non-zero if the argument is any punctuation character, i.e., not a space, letter, digit or control character. .nr PD .4v

isalnum(c) returns non-zero if the argument is a letter or a digit. .nr PD .4v

isprint(c) returns non-zero if the argument is printable \(em a letter, digit, or punctuation character. .nr PD .4v

iscntrl(c) returns non-zero if the argument is a control character. .nr PD .4v

isascii(c) returns non-zero if the argument is an ascii character, i.e., less than octal 0200. .nr PD .4v

toupper(c) returns the upper-case character corresponding to the lower-case letter c. .nr PD .4v

tolower(c) returns the lower-case character corresponding to the upper-case letter c .