From aa86bf2d6802741b82abbadd8b93f15e93018443 Mon Sep 17 00:00:00 2001 From: aaron Date: Thu, 20 Apr 2000 01:39:31 +0000 Subject: [PATCH] Flesh out all of the stdio man pages. --- lib/libc/stdio/fclose.3 | 5 +- lib/libc/stdio/ferror.3 | 5 +- lib/libc/stdio/fflush.3 | 5 +- lib/libc/stdio/fgetln.3 | 5 +- lib/libc/stdio/fopen.3 | 39 ++++++------ lib/libc/stdio/fputs.3 | 4 +- lib/libc/stdio/fseek.3 | 35 +++++------ lib/libc/stdio/funopen.3 | 27 ++++---- lib/libc/stdio/getc.3 | 22 +++---- lib/libc/stdio/mktemp.3 | 34 ++++------ lib/libc/stdio/perror.3 | 6 +- lib/libc/stdio/printf.3 | 92 ++++++++++++++------------- lib/libc/stdio/putc.3 | 25 ++++---- lib/libc/stdio/scanf.3 | 130 ++++++++++++++++++--------------------- lib/libc/stdio/setbuf.3 | 44 +++++++------ lib/libc/stdio/stdio.3 | 55 +++++++++-------- lib/libc/stdio/tmpnam.3 | 58 ++++++----------- lib/libc/stdio/ungetc.3 | 5 +- 18 files changed, 272 insertions(+), 324 deletions(-) diff --git a/lib/libc/stdio/fclose.3 b/lib/libc/stdio/fclose.3 index 1e1f0f5beee..396f3b077df 100644 --- a/lib/libc/stdio/fclose.3 +++ b/lib/libc/stdio/fclose.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fclose.3,v 1.2 1996/08/19 08:32:18 tholo Exp $ +.\" $OpenBSD: fclose.3,v 1.3 2000/04/20 01:39:31 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -88,6 +88,5 @@ or .Sh STANDARDS The .Fn fclose -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdio/ferror.3 b/lib/libc/stdio/ferror.3 index 351aee534fb..638db3a76e3 100644 --- a/lib/libc/stdio/ferror.3 +++ b/lib/libc/stdio/ferror.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ferror.3,v 1.4 1999/07/09 13:35:23 aaron Exp $ +.\" $OpenBSD: ferror.3,v 1.5 2000/04/20 01:39:31 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -57,8 +57,7 @@ .Sh DESCRIPTION The function .Fn clearerr -clears the end-of-file and error indicators for the stream pointed -to by +clears the end-of-file and error indicators for the stream pointed to by .Fa stream . .Pp The function diff --git a/lib/libc/stdio/fflush.3 b/lib/libc/stdio/fflush.3 index 99e17868058..352b6cea313 100644 --- a/lib/libc/stdio/fflush.3 +++ b/lib/libc/stdio/fflush.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fflush.3,v 1.4 1999/05/16 19:55:08 alex Exp $ +.\" $OpenBSD: fflush.3,v 1.5 2000/04/20 01:39:31 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -105,6 +105,5 @@ for any of the errors specified for the routine .Sh STANDARDS The .Fn fflush -function -conforms to +function conforms to .St -ansiC . diff --git a/lib/libc/stdio/fgetln.3 b/lib/libc/stdio/fgetln.3 index 20f16a26b48..cdf44663e35 100644 --- a/lib/libc/stdio/fgetln.3 +++ b/lib/libc/stdio/fgetln.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fgetln.3,v 1.6 1999/09/21 01:47:08 aaron Exp $ +.\" $OpenBSD: fgetln.3,v 1.7 2000/04/20 01:39:31 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -50,7 +50,7 @@ returns a pointer to the next line from the stream referenced by This line is .Em not a C string as it does not end with a terminating -.Dv NUL +.Tn NUL character. The length of the line, including the final newline, is stored in the memory location to which @@ -69,6 +69,7 @@ or as soon as the stream is closed. Otherwise, .Dv NULL is returned. +.Pp The .Fn fgetln function diff --git a/lib/libc/stdio/fopen.3 b/lib/libc/stdio/fopen.3 index 4b060145164..8bfa9ae25fe 100644 --- a/lib/libc/stdio/fopen.3 +++ b/lib/libc/stdio/fopen.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fopen.3,v 1.8 2000/04/12 21:48:01 aaron Exp $ +.\" $OpenBSD: fopen.3,v 1.9 2000/04/20 01:39:31 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -221,24 +221,6 @@ for any of the errors specified for the routines .Xr fclose 3 and .Xr fflush 3 . -.Sh SEE ALSO -.Xr open 2 , -.Xr fclose 3 , -.Xr fseek 3 , -.Xr funopen 3 -.Sh STANDARDS -The -.Fn fopen -and -.Fn freopen -functions -conform to -.St -ansiC . -The -.Fn fdopen -function -conforms to -.St -p1003.1-88 . .Sh CAVEATS Proper code using .Fn fdopen @@ -260,4 +242,21 @@ the resulting FILE * in case of success. close(fd); } .Ed - +.Sh SEE ALSO +.Xr open 2 , +.Xr fclose 3 , +.Xr fseek 3 , +.Xr funopen 3 +.Sh STANDARDS +The +.Fn fopen +and +.Fn freopen +functions +conform to +.St -ansiC . +The +.Fn fdopen +function +conforms to +.St -p1003.1-88 . diff --git a/lib/libc/stdio/fputs.3 b/lib/libc/stdio/fputs.3 index 4f2f38fdeaf..424ec95f8bd 100644 --- a/lib/libc/stdio/fputs.3 +++ b/lib/libc/stdio/fputs.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fputs.3,v 1.3 1999/05/16 19:55:08 alex Exp $ +.\" $OpenBSD: fputs.3,v 1.4 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -56,7 +56,7 @@ writes the string pointed to by to the stream pointed to by .Fa stream . .\" The terminating -.\" .Dv NUL +.\" .Tn NUL .\" character is not written. .Pp The function diff --git a/lib/libc/stdio/fseek.3 b/lib/libc/stdio/fseek.3 index cb14e62a968..f3827db1419 100644 --- a/lib/libc/stdio/fseek.3 +++ b/lib/libc/stdio/fseek.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fseek.3,v 1.6 2000/04/15 02:15:23 aaron Exp $ +.\" $OpenBSD: fseek.3,v 1.7 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -43,31 +43,30 @@ .Nm fseek , .Nm fseeko , .Nm fsetpos , -.Nm ftello , .Nm ftell , +.Nm ftello , .Nm rewind .Nd reposition a stream .Sh SYNOPSIS .Fd #include .Ft int +.Fn fgetpos "FILE *stream" "fpos_t *pos" +.Ft int .Fn fseek "FILE *stream" "long offset" "int whence" .Ft int .Fn fseeko "FILE *stream" "off_t offset" "int whence" +.Ft int +.Fn fsetpos "FILE *stream" "const fpos_t *pos" .Ft long .Fn ftell "FILE *stream" .Ft off_t .Fn ftello "FILE *stream" .Ft void .Fn rewind "FILE *stream" -.Ft int -.Fn fgetpos "FILE *stream" "fpos_t *pos" -.Ft int -.Fn fsetpos "FILE *stream" "const fpos_t *pos" .Sh DESCRIPTION The .Fn fseek -function sets the file position indicator for the stream pointed -to by +function sets the file position indicator for the stream pointed to by .Fa stream . The new position, measured in bytes, is obtained by adding .Fa offset @@ -95,14 +94,13 @@ The function is identical to .Fn fseek except that it takes an -.Dv off_t +.Li off_t as its .Fa offset . .Pp The .Fn ftell -function -obtains the current value of the file position indicator for the +function obtains the current value of the file position indicator for the stream pointed to by .Fa stream . .Pp @@ -111,7 +109,7 @@ The function is identical to .Fn ftell except that its return value is of type -.Dv off_t . +.Li off_t . .Pp The .Fn rewind @@ -131,8 +129,7 @@ The .Fn fgetpos and .Fn fsetpos -functions -are alternate interfaces equivalent to +functions are alternate interfaces equivalent to .Fn ftell and .Fn fseek @@ -150,8 +147,7 @@ and these routines may be the only way to portably reposition a text stream. .Sh RETURN VALUES The .Fn rewind -function -returns no value. +function returns no value. Upon successful completion, .Fn fgetpos , .Fn fseek , @@ -166,9 +162,7 @@ Otherwise, .Fn fseek and .Fn fseeko -return \-1 and -the others -return a nonzero value and the global variable +return \-1 and the others return a nonzero value and the global variable .Va errno is set to indicate the error. .Sh ERRORS @@ -176,8 +170,7 @@ is set to indicate the error. .It Bq Er EBADF The .Fa stream -specified -is not a seekable stream. +specified is not a seekable stream. .It Bq Er EINVAL The .Fa whence diff --git a/lib/libc/stdio/funopen.3 b/lib/libc/stdio/funopen.3 index 8962b347ca2..076ccc90162 100644 --- a/lib/libc/stdio/funopen.3 +++ b/lib/libc/stdio/funopen.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: funopen.3,v 1.8 1999/07/09 13:35:23 aaron Exp $ +.\" $OpenBSD: funopen.3,v 1.9 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -52,8 +52,7 @@ .Sh DESCRIPTION The .Fn funopen -function -associates a stream with up to four +function associates a stream with up to four .Dq Tn I/O No functions . Either .Fa readfn @@ -65,8 +64,7 @@ the others can be given as an appropriately typed pointer. These .Tn I/O -functions will be used to read, write, seek and -close the new stream. +functions will be used to read, write, seek and close the new stream. .Pp In general, omitting a function means that any attempt to perform the associated operation on the resulting stream will fail. @@ -76,7 +74,7 @@ any buffered output and then succeed. The calling conventions of .Fa readfn , .Fa writefn , -.Fa seekfn +.Fa seekfn , and .Fa closefn must match those, respectively, of @@ -90,7 +88,10 @@ with the exceptions that they are passed the argument specified to .Fn funopen in place of the traditional file descriptor argument and that -the seek function takes an fpos_t argument and not an off_t +the seek function takes an +.Li fpos_t +argument and not an +.Li off_t argument. .Pp Read and write @@ -140,15 +141,12 @@ is set to indicate the error. .It Bq Er EINVAL The .Fn funopen -function -was called without either a read or write function. +function was called without either a read or write function. The .Fn funopen -function -may also fail and set +function may also fail and set .Va errno -for any of the errors -specified for the routine +for any of the errors specified for the routine .Xr malloc 3 . .El .Sh SEE ALSO @@ -166,6 +164,5 @@ functions first appeared in .Sh BUGS The .Fn funopen -function -may not be portable to systems other than +function may not be portable to systems other than .Bx . diff --git a/lib/libc/stdio/getc.3 b/lib/libc/stdio/getc.3 index e5a065418d9..debba67a6e4 100644 --- a/lib/libc/stdio/getc.3 +++ b/lib/libc/stdio/getc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getc.3,v 1.5 1999/05/25 01:50:58 aaron Exp $ +.\" $OpenBSD: getc.3,v 1.6 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -65,32 +65,27 @@ or the next character pushed back on the stream via .Pp The .Fn getc -function -acts essentially identically to +function acts essentially identically to .Fn fgetc , but is a macro that expands in-line. .Pp The .Fn getchar -function -is equivalent to +function is equivalent to .Fn getc with the argument stdin. .Pp The .Fn getw -function -obtains the next -.Em int +function obtains the next +.Li int (if present) from the stream pointed at by .Fa stream . .Sh RETURN VALUES -If successful, these routines return the next requested object -from the +If successful, these routines return the next requested object from the .Fa stream . -If the stream is at end-of-file or a read error occurs, -the routines return +If the stream is at end-of-file or a read error occurs, the routines return .Dv EOF . The routines .Xr feof 3 @@ -114,7 +109,7 @@ until the condition is cleared with .Sh STANDARDS The .Fn fgetc , -.Fn getc +.Fn getc , and .Fn getchar functions @@ -134,4 +129,3 @@ The size and byte order of an varies from one machine to another, and .Fn getw is not recommended for portable applications. -.Pp diff --git a/lib/libc/stdio/mktemp.3 b/lib/libc/stdio/mktemp.3 index 2a26ee04fec..ee17797675f 100644 --- a/lib/libc/stdio/mktemp.3 +++ b/lib/libc/stdio/mktemp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mktemp.3,v 1.21 2000/04/18 03:01:34 aaron Exp $ +.\" $OpenBSD: mktemp.3,v 1.22 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -53,11 +53,9 @@ .Sh DESCRIPTION The .Fn mktemp -function -takes the given file name template and overwrites a portion of it +function takes the given file name template and overwrites a portion of it to create a file name. -This file name is unique and suitable for use -by the application. +This file name is unique and suitable for use by the application. The template may be any file name with some number of .So Li X .Sc Ns s @@ -119,8 +117,7 @@ functions return a pointer to the template on success and on failure. The .Fn mkstemp -function -returns \-1 if no suitable file could be created. +function returns \-1 if no suitable file could be created. If either call fails an error code is placed in the global variable .Va errno . .Sh ERRORS @@ -141,8 +138,7 @@ The .Fn mkstemp and .Fn mkdtemp -functions -may also set +functions may also set .Va errno to any value specified by the .Xr stat 2 @@ -150,8 +146,7 @@ function. .Pp The .Fn mkstemp -function -may also set +function may also set .Va errno to any value specified by the .Xr open 2 @@ -159,8 +154,7 @@ function. .Pp The .Fn mkstemps -function -may also set +function may also set .Va errno to any value specified by the .Xr open 2 @@ -172,8 +166,7 @@ The suffix length is longer than the template length. .Pp The .Fn mkdtemp -function -may also set +function may also set .Va errno to any value specified by the .Xr mkdir 2 @@ -184,8 +177,9 @@ For there is an obvious race between file name selection and file creation and deletion: the program is typically written to call .Xr tmpnam 3 , -.Xr tempnam 3 , or -.Ns Fn mktemp . +.Xr tempnam 3 , +or +.Fn mktemp . Subsequently, the program calls .Xr open 2 or @@ -212,16 +206,14 @@ The .Fn mkdtemp and .Fn mkstemps -functions are nonstandard and should not be used if portability -is required. +functions are nonstandard and should not be used if portability is required. .Sh EXAMPLES Quite often a programmer will want to replace a use of .Fn mktemp with .Fn mkstemp , usually to avoid the problems described above. -Doing this correctly requires a good understanding of the -code in question. +Doing this correctly requires a good understanding of the code in question. .Pp For instance, code of this form: .Bd -literal -offset indent diff --git a/lib/libc/stdio/perror.3 b/lib/libc/stdio/perror.3 index 39637604fc7..acdc51c6ffe 100644 --- a/lib/libc/stdio/perror.3 +++ b/lib/libc/stdio/perror.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: perror.3,v 1.3 1999/05/23 14:11:02 aaron Exp $ +.\" $OpenBSD: perror.3,v 1.4 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1980, 1991 Regents of the University of California. .\" All rights reserved. @@ -54,9 +54,7 @@ standard error stream. .Pp If the argument .Fa string -is -.Pf non- Dv NULL -it is prepended to the message string and separated from it by +is non-null it is prepended to the message string and separated from it by a colon and a space .Pq Ql \&:\ \& . If diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index 66c0aa25ea6..c064bed7f73 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: printf.3,v 1.25 2000/04/18 03:01:35 aaron Exp $ +.\" $OpenBSD: printf.3,v 1.26 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -79,23 +79,30 @@ .Sh DESCRIPTION The .Fn printf -family of functions produces output according to a +family of functions produce output according to the given .Fa format as described below. +This format may contain +.Dq conversion specifiers ; +the results of such conversions, if any, depend on the arguments +following the +.Fa format +string. +.Pp +The .Fn printf and .Fn vprintf -write output to -.Em stdout , -the standard output stream; +functions write output to the standard output stream, +.Em stdout ; .Fn fprintf and .Fn vfprintf -write output to the given output +write output to the supplied stream pointer .Fa stream ; .Fn sprintf , .Fn snprintf , -.Fn vsprintf +.Fn vsprintf , and .Fn vsnprintf write to the character string @@ -113,8 +120,7 @@ string that specifies how subsequent arguments .Xr stdarg 3 ) are converted for output. .Pp -These functions return -the number of characters printed +These functions return the number of characters printed (not including the trailing .Ql \e0 used to end output to strings). @@ -122,8 +128,7 @@ used to end output to strings). .Fn asprintf and .Fn vasprintf -return a pointer to a buffer sufficiently large to hold the -string in the +return a pointer to a buffer sufficiently large to hold the string in the .Fa ret argument. This pointer should be passed to @@ -132,7 +137,7 @@ to release the allocated storage when it is no longer needed. If sufficient space cannot be allocated, these functions will return \-1 and set .Fa ret -to be a NULL pointer. +to be a null pointer. .Pp If .Fn asprintf @@ -142,7 +147,7 @@ are given a .Fa size of 0, they set .Fa ret -to be a NULL pointer. +to be a null pointer. .Pp .Fn snprintf and @@ -170,11 +175,10 @@ ordinary .\" multibyte characters (not .Cm % ) , -which are copied unchanged to the output stream; +which are copied unchanged to the output stream, and conversion specifications, each of which results in fetching zero or more subsequent arguments. -Each conversion specification is introduced by -the character +Each conversion specification is introduced by the character .Cm % . The arguments must correspond properly (after type promotion) with the conversion specifier. @@ -184,7 +188,7 @@ the following appear in sequence: .Bl -bullet .It An optional field, consisting of a decimal digit string followed by a -.Cm $ , +.Cm $ specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. @@ -194,8 +198,8 @@ Arguments are numbered starting at Zero or more of the following flags: .Bl -hyphen .It -A -.Cm # +A hash +.Ql Cm # character specifying that the value should be converted to an ``alternate form''. For @@ -336,13 +340,13 @@ specifying that a following or .Cm X conversion corresponds to a -.Em short int +.Li short int or -.Em unsigned short int +.Li unsigned short int argument, or that a following .Cm n conversion corresponds to a pointer to a -.Em short int +.Li short int argument. .It The optional character @@ -356,13 +360,13 @@ The optional character or .Cm X conversion applies to a pointer to a -.Em long int +.Li long int or -.Em unsigned long int +.Li unsigned long int argument, or that a following .Cm n conversion corresponds to a pointer to a -.Em long int +.Li long int argument. .It The optional character @@ -376,13 +380,13 @@ specifying that a following or .Cm X conversion corresponds to a -.Em quad int +.Li quad int or -.Em unsigned quad int +.Li unsigned quad int argument, or that a following .Cm n conversion corresponds to a pointer to a -.Em quad int +.Li quad int argument. .It The character @@ -395,7 +399,7 @@ specifying that a following or .Cm G conversion corresponds to a -.Em long double +.Li long double argument (but note that long double values are not currently supported by the .Tn VAX @@ -414,7 +418,7 @@ or an asterisk followed by one or more decimal digits and a instead of a digit string. In this case, an -.Em int +.Li int argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were @@ -426,7 +430,7 @@ The conversion specifiers and their meanings are: .Bl -tag -width "diouxX" .It Cm diouxX The -.Em int +.Li int (or appropriate variant) argument is converted to signed decimal .Pf ( Cm d and @@ -454,7 +458,7 @@ appear; if the converted value requires fewer digits, it is padded on the left with zeros. .It Cm DOU The -.Em long int +.Li long int argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been .Cm ld , @@ -465,7 +469,7 @@ respectively. These conversion characters are deprecated, and will eventually disappear. .It Cm eE The -.Em double +.Li double argument is rounded and converted in the style .Sm off .Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd @@ -487,7 +491,7 @@ The exponent always contains at least two digits; if the value is zero, the exponent is 00. .It Cm f The -.Em double +.Li double argument is rounded and converted to decimal notation in the style .Sm off .Pf [-]ddd Cm \&. No ddd , @@ -499,7 +503,7 @@ explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it. .It Cm gG The -.Em double +.Li double argument is converted in style .Cm f or @@ -520,29 +524,29 @@ Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit. .It Cm c The -.Em int +.Li int argument is converted to an -.Em unsigned char , +.Li unsigned char , and the resulting character is written. .It Cm s The -.Dq Em char * +.Li char * argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating -.Dv NUL +.Tn NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating -.Dv NUL +.Tn NUL character. .It Cm p The -.Dq Em void * +.Li void * pointer argument is printed in hexadecimal (as if by .Ql %#x or @@ -550,7 +554,7 @@ or .It Cm n The number of characters written so far is stored into the integer indicated by the -.Dq Em int * +.Li int * (or variant) pointer argument. No argument is converted. .It Cm % @@ -568,9 +572,9 @@ field is expanded to contain the conversion result. .Sh EXAMPLES To print a date and time in the form `Sunday, July 3, 10:02', where -.Em weekday +.Va weekday and -.Em month +.Va month are pointers to strings: .Bd -literal -offset indent #include diff --git a/lib/libc/stdio/putc.3 b/lib/libc/stdio/putc.3 index d6850646fc3..f2f30c6134e 100644 --- a/lib/libc/stdio/putc.3 +++ b/lib/libc/stdio/putc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: putc.3,v 1.4 2000/04/18 03:01:35 aaron Exp $ +.\" $OpenBSD: putc.3,v 1.5 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -57,10 +57,10 @@ .Sh DESCRIPTION The .Fn fputc -function -writes the character +function writes the character .Fa c -(converted to an ``unsigned char'') +(converted to an +.Li unsigned char ) to the output stream pointed to by .Fa stream . .Pp @@ -82,15 +82,15 @@ with an output stream of .Pp The .Fn putw -function -writes the specified -.Em int +function writes the specified +.Li int +.Fa w to the named output .Fa stream . .Sh RETURN VALUES The functions, .Fn fputc , -.Fn putc +.Fn putc , and .Fn putchar return the character written. @@ -102,8 +102,7 @@ The function returns 0 on success; .Dv EOF -is returned if -a write error occurs, +is returned if a write error occurs, or if an attempt is made to write a read-only stream. .Sh SEE ALSO .Xr ferror 3 , @@ -123,8 +122,8 @@ A function function appeared in .At v6 . .Sh BUGS -The size and byte order of an -.Em int -varies from one machine to another, and +Since the size and byte order of an +.Li int +varies from one machine to another, .Fn putw is not recommended for portable applications. diff --git a/lib/libc/stdio/scanf.3 b/lib/libc/stdio/scanf.3 index d91cdeed345..87f5ad0213a 100644 --- a/lib/libc/stdio/scanf.3 +++ b/lib/libc/stdio/scanf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: scanf.3,v 1.6 2000/04/18 03:01:35 aaron Exp $ +.\" $OpenBSD: scanf.3,v 1.7 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -64,31 +64,29 @@ .Sh DESCRIPTION The .Fn scanf -family of functions scans input according to a +family of functions read input according to the given .Fa format as described below. This format may contain -.Em conversion specifiers ; -the results from such conversions, if any, -are stored through the -.Em pointer +.Dq conversion specifiers ; +the results of such conversions, if any, are stored through a set of pointer arguments. +.Pp The .Fn scanf -function -reads input from the standard input stream +function reads input from the standard input stream .Em stdin , .Fn fscanf -reads input from the stream pointer +reads input from the supplied stream pointer .Fa stream , and .Fn sscanf reads its input from the character string pointed to by .Fa str . +.Pp The .Fn vfscanf -function -is analogous to +function is analogous to .Xr vfprintf 3 and reads input from the stream pointer .Fa stream @@ -96,21 +94,20 @@ using a variable argument list of pointers (see .Xr stdarg 3 ) . The .Fn vscanf -function scans a variable argument list from the standard input and -the +function scans a variable argument list from the standard input and the .Fn vsscanf -function scans it from a string; -these are analogous to -the +function scans it from a string; these are analogous to the .Fn vprintf and .Fn vsprintf -functions respectively. +functions, respectively. +.Pp Each successive .Em pointer -argument must correspond properly with -each successive conversion specifier -(but see `suppression' below). +argument must correspond properly with each successive conversion specifier +(but see +.Dq suppression +below). All conversions are introduced by the .Cm % (percent sign) character. @@ -118,20 +115,16 @@ The .Fa format string may also contain other characters. -White space (such as blanks, tabs, or newlines) in the +Whitespace (such as blanks, tabs, or newlines) in the .Fa format string match any amount of whitespace, including none, in the input. -Everything else -matches only itself. -Scanning stops -when an input character does not match such a format character. -Scanning also stops -when an input conversion cannot be made (see below). +Everything else matches only itself. +Scanning stops when an input character does not match such a format character. +Scanning also stops when an input conversion cannot be made (see below). .Sh CONVERSIONS Following the .Cm % -character introducing a conversion -there may be a number of +character introducing a conversion there may be a number of .Em flag characters, as follows: .Bl -tag -width indent @@ -145,65 +138,67 @@ Indicates that the conversion will be one of or .Cm n and the next pointer is a pointer to a -.Em short int +.Li short int (rather than -.Em int ) . +.Li int ) . .It Cm l Indicates either that the conversion will be one of .Cm dioux or .Cm n and the next pointer is a pointer to a -.Em long int +.Li long int (rather than -.Em int ) , +.Li int ) , or that the conversion will be one of .Cm efg and the next pointer is a pointer to -.Em double +.Li double (rather than -.Em float ) . +.Li float ) . .It Cm q Indicates that the conversion will be one of .Cm dioux or .Cm n and the next pointer is a pointer to a -.Em quad_t +.Li quad_t (rather than -.Em int ) . +.Li int ) . .It Cm L Indicates that the conversion will be .Cm efg and the next pointer is a pointer to -.Em long double . +.Li long double . .El .Pp -In addition to these flags, -there may be an optional maximum field width, -expressed as a decimal integer, -between the +In addition to these flags, there may be an optional maximum field width, +expressed as a decimal integer, between the .Cm % and the conversion. If no width is given, -a default of `infinity' is used (with one exception, below); -otherwise at most this many characters are scanned -in processing the conversion. -Before conversion begins, -most conversions skip whitespace; +a default of +.Dq infinity +is used (with one exception, below); +otherwise at most this many characters are scanned in processing the +conversion. +Before conversion begins, most conversions skip whitespace; this whitespace is not counted against the field width. .Pp The following conversions are available: .Bl -tag -width XXXX .It Cm % Matches a literal `%'. -That is, `%\&%' in the format string -matches a single input `%' character. +That is, +.Ql %\&% +in the format string matches a single input +.Ql % +character. No conversion is done, and assignment does not occur. .It Cm d Matches an optionally signed decimal integer; the next pointer must be a pointer to -.Em int . +.Li int . .It Cm D Equivalent to .Cm ld ; @@ -211,7 +206,7 @@ this exists only for backwards compatibility. .It Cm i Matches an optionally signed integer; the next pointer must be a pointer to -.Em int . +.Li int . The integer is read in base 16 if it begins with .Ql 0x @@ -224,7 +219,7 @@ Only characters that correspond to the base are used. .It Cm o Matches an octal integer; the next pointer must be a pointer to -.Em unsigned int . +.Li unsigned int . .It Cm O Equivalent to .Cm lo ; @@ -232,18 +227,18 @@ this exists for backwards compatibility. .It Cm u Matches an optionally signed decimal integer; the next pointer must be a pointer to -.Em unsigned int . +.Li unsigned int . .It Cm x Matches an optionally signed hexadecimal integer; the next pointer must be a pointer to -.Em unsigned int . +.Li unsigned int . .It Cm X Equivalent to .Cm x . .It Cm f Matches an optionally signed floating-point number; the next pointer must be a pointer to -.Em float . +.Li float . .It Cm e Equivalent to .Cm f . @@ -259,23 +254,22 @@ Equivalent to .It Cm s Matches a sequence of non-whitespace characters; the next pointer must be a pointer to -.Em char , +.Li char , and the array must be large enough to accept all the sequence and the terminating -.Dv NUL +.Tn NUL character. The input string stops at whitespace or at the maximum field width, whichever occurs first. .It Cm c Matches a sequence of -.Em width -count -characters (default 1); +.Li width +count characters (default 1); the next pointer must be a pointer to -.Em char , +.Li char , and there must be enough room for all the characters (no terminating -.Dv NUL +.Tn NUL is added). The usual skip of leading whitespace is suppressed. To skip whitespace first, use an explicit space in the format. @@ -283,10 +277,10 @@ To skip whitespace first, use an explicit space in the format. Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to -.Em char , +.Li char , and there must be enough room for all the characters in the string, plus a terminating -.Dv NUL +.Tn NUL character. The usual skip of leading whitespace is suppressed. The string is to be made up of characters in @@ -298,9 +292,7 @@ character and a close bracket .Cm ] character. -The set -.Em excludes -those characters +The set excludes those characters if the first character after the open bracket is a circumflex .Cm ^ . To include a close bracket in the set, @@ -327,13 +319,13 @@ Matches a pointer value (as printed by in .Xr printf 3 ) ; the next pointer must be a pointer to -.Em void . +.Li void . .It Cm n Nothing is expected; instead, the number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to -.Em int . +.Li int . This is .Em not a conversion, although it can be suppressed with the diff --git a/lib/libc/stdio/setbuf.3 b/lib/libc/stdio/setbuf.3 index 2f9c7c99ec3..cdb379d8089 100644 --- a/lib/libc/stdio/setbuf.3 +++ b/lib/libc/stdio/setbuf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: setbuf.3,v 1.8 1999/07/09 13:35:23 aaron Exp $ +.\" $OpenBSD: setbuf.3,v 1.9 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -55,21 +55,22 @@ .Ft int .Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" .Sh DESCRIPTION -The three types of buffering available are unbuffered, block buffered, +The three types of stream buffering available are unbuffered, block buffered, and line buffered. When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; -when it is block buffered many characters are saved up and written as a block; -when it is line buffered characters are saved up until a newline is -output or input is read from any stream attached to a terminal device -(typically stdin). -The function +when it is block buffered, many characters are saved up and written as a block; +when line buffered, characters are saved up until a newline +.Pq Ql \en +is output or input is read from any stream attached to a terminal device +(typically +.Em stdin ) . +.Pp +The .Xr fflush 3 -may be used to force the block out early. -(See -.Xr fclose 3 . ) +function may be used to force the block out early. .Pp -Normally all files are block buffered. +Normally, all files are block buffered. When the first .Tn I/O operation occurs on a file, @@ -79,15 +80,15 @@ and an optimally sized buffer is obtained. If a stream refers to a terminal (as .Em stdout -normally does) it is line buffered. +normally does), it is line buffered. +.Pp The standard error stream .Em stderr is initially unbuffered. .Pp The .Fn setvbuf -function -may be used to alter the buffering behavior of a stream. +function may be used to alter the buffering behavior of a stream. The .Fa mode parameter must be one of the following three macros: @@ -104,8 +105,7 @@ The .Fa size parameter may be given as zero to obtain deferred optimal-size buffer allocation as usual. -If it is not zero, -then except for unbuffered files, the +If it is not zero, then except for unbuffered files, the .Fa buf argument should point to a buffer at least .Fa size @@ -130,7 +130,8 @@ The function may be used at any time, but may have peculiar side effects (such as discarding input or flushing output) -if the stream is ``active''. +if the stream is +.Dq active . Portable applications should call it only once on any given stream, and before any .Tn I/O @@ -146,14 +147,12 @@ function is exactly equivalent to the call .Pp The .Fn setbuffer -function -is the same, except that the size of the buffer is up to the caller, +function is the same, except that the size of the buffer is up to the caller, rather than being determined by the default .Dv BUFSIZ . The .Fn setlinebuf -function -is exactly equivalent to the call: +function is exactly equivalent to the call: .Pp .Dl "setvbuf(stream, NULL, _IOLBF, 0);" .Sh RETURN VALUES @@ -181,8 +180,7 @@ The .Fn setbuf and .Fn setvbuf -functions -conform to +functions conform to .St -ansiC . .Sh BUGS The diff --git a/lib/libc/stdio/stdio.3 b/lib/libc/stdio/stdio.3 index 401a7f7c04a..42ace2c1d9a 100644 --- a/lib/libc/stdio/stdio.3 +++ b/lib/libc/stdio/stdio.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: stdio.3,v 1.12 2000/04/18 03:01:35 aaron Exp $ +.\" $OpenBSD: stdio.3,v 1.13 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -39,6 +39,7 @@ .Nd standard input/output library functions .Sh SYNOPSIS .Fd #include +.Pp .Fd FILE *stdin; .Fd FILE *stdout; .Fd FILE *stderr; @@ -48,21 +49,20 @@ The standard library provides a simple and efficient buffered stream .Tn I/O interface. -Input and output is mapped into logical data streams -and the physical +Input and output is mapped into logical data streams and the physical .Tn I/O characteristics are concealed. -The functions and macros are listed -below; more information is available from the individual man pages. +The functions and macros are listed below; +more information is available from the individual man pages. .Pp A stream is associated with an external file (which may be a physical device) by -.Em opening +.Dq opening a file, which may involve creating a new file. Creating an existing file causes its former contents to be discarded. If a file can support positioning requests (such as a disk file, as opposed to a terminal) then a -.Em file position indicator +.Dq file position indicator associated with the stream is positioned at the start of the file (byte zero), unless the file is opened with append mode. If append mode @@ -78,8 +78,8 @@ written by successive calls to the function. .Pp A file is disassociated from a stream by -.Em closing -the file. +.Dq closing +it. Output streams are flushed (any unwritten buffer contents are transferred to the host environment) before the stream is disassociated from the file. The value of a pointer to a @@ -114,6 +114,7 @@ No translation is performed and no extra padding appears on any stream. .Pp At program startup, three streams are predefined and need not be opened explicitly: +.Pp .Bl -bullet -compact -offset indent .It .Em standard input @@ -125,8 +126,10 @@ opened explicitly: .Em standard error (for writing diagnostic output). .El +.Pp These streams are abbreviated -.Em stdin , stdout +.Em stdin , +.Em stdout , and .Em stderr . Initially, the standard error stream @@ -209,22 +212,6 @@ and .Xr putchar exist and will be used if the macro definitions are explicitly removed. -.Sh SEE ALSO -.Xr close 2 , -.Xr open 2 , -.Xr read 2 , -.Xr write 2 -.Sh BUGS -The standard buffered functions do not interact well with certain other -library and system functions, especially -.Xr vfork -and -.Xr abort . -.Sh STANDARDS -The -.Nm stdio -library conforms to -.St -ansiC . .Sh LIST OF FUNCTIONS .Bl -column "Description" .Sy Function Description @@ -291,3 +278,19 @@ vsnprintf formatted output conversion vsprintf formatted output conversion vsscanf input format conversion .El +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 +.Sh BUGS +The standard buffered functions do not interact well with certain other +library and system functions, especially +.Xr vfork +and +.Xr abort . +.Sh STANDARDS +The +.Nm stdio +library conforms to +.St -ansiC . diff --git a/lib/libc/stdio/tmpnam.3 b/lib/libc/stdio/tmpnam.3 index 4c26613a26f..7b78645cf94 100644 --- a/lib/libc/stdio/tmpnam.3 +++ b/lib/libc/stdio/tmpnam.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: tmpnam.3,v 1.7 2000/01/09 09:36:17 deraadt Exp $ +.\" $OpenBSD: tmpnam.3,v 1.8 2000/04/20 01:39:32 aaron Exp $ .\" .\" Copyright (c) 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -54,9 +54,8 @@ .Sh DESCRIPTION The .Fn tmpfile -function -returns a pointer to a stream associated with a file descriptor returned -by the routine +function returns a pointer to a stream associated with a file descriptor +returned by the routine .Xr mkstemp 3 . The created file is unlinked before .Fn tmpfile @@ -65,7 +64,7 @@ reference to it is closed. Since .Xr mkstemp 3 creates the file with mode -.Em "S_IRUSR|S_IWUSR", +.Dv S_IRUSR | S_IWUSR , after the unlink .Xr fchown 2 and @@ -76,20 +75,16 @@ The file is opened with the access value .Pp The .Fn tmpnam -function -returns a pointer to a file name, in the +function returns a pointer to a file name, in the .Dv P_tmpdir -directory, which -did not reference an existing file at some indeterminate point in the -past. +directory, which did not reference an existing file at some +indeterminate point in the past. .Dv P_tmpdir is defined in the include file .Aq Pa stdio.h . If the argument .Fa str -is -.Pf non- Dv NULL , -the file name is copied to the buffer it references. +is non-null, the file name is copied to the buffer it references. Otherwise, the file name is copied to a static buffer. In either case, .Fn tmpnam @@ -106,8 +101,7 @@ is defined in the include file .Pp The .Fn tempnam -function -is similar to +function is similar to .Fn tmpnam , but provides the ability to specify the directory which will contain the temporary file and the file name prefix. @@ -116,8 +110,7 @@ The environment variable .Ev TMPDIR (if set), the argument .Fa tmpdir -(if -.Pf non- Dv NULL ) , +(if non-null), the directory .Dv P_tmpdir , and the directory @@ -127,9 +120,7 @@ temporary file. .Pp The argument .Fa prefix , -if -.Pf non- Dv NULL , -is used to specify a file name prefix, which will be the +if non-null, is used to specify a file name prefix, which will be the first part of the created file name. .Fn tempnam allocates memory in which to store the file name; the returned pointer @@ -138,26 +129,19 @@ may be used as a subsequent argument to .Sh RETURN VALUES The .Fn tmpfile -function -returns a pointer to an open file stream on success, and a -.Dv NULL -pointer -on error. +function returns a pointer to an open file stream on success, and a null +pointer on error. .Pp The .Fn tmpnam and .Fn tempfile -functions -return a pointer to a file name on success, and a -.Dv NULL -pointer +functions return a pointer to a file name on success, and a null pointer on error. .Sh ERRORS The .Fn tmpfile -function -may fail and set the global variable +function may fail and set the global variable .Va errno for any of the errors specified for the library functions .Xr fdopen 3 @@ -166,16 +150,14 @@ or .Pp The .Fn tmpnam -function -may fail and set +function may fail and set .Va errno for any of the errors specified for the library function .Xr mktemp 3 . .Pp The .Fn tempnam -function -may fail and set +function may fail and set .Va errno for any of the errors specified for the library functions .Xr malloc 3 @@ -189,8 +171,7 @@ The .Fn tmpfile and .Fn tmpnam -functions -conform to +functions conform to .St -ansiC . .Sh BUGS .Fn tmpnam @@ -241,8 +222,7 @@ cannot depend on that. .Pp For these reasons, .Xr ld 8 -will output a warning message whenever it links code that uses the -functions +will output a warning message whenever it links code that uses the functions .Fn tmpnam or .Fn tempnam . diff --git a/lib/libc/stdio/ungetc.3 b/lib/libc/stdio/ungetc.3 index 4a2008f74f5..852b8bede31 100644 --- a/lib/libc/stdio/ungetc.3 +++ b/lib/libc/stdio/ungetc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ungetc.3,v 1.3 1999/05/16 19:55:11 alex Exp $ +.\" $OpenBSD: ungetc.3,v 1.4 2000/04/20 01:39:33 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -50,7 +50,8 @@ The .Fn ungetc function pushes the character .Fa c -(converted to an unsigned char) +(converted to an +.Li unsigned char ) back onto the input stream pointed to by .Fa stream . The pushed-backed characters will be returned by subsequent reads on the -- 2.20.1