Return to ios.r CVS log

Up to [CSRG BSD Unix] / 40BSD / libc / stdio

Annotation of 40BSD/libc/stdio/ios.r, revision 1.1

1.1     ! root        1: .de s
        !             2: .sp .5v
        !             3: ..
        !             4: .de sr
        !             5: .ft I
        !             6: .ne 2
        !             7: \\$1
        !             8: .if t .sp .2
        !             9: .br
        !            10: .ft R
        !            11: ..
        !            12: .de it
        !            13: \fI\\$1\fR
        !            14: ..
        !            15: .TL
        !            16: A New Input-Output Package
        !            17: .AU
        !            18: D. M. Ritchie
        !            19: .AI
        !            20: .MH
        !            21: .PP
        !            22: A new package of IO routines is available.
        !            23: It was designed with the following goals in mind.
        !            24: .IP 1.
        !            25: It should be similar in spirit to the earlier Portable
        !            26: Library, and, to the extent possible, be compatible with it.
        !            27: At the same time a few dubious design choices
        !            28: in the Portable Library will be corrected.
        !            29: .IP 2.
        !            30: It must be as efficient as possible, both in time and in space,
        !            31: so that there will be no hesitation in using it
        !            32: no matter how critical the application.
        !            33: .IP 3.
        !            34: It must be simple to use, and also free of the magic
        !            35: numbers and mysterious calls the use
        !            36: of which mars the understandability and portability
        !            37: of many programs using older packages.
        !            38: .IP 4.
        !            39: The interface provided should be applicable on all machines,
        !            40: whether or not the programs which implement it are directly portable
        !            41: to other systems,
        !            42: or to machines other than the PDP11 running a version of Unix.
        !            43: .PP
        !            44: It is intended that this package replace the Portable Library.
        !            45: Although it is not directly compatible, as discussed below,
        !            46: it is sufficiently similar that
        !            47: modifying programs to use it should be a simple exercise.
        !            48: .PP
        !            49: The most crucial difference between this package and the Portable
        !            50: Library is that the current offering names streams in terms
        !            51: of pointers rather than by
        !            52: the integers known as `file descriptors.'
        !            53: Thus, for example, the routine which opens a named file
        !            54: returns a pointer to a certain structure rather than a number;
        !            55: the routine which reads an open file
        !            56: takes as an argument the pointer returned from the open call.
        !            57: .SH
        !            58: General Usage
        !            59: .PP
        !            60: Each program using the library must have the line
        !            61: .DS
        !            62:                #include <stdio.h>
        !            63: .DE
        !            64: which defines certain macros and variables.
        !            65: The library containing the routines is `/usr/lib/libS.a,'
        !            66: so the command to compile is
        !            67: .DS
        !            68:                cc  . . .  \-lS
        !            69: .DE
        !            70: All names in the include file intended only for internal use begin
        !            71: with an underscore `\_' to reduce the possibility
        !            72: of collision with a user name.
        !            73: The names intended to be visible outside the package are
        !            74: .IP stdin 10
        !            75: The name of the standard input file
        !            76: .IP stdout 10
        !            77: The name of the standard output file
        !            78: .IP stderr 10
        !            79: The name of the standard error file
        !            80: .IP EOF 10
        !            81: is actually \-1, and is the value returned by
        !            82: the read routines on end-of-file or error.
        !            83: .IP NULL 10
        !            84: is a notation for the null pointer, returned by
        !            85: pointer-valued functions
        !            86: to indicate an error
        !            87: .IP FILE 10
        !            88: expands to `struct \_iob' and is a useful
        !            89: shorthand when declaring pointers
        !            90: to streams.
        !            91: .IP BUFSIZ
        !            92: is a number (viz. 512)
        !            93: of the size suitable for an IO buffer supplied by the user.
        !            94: See
        !            95: .it setbuf,
        !            96: below.
        !            97: .IP "getc, getchar, putc, putchar, feof, ferror, fileno" 10
        !            98: 
        !            99: .br
        !           100: are defined as macros.
        !           101: Their actions are described below;
        !           102: they are mentioned here
        !           103: to point out that it is not possible to
        !           104: redeclare them
        !           105: and that they are not actually functions;
        !           106: thus, for example, they may not have breakpoints set on them.
        !           107: .PP
        !           108: The routines in this package, like the Portable
        !           109: Library,
        !           110: offer the convenience of automatic buffer allocation
        !           111: and output flushing where appropriate.
        !           112: Absent, however, is the facility
        !           113: of changing the default input and output streams
        !           114: by assigning to `cin' and `cout.'
        !           115: The names `stdin,' stdout,' and `stderr'
        !           116: are in effect constants and may not be assigned to.
        !           117: .SH
        !           118: Calls
        !           119: .PP
        !           120: The routines in the library are in nearly one-to-one
        !           121: correspondence with those in the Portable Library.
        !           122: In several cases the name has been changed.
        !           123: This is an attempt to reduce confusion.
        !           124: .s
        !           125: .sr "FILE *fopen(filename, type) char *filename, *type"
        !           126: .it Fopen
        !           127: opens the file and, if needed, allocates a buffer for it.
        !           128: .it Filename
        !           129: is a character string specifying the name.
        !           130: .it Type
        !           131: is a character string (not a single character).
        !           132: It may be `"r",' `"w",' or `"a"' to indicate
        !           133: intent to read, write, or append.
        !           134: The value returned is a file pointer.
        !           135: If it is NULL the attempt to open failed.
        !           136: .s
        !           137: .sr "FILE *freopen(filename, type, ioptr) char *filename, *type; FILE *ioptr
        !           138: The stream named by
        !           139: .it ioptr
        !           140: is closed, if necessary, and then reopened
        !           141: as if by
        !           142: .it fopen.
        !           143: If the attempt to open fails, NULL is returned,
        !           144: otherwise
        !           145: .it ioptr,
        !           146: which will now refer to the new file.
        !           147: Often the reopened stream is
        !           148: .it stdin
        !           149: or
        !           150: .it stdout.
        !           151: .s
        !           152: .sr "int getc(ioptr) FILE *ioptr
        !           153: returns the next character from the stream named by
        !           154: .it ioptr,
        !           155: which is a pointer to a file such as returned by
        !           156: .it fopen,
        !           157: or the name
        !           158: .it stdin.
        !           159: The integer EOF is returned on end-of-file or when
        !           160: an error occurs.
        !           161: The null character \(aa\e0\(aa is a legal character.
        !           162: .s
        !           163: .sr "int fgetc(ioptr) FILE *ioptr
        !           164: acts like
        !           165: .it getc
        !           166: but is a genuine function,
        !           167: not a macro.
        !           168: .s
        !           169: .sr "putc(c, ioptr) FILE *ioptr
        !           170: .it Putc
        !           171: writes the character
        !           172: .it c
        !           173: on the output stream named by
        !           174: .it ioptr,
        !           175: which is a value returned from
        !           176: .it fopen
        !           177: or perhaps
        !           178: .it stdout
        !           179: or
        !           180: .it stderr.
        !           181: The character is returned as value,
        !           182: but EOF is returned on error.
        !           183: .s
        !           184: .sr "fputc(c, ioptr) FILE *ioptr
        !           185: .it Fputc
        !           186: acts like
        !           187: .it putc
        !           188: but is a genuine
        !           189: function, not a macro.
        !           190: .s
        !           191: .sr "fclose(ioptr) FILE *ioptr
        !           192: The file corresponding to
        !           193: .it ioptr
        !           194: is closed after any buffers are emptied.
        !           195: A buffer allocated by the IO system is freed.
        !           196: .it Fclose
        !           197: is automatic on normal termination of the program.
        !           198: .s
        !           199: .sr "fflush(ioptr) FILE *ioptr
        !           200: Any buffered information on the (output) stream named by
        !           201: .it ioptr
        !           202: is written out.
        !           203: Output files are normally buffered
        !           204: if and only if they are not directed to the terminal,
        !           205: but
        !           206: .it stderr
        !           207: is unbuffered unless
        !           208: .it setbuf
        !           209: is used.
        !           210: .s
        !           211: .sr exit(errcode)
        !           212: .it Exit
        !           213: terminates the process and returns its argument as status
        !           214: to the parent.
        !           215: This is a special version of the routine
        !           216: which calls
        !           217: .it fflush
        !           218: for each output file.
        !           219: To terminate without flushing,
        !           220: use
        !           221: .it \_exit.
        !           222: .s
        !           223: .sr "feof(ioptr) FILE *ioptr
        !           224: returns non-zero when end-of-file
        !           225: has occurred on the specified input stream.
        !           226: .s
        !           227: .sr "ferror(ioptr) FILE *ioptr
        !           228: returns non-zero when an error has occurred while reading
        !           229: or writing the named stream.
        !           230: The error indication lasts until the file has been closed.
        !           231: .s
        !           232: .sr "getchar( )"
        !           233: is identical to
        !           234: .it "getc(stdin).
        !           235: .s
        !           236: .sr "putchar(c)"
        !           237: is identical to
        !           238: .it "putc(c, stdout).
        !           239: .s
        !           240: .sr "char *gets(s) char *s
        !           241: reads characters up to a new-line from the standard input.
        !           242: The new-line character is replaced by a null character.
        !           243: It is the user's responsibility to make sure that the character array
        !           244: .it s
        !           245: is large enough.
        !           246: .it Gets
        !           247: returns its argument, or NULL if end-of-file or error occurred.
        !           248: Note that this routine is not compatible with
        !           249: .it fgets;
        !           250: it is included for downward compatibility.
        !           251: .s
        !           252: .sr "char *fgets(s, n, ioptr) char *s; FILE *ioptr
        !           253: reads up to
        !           254: .it n
        !           255: characters from the stream
        !           256: .it ioptr
        !           257: into the character pointer
        !           258: .it s.
        !           259: The read terminates with a new-line character.
        !           260: The new-line character is placed in the buffer
        !           261: followed by a null character.
        !           262: The first argument,
        !           263: or NULL if error or end-of-file occurred,
        !           264: is returned.
        !           265: .s
        !           266: .sr "puts(s) char *s
        !           267: writes the null-terminated string (character array)
        !           268: .it s
        !           269: on the standard output.
        !           270: A new-line is appended.
        !           271: No value is returned.
        !           272: Note that this routine
        !           273: is not compatible with
        !           274: .it fputs;
        !           275: it is included for downward compatibility.
        !           276: .s
        !           277: .sr "*fputs(s, ioptr) char *s; FILE *ioptr
        !           278: writes the null-terminated string (character array)
        !           279: .it s
        !           280: on the stream
        !           281: .it ioptr.
        !           282: No new-line is appended.
        !           283: No value is returned.
        !           284: .s
        !           285: .sr "ungetc(c, ioptr) FILE *ioptr
        !           286: The argument character
        !           287: .it c
        !           288: is pushed back on the input stream named by
        !           289: .it ioptr.
        !           290: Only one character may be pushed back.
        !           291: .s
        !           292: .sr "printf(format, a1, . . .) char *format
        !           293: .sr "fprintf(ioptr, format, a1, . . .) FILE *ioptr; char *format
        !           294: .sr "sprintf(s, format, a1, . . .)char *s, *format
        !           295: .it Printf
        !           296: writes on the standard output.
        !           297: .it Fprintf
        !           298: writes on the named output stream.
        !           299: .it Sprintf
        !           300: puts characters in the character array (string)
        !           301: named by
        !           302: .it s.
        !           303: The specifications are as described in section
        !           304: .it "printf
        !           305: (III)
        !           306: of the Unix Programmer's Manual.
        !           307: There is a new conversion:
        !           308: .it %m.n\fB\|g\fI
        !           309: converts a double argument in the style of
        !           310: .it e
        !           311: or
        !           312: .it f
        !           313: as most appropriate.
        !           314: .s
        !           315: .sr "scanf(format, a1, . . .) char *format
        !           316: .sr "fscanf(ioptr, format, a1, . . .) FILE *ioptr; char *format
        !           317: .sr "sscanf(s, format, a1, . . .) char *s, *format
        !           318: .it Scanf
        !           319: reads from the standard input.
        !           320: .it Fscanf
        !           321: reads from the named input stream.
        !           322: .it Sscanf
        !           323: reads from the character string
        !           324: supplied as
        !           325: .it s.
        !           326: The specifications are identical
        !           327: to those of the Portable Library.
        !           328: .it Scanf
        !           329: reads characters, interprets
        !           330: them according to a format, and stores the results in its arguments.
        !           331: It expects as arguments
        !           332: a control string
        !           333: .it format,
        !           334: described below,
        !           335: and a set of arguments,
        !           336: .I
        !           337: each of which must be a pointer,
        !           338: .R
        !           339: indicating where the converted input should be stored.
        !           340: .PP
        !           341: The
        !           342: control string
        !           343: usually contains
        !           344: conversion specifications, which are used to direct interpretation
        !           345: of input sequences.
        !           346: The control string may contain:
        !           347: .IP 1.
        !           348: Blanks, tabs or newlines, which are ignored.
        !           349: .IP 2.
        !           350: Ordinary characters (not %) which are expected to match
        !           351: the next non-space character of the input stream
        !           352: (where space characters are defined as blank, tab or newline).
        !           353: .IP 3.
        !           354: Conversion specifications, consisting of the
        !           355: character %, an optional assignment suppressing character \**,
        !           356: an optional numerical maximum field width, and a conversion
        !           357: character.
        !           358: .PP
        !           359: A conversion specification is used to direct the conversion of the
        !           360: next input field; the result
        !           361: is placed in the variable pointed to by the corresponding argument,
        !           362: unless assignment suppression was
        !           363: indicated by the \** character.
        !           364: An input field is defined as a string of non-space characters;
        !           365: it extends either to the next space character or until the field
        !           366: width, if specified, is exhausted.
        !           367: .PP
        !           368: The conversion character indicates the interpretation of the
        !           369: input field; the corresponding pointer argument must
        !           370: usually be of a restricted type.
        !           371: The following conversion characters are legal:
        !           372: .IP %
        !           373: indicates that a single % character is expected
        !           374: in the input stream at this point;
        !           375: no assignment is done.
        !           376: .IP d
        !           377: indicates that a decimal integer is expected
        !           378: in the input stream;
        !           379: the corresponding argument should be an integer pointer.
        !           380: .IP o
        !           381: indicates that an octal integer is expected in the
        !           382: input stream; the corresponding argument should be a integer pointer.
        !           383: .IP x
        !           384: indicates that a hexadecimal integer is expected in the input stream;
        !           385: the corresponding argument should be an integer pointer.
        !           386: .ti -0.2i
        !           387: .IP s
        !           388: indicates that a character string is expected;
        !           389: the corresponding argument should be a character pointer
        !           390: pointing to an array of characters large enough to accept the
        !           391: string and a terminating `\e0', which will be added.
        !           392: The input field is terminated by a space character
        !           393: or a newline.
        !           394: .IP c
        !           395: indicates that a character is expected; the
        !           396: corresponding argument should be a character pointer;
        !           397: the next input character is placed at the indicated spot.
        !           398: The normal skip over space characters is suppressed
        !           399: in this case;
        !           400: to read the next non-space character, try
        !           401: .I
        !           402: %1s.
        !           403: .R
        !           404: If a field width is given, the corresponding argument
        !           405: should refer to a character array, and the
        !           406: indicated number of characters is read.
        !           407: .IP e
        !           408: (or
        !           409: .I f\|\fR)
        !           410: .R
        !           411: indicates that a floating point number is expected in the input stream;
        !           412: the next field is converted accordingly and stored through the
        !           413: corresponding argument, which should be a pointer to a
        !           414: .it float.
        !           415: The input format for
        !           416: floating point numbers is
        !           417: an optionally signed
        !           418: string of digits
        !           419: possibly containing a decimal point, followed by an optional
        !           420: exponent field beginning with an E or e followed by an optionally signed integer.
        !           421: .IP [
        !           422: indicates a string not to be delimited by space characters.
        !           423: The left bracket is followed by a set of characters and a right
        !           424: bracket; the characters between the brackets define a set
        !           425: of characters making up the string.
        !           426: If the first character
        !           427: is not circumflex (\|^\|), the input field
        !           428: is all characters until the first character not in the set between
        !           429: the brackets; if the first character
        !           430: after the left bracket is ^, the input field is all characters
        !           431: until the first character which is in the remaining set of characters
        !           432: between the brackets.
        !           433: The corresponding argument must point to a character array.
        !           434: .PP
        !           435: The conversion characters
        !           436: .I
        !           437: d, o
        !           438: .R
        !           439: and
        !           440: .I
        !           441: x
        !           442: .R
        !           443: may be capitalized or preceded
        !           444: by
        !           445: .I
        !           446: l
        !           447: .R
        !           448: to indicate that a pointer to
        !           449: .I
        !           450: long
        !           451: .R
        !           452: rather than
        !           453: .I
        !           454: int
        !           455: .R
        !           456: is expected.
        !           457: Similarly, the conversion characters
        !           458: .I
        !           459: e
        !           460: .R
        !           461: or
        !           462: .I
        !           463: f
        !           464: .R
        !           465: may be capitalized or
        !           466: preceded by
        !           467: .I
        !           468: l
        !           469: .R
        !           470: to indicate that a pointer to 
        !           471: .I
        !           472: double
        !           473: .R
        !           474: rather than 
        !           475: .I
        !           476: float
        !           477: .R
        !           478: is in the argument list.
        !           479: The character
        !           480: .I
        !           481: h
        !           482: .R
        !           483: will function similarly in the future to indicate
        !           484: .I
        !           485: short
        !           486: .R
        !           487: data items.
        !           488: .PP
        !           489: For example, the call
        !           490: .DS
        !           491: int i; float x; char name[50];
        !           492: scanf( "%d%f%s", &i, &x, name);
        !           493: .DE
        !           494: with the input line
        !           495: .DS
        !           496: 25   54.32E\(mi1  thompson
        !           497: .DE
        !           498: will assign to
        !           499: .it i
        !           500: the value
        !           501: 25,
        !           502: .it x
        !           503: the value 5.432, and
        !           504: .it name
        !           505: will contain
        !           506: .it ``thompson\e0''.
        !           507: Or,
        !           508: .DS
        !           509: int i; float x; char name[50];
        !           510: scanf("%2d%f%\**d%[1234567890]", &i, &x, name);
        !           511: .DE
        !           512: with input
        !           513: .DS
        !           514: 56789 0123 56a72
        !           515: .DE
        !           516: will assign 56 to
        !           517: .it i,
        !           518: 789.0 to
        !           519: .it x,
        !           520: skip ``0123'',
        !           521: and place the string ``56\e0'' in
        !           522: .it name.
        !           523: The next call to
        !           524: .it getchar
        !           525: will return `a'.
        !           526: .PP
        !           527: .it Scanf
        !           528: returns as its value the number of successfully matched and assigned input
        !           529: items.
        !           530: This can be used to decide how many input items were found.
        !           531: On end of file, EOF is returned; note that this is different
        !           532: from 0, which means that the next input character does not
        !           533: match what was called for in the control string.
        !           534: .s
        !           535: .sr "fread(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr
        !           536: reads
        !           537: .it nitems
        !           538: of data beginning at
        !           539: .it ptr
        !           540: from file
        !           541: .it ioptr.
        !           542: It behaves identically to the Portable Library's
        !           543: .it cread.
        !           544: No advance notification
        !           545: that binary IO is being done is required;
        !           546: when, for portability reasons,
        !           547: it becomes required, it will be done
        !           548: by adding an additional character to the mode-string on the
        !           549: fopen call.
        !           550: .s
        !           551: .sr "fwrite(ptr, sizeof(*ptr), nitems, ioptr) FILE *ioptr
        !           552: Like
        !           553: .it fread,
        !           554: but in the other direction.
        !           555: .s
        !           556: .sr "rewind(ioptr) FILE *ioptr
        !           557: rewinds the stream
        !           558: named by
        !           559: .it ioptr.
        !           560: It is not very useful except on input,
        !           561: since a rewound output file is still open only for output.
        !           562: .s
        !           563: .sr "system(string) char *string
        !           564: The
        !           565: .it string
        !           566: is executed by the shell as if typed at the terminal.
        !           567: .s
        !           568: .sr "getw(ioptr) FILE *ioptr
        !           569: returns the next word from the input stream named by
        !           570: .it ioptr.
        !           571: EOF is returned on end-of-file or error,
        !           572: but since this a perfectly good
        !           573: integer
        !           574: .it feof
        !           575: and
        !           576: .it ferror
        !           577: should be used.
        !           578: .s
        !           579: .sr "putw(w, ioptr) FILE *ioptr
        !           580: writes the integer
        !           581: .it w
        !           582: on the named output stream.
        !           583: .s
        !           584: .sr "setbuf(ioptr, buf) FILE *ioptr; char *buf
        !           585: .it Setbuf
        !           586: may be used after a stream has been opened
        !           587: but before IO has started.
        !           588: If
        !           589: .it buf
        !           590: is NULL,
        !           591: the stream will be unbuffered.
        !           592: Otherwise the buffer supplied will be used.
        !           593: It is a character array of sufficient size:
        !           594: .DS
        !           595: char   buf[BUFSIZ];
        !           596: .DE
        !           597: .s
        !           598: .sr "fileno(ioptr) FILE *ioptr
        !           599: returns the integer file descriptor associated with the file.
        !           600: .s
        !           601: .sr "fseek(ioptr, offset, ptrname) FILE *ioptr; long offset
        !           602: The location of the next byte in the stream
        !           603: named by
        !           604: .it ioptr
        !           605: is adjusted.
        !           606: .it Offset
        !           607: is a long integer.
        !           608: If
        !           609: .it ptrname
        !           610: is 0, the offset is measured from the beginning of the file;
        !           611: if
        !           612: .it ptrname
        !           613: is 1, the offset is measured from the current read or
        !           614: write pointer;
        !           615: if
        !           616: .it ptrname
        !           617: is 2, the offset is measured from the end of the file.
        !           618: The routine accounts properly for any buffering.
        !           619: (When this routine is used on non-Unix systems,
        !           620: the offset must be a value returned from
        !           621: .it ftell
        !           622: and the ptrname must be 0).
        !           623: .s
        !           624: .sr "long ftell(ioptr) FILE *ioptr
        !           625: The byte offset, measured from the beginning of the file,
        !           626: associated with the named stream is returned.
        !           627: Any buffering is properly accounted for.
        !           628: (On non-Unix systems the value of this call is useful only
        !           629: for handing to
        !           630: .it fseek,
        !           631: so as to position the file to the same place it was when
        !           632: .it ftell
        !           633: was called.)
        !           634: .s
        !           635: .sr "getpw(uid, buf) char *buf
        !           636: The password file is searched for the given integer user ID.
        !           637: If an appropriate line is found, it is copied into
        !           638: the character array
        !           639: .it buf,
        !           640: and 0 is returned.
        !           641: If no line is found corresponding to the user ID
        !           642: then 1 is returned.
        !           643: .s
        !           644: .sr "char *calloc(num, size)
        !           645: allocates space for
        !           646: .it num
        !           647: items each of size
        !           648: .it size.
        !           649: The space is guaranteed to be set to 0 and the pointer is
        !           650: sufficiently well aligned to be usable for any purpose.
        !           651: NULL is returned if no space is available.
        !           652: .s
        !           653: .sr "cfree(ptr) char *ptr
        !           654: Space is returned to the pool used by
        !           655: .it calloc.
        !           656: Disorder can be expected if the pointer was not obtained
        !           657: from
        !           658: .it calloc.
        !           659: .LP
        !           660: The following are macros defined by stdio.h.
        !           661: .s
        !           662: .sr isalpha(c)
        !           663: returns non-zero if the argument is alphabetic.
        !           664: .s
        !           665: .sr isupper(c)
        !           666: returns non-zero if the argument is upper-case alphabetic.
        !           667: .s
        !           668: .sr islower(c)
        !           669: returns non-zero if the argument is lower-case alphabetic.
        !           670: .s
        !           671: .sr isdigit(c)
        !           672: returns non-zero if the argument is a digit.
        !           673: .s
        !           674: .sr isspace(c)
        !           675: returns non-zero if the argument is a spacing character:
        !           676: tab, new-line, carriage return, vertical tab,
        !           677: form feed, space.
        !           678: .s
        !           679: .sr toupper(c)
        !           680: returns the upper-case character corresponding to the lower-case
        !           681: letter c.
        !           682: .s
        !           683: .sr tolower(c)
        !           684: returns the lower-case character corresponding to the upper-case
        !           685: letter c.

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