Return to p9 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 03.uprog

Annotation of 43BSDReno/share/doc/ps2/03.uprog/p9, revision 1.1

1.1     ! root        1: .\"    @(#)p9  6.1 (Berkeley) 4/25/86
        !             2: .\"
        !             3: .sp 100
        !             4: .TL
        !             5: .ft R
        !             6: Appendix \(em The Standard I/O Library
        !             7: .AU
        !             8: D. M. Ritchie
        !             9: .AI
        !            10: .MH
        !            11: .PP
        !            12: The standard I/O library
        !            13: was designed with the following goals in mind.
        !            14: .IP 1.
        !            15: It must be as efficient as possible, both in time and in space,
        !            16: so that there will be no hesitation in using it
        !            17: no matter how critical the application.
        !            18: .IP 2.
        !            19: It must be simple to use, and also free of the magic
        !            20: numbers and mysterious calls
        !            21: whose use mars the understandability and portability
        !            22: of many programs using older packages.
        !            23: .IP 3.
        !            24: The interface provided should be applicable on all machines,
        !            25: whether or not the programs which implement it are directly portable
        !            26: to other systems,
        !            27: or to machines other than the PDP-11 running a version of
        !            28: .UC UNIX .
        !            29: .SH
        !            30: 1.  General Usage
        !            31: .PP
        !            32: Each program using the library must have the line
        !            33: .P1
        !            34:                #include <stdio.h>
        !            35: .P2
        !            36: which defines certain macros and variables.
        !            37: The routines are in the normal C library,
        !            38: so no special library argument is needed for loading.
        !            39: All names in the include file intended only for internal use begin
        !            40: with an underscore
        !            41: .UL _
        !            42: to reduce the possibility
        !            43: of collision with a user name.
        !            44: The names intended to be visible outside the package are
        !            45: .IP \f3stdin\f1 10
        !            46: The name of the standard input file
        !            47: .IP \f3stdout\f1 10
        !            48: The name of the standard output file
        !            49: .IP \f3stderr\f1 10
        !            50: The name of the standard error file
        !            51: .IP \f3EOF\f1 10
        !            52: is actually \-1, and is the value returned by
        !            53: the read routines on end-of-file or error.
        !            54: .IP \f3NULL\f1 10
        !            55: is a notation for the null pointer, returned by
        !            56: pointer-valued functions
        !            57: to indicate an error
        !            58: .IP \f3FILE\f1 10
        !            59: expands to
        !            60: .UL struct
        !            61: .UL _iob
        !            62: and is a useful
        !            63: shorthand when declaring pointers
        !            64: to streams.
        !            65: .IP \f3BUFSIZ\f1 10
        !            66: is a number (viz. 512)
        !            67: of the size suitable for an I/O buffer supplied by the user.
        !            68: See
        !            69: .UL setbuf ,
        !            70: below.
        !            71: .IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
        !            72: .br
        !            73: are defined as macros.
        !            74: Their actions are described below;
        !            75: they are mentioned here
        !            76: to point out that it is not possible to
        !            77: redeclare them
        !            78: and that they are not actually functions;
        !            79: thus, for example, they may not have breakpoints set on them.
        !            80: .PP
        !            81: The routines in this package
        !            82: offer the convenience of automatic buffer allocation
        !            83: and output flushing where appropriate.
        !            84: The names
        !            85: .UL stdin ,
        !            86: .UL stdout ,
        !            87: and
        !            88: .UL stderr
        !            89: are in effect constants and may not be assigned to.
        !            90: .SH
        !            91: 2.  Calls
        !            92: .nr PD .4v
        !            93: .LP
        !            94: .UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
        !            95: .nr PD 0
        !            96: .IP
        !            97: .br
        !            98: opens the file and, if needed, allocates a buffer for it.
        !            99: .UL filename
        !           100: is a character string specifying the name.
        !           101: .UL type
        !           102: is a character string (not a single character).
        !           103: It may be
        !           104: .UL \&"r" ,
        !           105: .UL \&"w" ,
        !           106: or
        !           107: .UL \&"a"
        !           108: to indicate
        !           109: intent to read, write, or append.
        !           110: The value returned is a file pointer.
        !           111: If it is
        !           112: .UL  NULL
        !           113: the attempt to open failed.
        !           114: .ne 3
        !           115: .nr PD .4v
        !           116: .LP
        !           117: .UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
        !           118: .nr PD 0
        !           119: .IP
        !           120: .br
        !           121: The stream named by
        !           122: .UL ioptr
        !           123: is closed, if necessary, and then reopened
        !           124: as if by
        !           125: .UL fopen .
        !           126: If the attempt to open fails,
        !           127: .UL  NULL
        !           128: is returned,
        !           129: otherwise
        !           130: .UL ioptr ,
        !           131: which will now refer to the new file.
        !           132: Often the reopened stream is
        !           133: .UL stdin
        !           134: or
        !           135: .UL stdout .
        !           136: .nr PD .4v
        !           137: .LP
        !           138: .UL int\ getc(ioptr)\ FILE\ *ioptr;
        !           139: .nr PD 0
        !           140: .IP
        !           141: returns the next character from the stream named by
        !           142: .UL ioptr ,
        !           143: which is a pointer to a file such as returned by
        !           144: .UL fopen ,
        !           145: or the name
        !           146: .UL stdin .
        !           147: The integer
        !           148: .UL  EOF
        !           149: is returned on end-of-file or when
        !           150: an error occurs.
        !           151: The null character
        !           152: .UL \e0
        !           153: is a legal character.
        !           154: .nr PD .4v
        !           155: .LP
        !           156: .UL int\ fgetc(ioptr)\ FILE\ *ioptr;
        !           157: .nr PD 0
        !           158: .IP
        !           159: .br
        !           160: acts like
        !           161: .UL getc
        !           162: but is a genuine function,
        !           163: not a macro,
        !           164: so it can be pointed to, passed as an argument, etc.
        !           165: .nr PD .4v
        !           166: .LP
        !           167: .UL putc(c,\ ioptr)\ FILE\ *ioptr;
        !           168: .nr PD 0
        !           169: .IP
        !           170: .br
        !           171: .UL putc
        !           172: writes the character
        !           173: .UL c
        !           174: on the output stream named by
        !           175: .UL ioptr ,
        !           176: which is a value returned from
        !           177: .UL fopen
        !           178: or perhaps
        !           179: .UL stdout
        !           180: or
        !           181: .UL stderr .
        !           182: The character is returned as value,
        !           183: but
        !           184: .UL  EOF
        !           185: is returned on error.
        !           186: .nr PD .4v
        !           187: .LP
        !           188: .UL fputc(c,\ ioptr)\ FILE\ *ioptr;
        !           189: .nr PD 0
        !           190: .IP
        !           191: .br
        !           192: acts like
        !           193: .UL putc
        !           194: but is a genuine
        !           195: function, not a macro.
        !           196: .nr PD .4v
        !           197: .LP
        !           198: .UL fclose(ioptr)\ FILE\ *ioptr;
        !           199: .nr PD 0
        !           200: .IP
        !           201: .br
        !           202: The file corresponding to
        !           203: .UL ioptr
        !           204: is closed after any buffers are emptied.
        !           205: A buffer allocated by the I/O system is freed.
        !           206: .UL fclose
        !           207: is automatic on normal termination of the program.
        !           208: .nr PD .4v
        !           209: .LP
        !           210: .UL fflush(ioptr)\ FILE\ *ioptr;
        !           211: .nr PD 0
        !           212: .IP
        !           213: .br
        !           214: Any buffered information on the (output) stream named by
        !           215: .UL ioptr
        !           216: is written out.
        !           217: Output files are normally buffered
        !           218: if and only if they are not directed to the terminal;
        !           219: however,
        !           220: .UL stderr
        !           221: always starts off unbuffered and remains so unless
        !           222: .UL setbuf
        !           223: is used, or unless it is reopened.
        !           224: .nr PD .4v
        !           225: .LP
        !           226: .UL exit(errcode);
        !           227: .nr PD 0
        !           228: .IP
        !           229: .br
        !           230: terminates the process and returns its argument as status
        !           231: to the parent.
        !           232: This is a special version of the routine
        !           233: which calls
        !           234: .UL fflush
        !           235: for each output file.
        !           236: To terminate without flushing,
        !           237: use
        !           238: .UL _exit .
        !           239: .nr PD .4v
        !           240: .LP
        !           241: .UL feof(ioptr)\ FILE\ *ioptr;
        !           242: .nr PD 0
        !           243: .IP
        !           244: .br
        !           245: returns non-zero when end-of-file
        !           246: has occurred on the specified input stream.
        !           247: .nr PD .4v
        !           248: .LP
        !           249: .UL ferror(ioptr)\ FILE\ *ioptr;
        !           250: .nr PD 0
        !           251: .IP
        !           252: .br
        !           253: returns non-zero when an error has occurred while reading
        !           254: or writing the named stream.
        !           255: The error indication lasts until the file has been closed.
        !           256: .nr PD .4v
        !           257: .LP
        !           258: .UL getchar();
        !           259: .nr PD 0
        !           260: .IP
        !           261: .br
        !           262: is identical to
        !           263: .UL getc(stdin) .
        !           264: .nr PD .4v
        !           265: .LP
        !           266: .UL putchar(c);
        !           267: .nr PD 0
        !           268: .IP
        !           269: .br
        !           270: is identical to
        !           271: .UL putc(c,\ stdout) .
        !           272: .nr PD .4v
        !           273: .nr PD .4v
        !           274: .ne 2
        !           275: .LP
        !           276: .UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
        !           277: .nr PD 0
        !           278: .IP
        !           279: .br
        !           280: reads up to
        !           281: .UL n-1
        !           282: characters from the stream
        !           283: .UL ioptr
        !           284: into the character pointer
        !           285: .UL s .
        !           286: The read terminates with a newline character.
        !           287: The newline character is placed in the buffer
        !           288: followed by a null character.
        !           289: .UL fgets
        !           290: returns the first argument,
        !           291: or
        !           292: .UL  NULL
        !           293: if error or end-of-file occurred.
        !           294: .nr PD .4v
        !           295: .nr PD .4v
        !           296: .LP
        !           297: .UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
        !           298: .nr PD 0
        !           299: .IP
        !           300: .br
        !           301: writes the null-terminated string (character array)
        !           302: .UL s
        !           303: on the stream
        !           304: .UL ioptr .
        !           305: No newline is appended.
        !           306: No value is returned.
        !           307: .nr PD .4v
        !           308: .LP
        !           309: .UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
        !           310: .nr PD 0
        !           311: .IP
        !           312: .br
        !           313: The argument character
        !           314: .UL c
        !           315: is pushed back on the input stream named by
        !           316: .UL ioptr .
        !           317: Only one character may be pushed back.
        !           318: .ne 5
        !           319: .nr PD .4v
        !           320: .LP
        !           321: .UL printf(format,\ a1,\ ...)\ char\ *format;
        !           322: .br
        !           323: .UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
        !           324: .br
        !           325: .UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
        !           326: .br
        !           327: .nr PD 0
        !           328: .IP
        !           329: .UL printf
        !           330: writes on the standard output.
        !           331: .UL fprintf
        !           332: writes on the named output stream.
        !           333: .UL sprintf
        !           334: puts characters in the character array (string)
        !           335: named by
        !           336: .UL s .
        !           337: The specifications are as described in section
        !           338: .UL printf (3)
        !           339: of the
        !           340: .ul
        !           341: .UC UNIX
        !           342: .ul
        !           343: Programmer's Manual.
        !           344: .nr PD .4v
        !           345: .LP
        !           346: .UL scanf(format,\ a1,\ ...)\ char\ *format;
        !           347: .br
        !           348: .UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
        !           349: .br
        !           350: .UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
        !           351: .nr PD 0
        !           352: .IP
        !           353: .br
        !           354: .UL scanf
        !           355: reads from the standard input.
        !           356: .UL fscanf
        !           357: reads from the named input stream.
        !           358: .UL sscanf
        !           359: reads from the character string
        !           360: supplied as
        !           361: .UL s .
        !           362: .UL scanf
        !           363: reads characters, interprets
        !           364: them according to a format, and stores the results in its arguments.
        !           365: Each routine expects as arguments
        !           366: a control string
        !           367: .UL format ,
        !           368: and a set of arguments,
        !           369: .I
        !           370: each of which must be a pointer,
        !           371: .R
        !           372: indicating where the converted input should be stored.
        !           373: .if t .sp .4v
        !           374: .UL scanf
        !           375: returns as its value the number of successfully matched and assigned input
        !           376: items.
        !           377: This can be used to decide how many input items were found.
        !           378: On end of file,
        !           379: .UL EOF
        !           380: is returned; note that this is different
        !           381: from 0, which means that the next input character does not
        !           382: match what was called for in the control string.
        !           383: .RE
        !           384: .nr PD .4v
        !           385: .LP
        !           386: .UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
        !           387: .nr PD 0
        !           388: .IP
        !           389: .br
        !           390: reads
        !           391: .UL nitems
        !           392: of data beginning at
        !           393: .UL ptr
        !           394: from file
        !           395: .UL ioptr .
        !           396: No advance notification
        !           397: that binary I/O is being done is required;
        !           398: when, for portability reasons,
        !           399: it becomes required, it will be done
        !           400: by adding an additional character to the mode-string on the
        !           401: .UL fopen
        !           402: call.
        !           403: .nr PD .4v
        !           404: .LP
        !           405: .UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
        !           406: .nr PD 0
        !           407: .IP
        !           408: .br
        !           409: Like
        !           410: .UL fread ,
        !           411: but in the other direction.
        !           412: .nr PD .4v
        !           413: .LP
        !           414: .UL rewind(ioptr)\ FILE\ *ioptr;
        !           415: .nr PD 0
        !           416: .IP
        !           417: .br
        !           418: rewinds the stream
        !           419: named by
        !           420: .UL ioptr .
        !           421: It is not very useful except on input,
        !           422: since a rewound output file is still open only for output.
        !           423: .nr PD .4v
        !           424: .LP
        !           425: .UL system(string)\ char\ *string;
        !           426: .nr PD 0
        !           427: .IP
        !           428: .br
        !           429: The
        !           430: .UL string
        !           431: is executed by the shell as if typed at the terminal.
        !           432: .nr PD .4v
        !           433: .LP
        !           434: .UL getw(ioptr)\ FILE\ *ioptr;
        !           435: .nr PD 0
        !           436: .IP
        !           437: .br
        !           438: returns the next word from the input stream named by
        !           439: .UL ioptr .
        !           440: .UL EOF
        !           441: is returned on end-of-file or error,
        !           442: but since this a perfectly good
        !           443: integer
        !           444: .UL feof
        !           445: and
        !           446: .UL ferror
        !           447: should be used.
        !           448: A ``word'' is 16 bits on the
        !           449: .UC PDP-11.
        !           450: .nr PD .4v
        !           451: .LP
        !           452: .UL putw(w,\ ioptr)\ FILE\ *ioptr;
        !           453: .nr PD 0
        !           454: .IP
        !           455: .br
        !           456: writes the integer
        !           457: .UL w
        !           458: on the named output stream.
        !           459: .nr PD .4v
        !           460: .LP
        !           461: .UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
        !           462: .nr PD 0
        !           463: .IP
        !           464: .br
        !           465: .UL setbuf
        !           466: may be used after a stream has been opened
        !           467: but before I/O has started.
        !           468: If
        !           469: .UL buf
        !           470: is
        !           471: .UL NULL ,
        !           472: the stream will be unbuffered.
        !           473: Otherwise the buffer supplied will be used.
        !           474: It must be a character array of sufficient size:
        !           475: .P1
        !           476: char   buf[BUFSIZ];
        !           477: .P2
        !           478: .nr PD .4v
        !           479: .LP
        !           480: .UL fileno(ioptr)\ FILE\ *ioptr;
        !           481: .nr PD 0
        !           482: .IP
        !           483: .br
        !           484: returns the integer file descriptor associated with the file.
        !           485: .nr PD .4v
        !           486: .LP
        !           487: .UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
        !           488: .nr PD 0
        !           489: .IP
        !           490: .br
        !           491: The location of the next byte in the stream
        !           492: named by
        !           493: .UL ioptr
        !           494: is adjusted.
        !           495: .UL offset
        !           496: is a long integer.
        !           497: If
        !           498: .UL ptrname
        !           499: is 0, the offset is measured from the beginning of the file;
        !           500: if
        !           501: .UL ptrname
        !           502: is 1, the offset is measured from the current read or
        !           503: write pointer;
        !           504: if
        !           505: .UL ptrname
        !           506: is 2, the offset is measured from the end of the file.
        !           507: The routine accounts properly for any buffering.
        !           508: (When this routine is used on
        !           509: .UC UNIX \& non-
        !           510: systems,
        !           511: the offset must be a value returned from
        !           512: .UL ftell
        !           513: and the ptrname must be 0).
        !           514: .ne 3
        !           515: .nr PD .4v
        !           516: .LP
        !           517: .UL long\ ftell(ioptr)\ FILE\ *ioptr;
        !           518: .nr PD 0
        !           519: .IP
        !           520: .br
        !           521: The byte offset, measured from the beginning of the file,
        !           522: associated with the named stream is returned.
        !           523: Any buffering is properly accounted for.
        !           524: (On
        !           525: .UC UNIX \& non-
        !           526: systems the value of this call is useful only
        !           527: for handing to
        !           528: .UL fseek ,
        !           529: so as to position the file to the same place it was when
        !           530: .UL ftell
        !           531: was called.)
        !           532: .nr PD .4v
        !           533: .LP
        !           534: .UL getpw(uid,\ buf)\ char\ *buf;
        !           535: .nr PD 0
        !           536: .IP
        !           537: .br
        !           538: The password file is searched for the given integer user ID.
        !           539: If an appropriate line is found, it is copied into
        !           540: the character array
        !           541: .UL buf ,
        !           542: and 0 is returned.
        !           543: If no line is found corresponding to the user ID
        !           544: then 1 is returned.
        !           545: .nr PD .4v
        !           546: .LP
        !           547: .UL char\ *malloc(num);
        !           548: .nr PD 0
        !           549: .IP
        !           550: .br
        !           551: allocates
        !           552: .UL num
        !           553: bytes.
        !           554: The pointer returned is sufficiently well aligned to be usable for any purpose.
        !           555: .UL NULL
        !           556: is returned if no space is available.
        !           557: .nr PD .4v
        !           558: .LP
        !           559: .UL char\ *calloc(num,\ size);
        !           560: .nr PD 0
        !           561: .IP
        !           562: .br
        !           563: allocates space for
        !           564: .UL num
        !           565: items each of size
        !           566: .UL size .
        !           567: The space is guaranteed to be set to 0 and the pointer is
        !           568: sufficiently well aligned to be usable for any purpose.
        !           569: .UL NULL
        !           570: is returned if no space is available .
        !           571: .nr PD .4v
        !           572: .LP
        !           573: .UL cfree(ptr)\ char\ *ptr;
        !           574: .nr PD 0
        !           575: .IP
        !           576: .br
        !           577: Space is returned to the pool used by
        !           578: .UL calloc .
        !           579: Disorder can be expected if the pointer was not obtained
        !           580: from
        !           581: .UL calloc .
        !           582: .nr PD .4v
        !           583: .LP
        !           584: The following are macros whose definitions may be obtained by including
        !           585: .UL <ctype.h> .
        !           586: .nr PD .4v
        !           587: .LP
        !           588: .UL isalpha(c)
        !           589: returns non-zero if the argument is alphabetic.
        !           590: .nr PD .4v
        !           591: .LP
        !           592: .UL isupper(c)
        !           593: returns non-zero if the argument is upper-case alphabetic.
        !           594: .nr PD .4v
        !           595: .LP
        !           596: .UL islower(c)
        !           597: returns non-zero if the argument is lower-case alphabetic.
        !           598: .nr PD .4v
        !           599: .LP
        !           600: .UL isdigit(c)
        !           601: returns non-zero if the argument is a digit.
        !           602: .nr PD .4v
        !           603: .LP
        !           604: .UL isspace(c)
        !           605: returns non-zero if the argument is a spacing character:
        !           606: tab, newline, carriage return, vertical tab,
        !           607: form feed, space.
        !           608: .nr PD .4v
        !           609: .LP
        !           610: .UL ispunct(c)
        !           611: returns non-zero if the argument is
        !           612: any punctuation character, i.e., not a space, letter,
        !           613: digit or control character.
        !           614: .nr PD .4v
        !           615: .LP
        !           616: .UL isalnum(c)
        !           617: returns non-zero if the argument is a letter or a digit.
        !           618: .nr PD .4v
        !           619: .LP
        !           620: .UL isprint(c)
        !           621: returns non-zero if the argument is printable \(em
        !           622: a letter, digit, or punctuation character.
        !           623: .nr PD .4v
        !           624: .LP
        !           625: .UL iscntrl(c)
        !           626: returns non-zero if the argument is a control character.
        !           627: .nr PD .4v
        !           628: .LP
        !           629: .UL isascii(c)
        !           630: returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
        !           631: .nr PD .4v
        !           632: .LP
        !           633: .UL toupper(c)
        !           634: returns the upper-case character corresponding to the lower-case
        !           635: letter
        !           636: .UL c.
        !           637: .nr PD .4v
        !           638: .LP
        !           639: .UL tolower(c)
        !           640: returns the lower-case character corresponding to the upper-case
        !           641: letter
        !           642: .UL c .

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.