.sp 100.TL.ft RAppendix \(em The Standard I/O Library.AUD. M. Ritchie.AI.MH.PPThe standard I/O librarywas designed with the following goals in mind..IP 1.It must be as efficient as possible, both in time and in space,so that there will be no hesitation in using itno matter how critical the application..IP 2.It must be simple to use, and also free of the magicnumbers and mysterious callswhose use mars the understandability and portabilityof many programs using older packages..IP 3.The interface provided should be applicable on all machines,whether or not the programs which implement it are directly portableto other systems,or to machines other than the PDP-11 running a version of.UC UNIX ..SH1.  General Usage.PPEach program using the library must have the line.P1		#include <stdio.h>.P2which 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 beginwith an underscore.UL _to reduce the possibilityof collision with a user name.The names intended to be visible outside the package are.IP \f3stdin\f1 10The name of the standard input file.IP \f3stdout\f1 10The name of the standard output file.IP \f3stderr\f1 10The name of the standard error file.IP \f3EOF\f1 10is actually \-1, and is the value returned bythe read routines on end-of-file or error..IP \f3NULL\f1 10is a notation for the null pointer, returned bypointer-valued functionsto indicate an error.IP \f3FILE\f1 10expands to.UL struct.UL _ioband is a usefulshorthand when declaring pointersto streams..IP \f3BUFSIZ\f1 10is a number (viz. 512)of the size suitable for an I/O buffer supplied by the user.See.UL setbuf ,below..IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10.brare defined as macros.Their actions are described below;they are mentioned hereto point out that it is not possible toredeclare themand that they are not actually functions;thus, for example, they may not have breakpoints set on them..PPThe routines in this packageoffer the convenience of automatic buffer allocationand output flushing where appropriate.The names.UL stdin ,.UL stdout ,and.UL stderrare in effect constants and may not be assigned to..SH2.  Calls.nr PD .4v.LP.UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;.nr PD 0.IP.bropens the file and, if needed, allocates a buffer for it..UL filenameis a character string specifying the name..UL typeis a character string (not a single character).It may be.UL \&"r" ,.UL \&"w" ,or.UL \&"a"to indicateintent to read, write, or append.The value returned is a file pointer.If it is.UL  NULLthe attempt to open failed..ne 3.nr PD .4v.LP.UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;.nr PD 0.IP.brThe stream named by.UL ioptris closed, if necessary, and then reopenedas if by.UL fopen .If the attempt to open fails,.UL  NULLis returned,otherwise.UL ioptr ,which will now refer to the new file.Often the reopened stream is.UL stdinor.UL stdout ..nr PD .4v.LP.UL int\ getc(ioptr)\ FILE\ *ioptr;.nr PD 0.IPreturns the next character from the stream named by.UL ioptr ,which is a pointer to a file such as returned by.UL fopen ,or the name.UL stdin .The integer.UL  EOFis returned on end-of-file or whenan error occurs.The null character.UL \e0is a legal character..nr PD .4v.LP.UL int\ fgetc(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.bracts like.UL getcbut is a genuine function,not a macro,so it can be pointed to, passed as an argument, etc..nr PD .4v.LP.UL putc(c,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.br.UL putcwrites the character.UL con the output stream named by.UL ioptr ,which is a value returned from.UL fopenor perhaps.UL stdoutor.UL stderr .The character is returned as value,but.UL  EOFis returned on error..nr PD .4v.LP.UL fputc(c,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.bracts like.UL putcbut is a genuinefunction, not a macro..nr PD .4v.LP.UL fclose(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brThe file corresponding to.UL ioptris closed after any buffers are emptied.A buffer allocated by the I/O system is freed..UL fcloseis automatic on normal termination of the program..nr PD .4v.LP.UL fflush(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brAny buffered information on the (output) stream named by.UL ioptris written out.Output files are normally bufferedif and only if they are not directed to the terminal;however,.UL stderralways starts off unbuffered and remains so unless.UL setbufis used, or unless it is reopened..nr PD .4v.LP.UL exit(errcode);.nr PD 0.IP.brterminates the process and returns its argument as statusto the parent.This is a special version of the routinewhich calls.UL fflushfor each output file.To terminate without flushing,use.UL _exit ..nr PD .4v.LP.UL feof(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brreturns non-zero when end-of-filehas occurred on the specified input stream..nr PD .4v.LP.UL ferror(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brreturns non-zero when an error has occurred while readingor writing the named stream.The error indication lasts until the file has been closed..nr PD .4v.LP.UL getchar();.nr PD 0.IP.bris identical to.UL getc(stdin) ..nr PD .4v.LP.UL putchar(c);.nr PD 0.IP.bris identical to.UL putc(c,\ stdout) ..nr PD .4v.nr PD .4v.ne 2.LP.UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;.nr PD 0.IP.brreads up to.UL n-1characters from the stream.UL ioptrinto the character pointer.UL s .The read terminates with a newline character.The newline character is placed in the bufferfollowed by a null character..UL fgetsreturns the first argument,or.UL  NULLif error or end-of-file occurred..nr PD .4v.nr PD .4v.LP.UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;.nr PD 0.IP.brwrites the null-terminated string (character array).UL son the stream.UL ioptr .No newline is appended.No value is returned..nr PD .4v.LP.UL ungetc(c,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brThe argument character.UL cis pushed back on the input stream named by.UL ioptr .Only one character may be pushed back..ne 5.nr PD .4v.LP.UL printf(format,\ a1,\ ...)\ char\ *format;.br.UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;.br.UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;.br.nr PD 0.IP.UL printfwrites on the standard output..UL fprintfwrites on the named output stream..UL sprintfputs characters in the character array (string)named by.UL s .The specifications are as described in section.UL printf (3)of the.ul.UC UNIX.ulProgrammer's Manual..nr PD .4v.LP.UL scanf(format,\ a1,\ ...)\ char\ *format;.br.UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;.br.UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;.nr PD 0.IP.br.UL scanfreads from the standard input..UL fscanfreads from the named input stream..UL sscanfreads from the character stringsupplied as.UL s ..UL scanfreads characters, interpretsthem according to a format, and stores the results in its arguments.Each routine expects as argumentsa control string.UL format ,and a set of arguments,.Ieach of which must be a pointer,.Rindicating where the converted input should be stored..if t .sp .4v.UL scanfreturns as its value the number of successfully matched and assigned inputitems.This can be used to decide how many input items were found.On end of file,.UL EOFis returned; note that this is differentfrom 0, which means that the next input character does notmatch what was called for in the control string..RE.nr PD .4v.LP.UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brreads.UL nitemsof data beginning at.UL ptrfrom file.UL ioptr .No advance notificationthat binary I/O is being done is required;when, for portability reasons,it becomes required, it will be doneby adding an additional character to the mode-string on the.UL fopencall..nr PD .4v.LP.UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brLike.UL fread ,but in the other direction..nr PD .4v.LP.UL rewind(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brrewinds the streamnamed by.UL ioptr .It is not very useful except on input,since a rewound output file is still open only for output..nr PD .4v.LP.UL system(string)\ char\ *string;.nr PD 0.IP.brThe.UL stringis executed by the shell as if typed at the terminal..nr PD .4v.LP.UL getw(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brreturns the next word from the input stream named by.UL ioptr ..UL EOFis returned on end-of-file or error,but since this a perfectly goodinteger.UL feofand.UL ferrorshould be used.A ``word'' is 16 bits on the.UC PDP-11..nr PD .4v.LP.UL putw(w,\ ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brwrites the integer.UL won the named output stream..nr PD .4v.LP.UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;.nr PD 0.IP.br.UL setbufmay be used after a stream has been openedbut before I/O has started.If.UL bufis.UL NULL ,the stream will be unbuffered.Otherwise the buffer supplied will be used.It must be a character array of sufficient size:.P1char	buf[BUFSIZ];.P2.nr PD .4v.LP.UL fileno(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brreturns the integer file descriptor associated with the file..nr PD .4v.LP.UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;.nr PD 0.IP.brThe location of the next byte in the streamnamed by.UL ioptris adjusted..UL offsetis a long integer.If.UL ptrnameis 0, the offset is measured from the beginning of the file;if.UL ptrnameis 1, the offset is measured from the current read orwrite pointer;if.UL ptrnameis 2, the offset is measured from the end of the file.The routine accounts properly for any buffering.(When this routine is used on.UC UNIX \& non-systems,the offset must be a value returned from.UL ftelland the ptrname must be 0)..ne 3.nr PD .4v.LP.UL long\ ftell(ioptr)\ FILE\ *ioptr;.nr PD 0.IP.brThe byte offset, measured from the beginning of the file,associated with the named stream is returned.Any buffering is properly accounted for.(On.UC UNIX \& non-systems the value of this call is useful onlyfor handing to.UL fseek ,so as to position the file to the same place it was when.UL ftellwas called.).nr PD .4v.LP.UL getpw(uid,\ buf)\ char\ *buf;.nr PD 0.IP.brThe password file is searched for the given integer user ID.If an appropriate line is found, it is copied intothe character array.UL buf ,and 0 is returned.If no line is found corresponding to the user IDthen 1 is returned..nr PD .4v.LP.UL char\ *malloc(num);.nr PD 0.IP.brallocates.UL numbytes.The pointer returned is sufficiently well aligned to be usable for any purpose..UL NULLis returned if no space is available..nr PD .4v.LP.UL char\ *calloc(num,\ size);.nr PD 0.IP.brallocates space for.UL numitems each of size.UL size .The space is guaranteed to be set to 0 and the pointer issufficiently well aligned to be usable for any purpose..UL NULLis returned if no space is available ..nr PD .4v.LP.UL cfree(ptr)\ char\ *ptr;.nr PD 0.IP.brSpace is returned to the pool used by.UL calloc .Disorder can be expected if the pointer was not obtainedfrom.UL calloc ..nr PD .4v.LPThe following are macros whose definitions may be obtained by including.UL <ctype.h> ..nr PD .4v.LP.UL isalpha(c)returns non-zero if the argument is alphabetic..nr PD .4v.LP.UL isupper(c)returns non-zero if the argument is upper-case alphabetic..nr PD .4v.LP.UL islower(c)returns non-zero if the argument is lower-case alphabetic..nr PD .4v.LP.UL isdigit(c)returns non-zero if the argument is a digit..nr PD .4v.LP.UL isspace(c)returns non-zero if the argument is a spacing character:tab, newline, carriage return, vertical tab,form feed, space..nr PD .4v.LP.UL ispunct(c)returns non-zero if the argument isany punctuation character, i.e., not a space, letter,digit or control character..nr PD .4v.LP.UL isalnum(c)returns non-zero if the argument is a letter or a digit..nr PD .4v.LP.UL isprint(c)returns non-zero if the argument is printable \(ema letter, digit, or punctuation character..nr PD .4v.LP.UL iscntrl(c)returns non-zero if the argument is a control character..nr PD .4v.LP.UL isascii(c)returns non-zero if the argument is an ascii character, i.e., less than octal 0200..nr PD .4v.LP.UL toupper(c)returns the upper-case character corresponding to the lower-caseletter.UL c..nr PD .4v.LP.UL tolower(c)returns the lower-case character corresponding to the upper-caseletter.UL c .