From 2ff5e0d02e9d828995f3b64ee5436a9801b367d4 Mon Sep 17 00:00:00 2001 From: gdr Date: Tue, 16 Sep 1997 00:11:30 +0000 Subject: [PATCH] added various stdio man pages --- usr.man/man3/clearerr.3 | 97 ++++++ usr.man/man3/ecvt.3 | 59 ++++ usr.man/man3/fclose.3 | 90 ++++++ usr.man/man3/fflush.3 | 107 +++++++ usr.man/man3/fgets.3 | 152 ++++++++++ usr.man/man3/fputs.3 | 101 +++++++ usr.man/man3/fread.3 | 103 +++++++ usr.man/man3/fseek.3 | 183 ++++++++++++ usr.man/man3/getc.3 | 133 +++++++++ usr.man/man3/isblank.3 | 53 ++++ usr.man/man3/isinf.3 | 71 +++++ usr.man/man3/printf.3 | 639 ++++++++++++++++++++++++++++++++++++++++ usr.man/man3/putc.3 | 126 ++++++++ usr.man/man3/remove.3 | 79 +++++ usr.man/man3/scanf.3 | 429 +++++++++++++++++++++++++++ usr.man/man3/setbuf.3 | 193 ++++++++++++ usr.man/man3/stdio.3 | 283 ++++++++++++++++++ usr.man/man3/ungetc.3 | 90 ++++++ 18 files changed, 2988 insertions(+) create mode 100644 usr.man/man3/clearerr.3 create mode 100644 usr.man/man3/ecvt.3 create mode 100644 usr.man/man3/fclose.3 create mode 100644 usr.man/man3/fflush.3 create mode 100644 usr.man/man3/fgets.3 create mode 100644 usr.man/man3/fputs.3 create mode 100644 usr.man/man3/fread.3 create mode 100644 usr.man/man3/fseek.3 create mode 100644 usr.man/man3/getc.3 create mode 100644 usr.man/man3/isblank.3 create mode 100644 usr.man/man3/isinf.3 create mode 100644 usr.man/man3/printf.3 create mode 100644 usr.man/man3/putc.3 create mode 100644 usr.man/man3/remove.3 create mode 100644 usr.man/man3/scanf.3 create mode 100644 usr.man/man3/setbuf.3 create mode 100644 usr.man/man3/stdio.3 create mode 100644 usr.man/man3/ungetc.3 diff --git a/usr.man/man3/clearerr.3 b/usr.man/man3/clearerr.3 new file mode 100644 index 0000000..a5be88a --- /dev/null +++ b/usr.man/man3/clearerr.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ferror.3 8.2 (Berkeley) 4/19/94 +.\" +.TH FERROR 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno +\- check and reset stream status +.SH SYNOPSIS +#include +.sp 1 +void \fBclearerr\fR (FILE *\fIstream\fR); +.br +int \fBfeof\fR (FILE *\fIstream\fR); +.br +int \fBferror\fR (FILE *\fIstream\fR); +.br +int \fBfileno\fR (FILE *\fIstream\fR); +.SH DESCRIPTION +The function +.BR clearerr +clears the end-of-file and error indicators for the stream pointed +to by +.IR stream . +.LP +The function +.BR feof +tests the end-of-file indicator for the stream pointed to by +.IR stream , +returning non-zero if it is set. +The end-of-file indicator can only be cleared by the function +.BR clearerr . +.LP +The function +.BR ferror +tests the error indicator for the stream pointed to by +.IR stream , +returning non-zero if it is set. +The error indicator can only be reset by the +.BR clearerr +function. +.LP +The function +.BR fileno +examines the argument +.I stream +and returns its integer descriptor. +.SH ERRORS +These functions should not fail and do not set the external +variable +.IR errno . +.SH SEE ALSO +.BR open (2), +.BR stdio (3) +.SH STANDARDS +The functions +.BR clearerr , +.BR feof , +and +.BR ferror +conform to ANSI/C. diff --git a/usr.man/man3/ecvt.3 b/usr.man/man3/ecvt.3 new file mode 100644 index 0000000..0b8ac9c --- /dev/null +++ b/usr.man/man3/ecvt.3 @@ -0,0 +1,59 @@ +.\" This manual page is derived from Linux sources. +.\" +.\" Devin Reade, 1997 +.\" +.\" $Id: ecvt.3,v 1.1 1997/09/16 00:11:29 gdr Exp $ +.\" +.TH ECVT 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR ecvt , +.BR fcvt +\- convert a floating-point number to a string +.SH SYNOPSIS +#include +.sp 1 +char *\fBecvt\fR (double \fInumber\fR, size_t \fIndigits\fR, int *\fIdecpt\fR, int *\fIsign\fR); +.br +char *\fBfcvt\fR (double \fInumber\fR, size_t \fIndigits\fR, int *\fIdecpt\fR, int *\fIsign\fR); +.SH DESCRIPTION +The +.BR ecvt +function converts +.IR number +to a NULL terminated string of +.IR ndigits +digits, and returns a pointer to the string. The string itself does not +contain a decimal point; however, the position of the decimal point relative +to the start of the string is stored in +.IR decpt . +A negative value for +.IR decpt +means that the decimal point is to the left of the start of the string. +If the sign of +.IR number +is negative, +.IR sign +is set to a non-zero value, otherwise it's set to 0. +.LP +The +.BR fcvt +function is identical to +.BR ecvt , +except that +.IR ndigits +specifies the number of digits after the decimal point. +.SH RETURN VALUE +Both the +.BR ecvt +and +.BR fcvt +functions return a pointer to a static string containing the ASCII +representation of +.IR number . +The static string is overwritten by each call to +.BR ecvt +or +.BR fcvt . +.SH SEE ALSO +.BR gcvt (3), +.BR sprintf (3) diff --git a/usr.man/man3/fclose.3 b/usr.man/man3/fclose.3 new file mode 100644 index 0000000..fc9072c --- /dev/null +++ b/usr.man/man3/fclose.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fclose.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FCLOSE 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fclose +\- close a stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfclose\fR (FILE *\fIstream\fR); +.SH DESCRIPTION +The +.BR fclose +function +dissociates the named +.I stream +from its underlying file or set of functions. +If the stream was being used for output, any buffered data is written +first, using +.BR fflush (3). +.SH RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, +.BR EOF +is returned and the global variable +.IR errno +is set to indicate the error. +In either case no further access to the stream is possible. +.SH ERRORS +.RS +.IP \fBEBADF\fR +The argument +.I stream +is not an open stream. +.RE +.LP +The +.BR fclose +function +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR close (2) +or +.BR fflush (3). +.SH SEE ALSO +.BR close (2), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) +.SH STANDARDS +The +.BR fclose +function +conforms to ANSI/C. diff --git a/usr.man/man3/fflush.3 b/usr.man/man3/fflush.3 new file mode 100644 index 0000000..3edb9d0 --- /dev/null +++ b/usr.man/man3/fflush.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fflush.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FFLUSH 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fflush , +.BR fpurge +\- flush a stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfflush\fR (FILE *\fIstream\fR); +.br +int \fBfpurge\fR (FILE *\fIstream\fR); +.SH DESCRIPTION +The function +.BR fflush +forces a write of all buffered data for the given output or update +.I stream +via the stream's underlying write function. +The open status of the stream is unaffected. +.LP +If the +.I stream +argument is +.BR NULL , +.BR fflush +flushes +.IR all +open output streams. +.LP +The function +.BR fpurge +erases any input or output buffered in the given +.IR stream . +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.BR getc (3); +this includes any text pushed back via +.BR ungetc . +.SH RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, +.BR EOF +is returned and the global variable +.IR errno +is set to indicate the error. +.SH ERRORS +.RS +.IP \fBEBADF\fR +.I Stream +is not an open stream, or, in the case of +.BR fflush , +not a stream open for writing. +.RE +.LP +The function +.BR fflush +may also fail and set +.IR errno +for any of the errors specified for the routine +.BR write (2). +.SH SEE ALSO +.BR write (2), +.BR fopen (3), +.BR fclose (3), +.BR setbuf (3) +.SH STANDARDS +The +.BR fflush +function +conforms to ANSI/C. diff --git a/usr.man/man3/fgets.3 b/usr.man/man3/fgets.3 new file mode 100644 index 0000000..56d6ef9 --- /dev/null +++ b/usr.man/man3/fgets.3 @@ -0,0 +1,152 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FGETS 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fgets , +.BR gets +\- get a line from a stream +.SH SYNOPSIS +#include +.sp 1 +char *\fBfgets\fR (char *\fIstr\fR, size_t \fIsize\fR, FILE *\fIstream\fR); +.br +char *\fBgets\fR (char *\fIstr\fR); +.SH DESCRIPTION +The +.BR fgets +function +reads at most one less than the number of characters specified by +.I size +from the given +.I stream +and stores them in the string +.IR str . +Reading stops when a newline character is found, +at end-of-file or error. +The newline, if any, is retained. +If any characters are read and there is no error, a +.BR \e0 +character is appended to end the string. +.LP +The +.BR gets +function +is equivalent to +.BR fgets +with an infinite +.I size +and a +.I stream +of +.IR stdin , +except that the newline character (if any) is not stored in the string. +It is the caller's responsibility to ensure that the input line, +if any, is sufficiently short to fit in the string. +.SH RETURN VALUES +.LP +Upon successful completion, +.BR fgets +and +.BR gets +return +a pointer to the string. +If end-of-file occurs before any characters are read, +they return +.BR NULL +and the buffer contents is unchanged. +If an error occurs, +they return +.BR NULL +and the buffer contents is indeterminate. +The +.BR fgets +and +.BR gets +functions +do not distinguish between end-of-file and error, and callers must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +.SH ERRORS +.RS +.IP \fBEBADF\fR +The given +.I stream +is not a readable stream. +.RE +.LP +The function +.BR fgets +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR read (2), +or +.BR malloc (3). +.LP +The function +.BR gets +may also fail and set +.IR errno +for any of the errors specified for the routine +.BR getchar (3). +.SH SEE ALSO +.BR feof (3), +.BR ferror (3), +.BR fgetln (3) +.SH STANDARDS +The functions +.BR fgets +and +.BR gets +conform to ANSI/C. +.SH BUGS +Since it is usually impossible to ensure that the next input line +is less than some arbitrary length, and because overflowing the +input buffer is almost invariably a security violation, programs +should +.IR NEVER +use +.BR gets . +The +.BR gets +function +exists purely to conform to ANSI/C. diff --git a/usr.man/man3/fputs.3 b/usr.man/man3/fputs.3 new file mode 100644 index 0000000..c476951 --- /dev/null +++ b/usr.man/man3/fputs.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fputs.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FPUTS 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fputs , +.BR puts +\- output a line to a stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfputs\fR (const char *\fIstr\fR, FILE *\fIstream\fR); +.br +int \fBputs\fR (const char *\fIstr\fR); +.SH DESCRIPTION +The function +.BR fputs +writes the string pointed to by +.I str +to the stream pointed to by +.IR stream . +.LP +The function +.BR puts +writes the string +.IR str +and a terminating newline character, +to the stream +.IR stdout . +.SH RETURN VALUES +The +.BR fputs +function +returns 0 on success and +.BR EOF +on error; +.BR puts +returns a nonnegative integer on success and +.BR EOF +on error. +.SH ERRORS +.RS +.IP \fBEBADF\fR +The +.I stream +supplied +is not a writable stream. +.RE +.LP +The functions +.BR fputs +and +.BR puts +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR write (2). +.SH SEE ALSO +.BR putc (3), +.BR ferror (3), +.BR stdio (3) +.SH STANDARDS +The functions +.BR fputs +and +.BR puts +conform to ANSI/C. diff --git a/usr.man/man3/fread.3 b/usr.man/man3/fread.3 new file mode 100644 index 0000000..0db4c30 --- /dev/null +++ b/usr.man/man3/fread.3 @@ -0,0 +1,103 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fread.3 8.2 (Berkeley) 3/8/94 +.\" +.TH FREAD 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fread , +.BR fwrite +\- binary stream input/output +.SH SYNOPSIS +#include +.sp 1 +size_t \fBfread\fR (void *\fIptr\fR, size_t \fIsize\fR, size_t \fInmemb\fR, FILE *\fIstream\fR); +.br +size_t \fBfwrite\fR (const void *\fIptr\fR, size_t \fIsize\fR, size_t \fInmemb\fR, FILE *\fIstream\fR); +.SH DESCRIPTION +The function +.BR fread +reads +.I nmemb +objects, each +.I size +bytes long, from the stream pointed to by +.IR stream , +storing them at the location given by +.IR ptr . +.LP +The function +.BR fwrite +writes +.I nmemb +objects, each +.I size +bytes long, to the stream pointed to by +.IR stream , +obtaining them from the location given by +.IR ptr . +.SH RETURN VALUES +The functions +.BR fread +and +.BR fwrite +advance the file position indicator for the stream +by the number of bytes read or written. +They return the number of objects read or written. +If an error occurs, or the end-of-file is reached, +the return value is a short object count (or zero). +.LP +The function +.BR fread +does not distinguish between end-of-file and error, and callers +must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +The function +.BR fwrite +returns a value less than +.I nmemb +only if a write error has occurred. +.SH SEE ALSO +.BR read (2), +.BR write (2) +.SH STANDARDS +The functions +.BR fread +and +.BR fwrite +conform to ANSI/C. diff --git a/usr.man/man3/fseek.3 b/usr.man/man3/fseek.3 new file mode 100644 index 0000000..d6c9eb7 --- /dev/null +++ b/usr.man/man3/fseek.3 @@ -0,0 +1,183 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FSEEK 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fgetpos , +.BR fseek , +.BR fsetpos , +.BR ftell , +.BR rewind +\- reposition a stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfseek\fR (FILE *\fIstream\fR, long \fIoffset\fR, int \fIwhence\fR); +.br +long \fBftell\fR (FILE *\fIstream\fR); +.br +void \fBrewind\fR (FILE *\fIstream\fR); +.br +int \fBfgetpos\fR (FILE *\fIstream\fR, fpos_t *\fIpos\fR); +.br +int \fBfsetpos\fR (FILE *\fIstream\fR, fpos_t *\fIpos\fR); +.SH DESCRIPTION +The +.BR fseek +function sets the file position indicator for the stream pointed +to by +.IR stream . +The new position, measured in bytes, is obtained by adding +.I offset +bytes to the position specified by +.IR whence . +If +.I whence +is set to +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +the offset is relative to the +start of the file, the current position indicator, or end-of-file, +respectively. +A successful call to the +.BR fseek +function clears the end-of-file indicator for the stream and undoes +any effects of the +.BR ungetc (3) +function on the same stream. +.LP +The +.BR ftell +function +obtains the current value of the file position indicator for the +stream pointed to by +.IR stream . +.LP +The +.BR rewind +function sets the file position indicator for the stream pointed +to by +.I stream +to the beginning of the file. +It is equivalent to: +.RS + (void) fseek(stream, 0L, SEEK_SET) +.RE +except that the error indicator for the stream is also cleared +(see +.BR clearerr (3)). +.LP +The +.BR fgetpos +and +.BR fsetpos +functions +are alternate interfaces equivalent to +.BR ftell +and +.BR fseek +(with whence set to \fBSEEK_SET\fR), +setting and storing the current value of +the file offset into or from the object referenced by +.IR pos . +On some non-UNIX +systems an +.B fpos_t +object may be a complex object +and these routines may be the only way to portably reposition a text stream. +.SH RETURN VALUES +The +.BR rewind +function +returns no value. +Upon successful completion, +.BR fgetpos , +.BR fseek , +.BR fsetpos +return 0, +and +.BR ftell +returns the current offset. +Otherwise, \-1 is returned and the global variable errno is set to +indicate the error. +.SH ERRORS +.RS +.IP \fBEBADF\fR +The +.I stream +specified +is not a seekable stream. +.IP \fBEINVAL\fR +The +.I whence +argument to +.BR fseek +was not +.BR SEEK_SET , +.BR SEEK_END , +or +.BR SEEK_CUR . +.RE +.LP +The function +.BR fgetpos , +.BR fseek , +.BR fsetpos , +and +.BR ftell +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR lseek (2), +and +.BR malloc (3). +.SH SEE ALSO +.BR lseek (2) +.SH STANDARDS +The +.BR fgetpos , +.BR fsetpos , +.BR fseek , +.BR ftell , +and +.BR rewind +functions +conform to ANSI/C. diff --git a/usr.man/man3/getc.3 b/usr.man/man3/getc.3 new file mode 100644 index 0000000..836d14e --- /dev/null +++ b/usr.man/man3/getc.3 @@ -0,0 +1,133 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getc.3 8.1 (Berkeley) 6/4/93 +.\" +.TH GETC 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fgetc , +.BR getc , +.BR getchar , +.BR getw +\- get next character or word from input stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfgetc\fR (FILE *\fIstream\fR); +.br +int \fBgetc\fR (FILE *\fIstream\fR); +.br +int \fBgetchar\fR (void); +.br +int \fBgetw\fR (FILE *\fIstream\fR); +.SH DESCRIPTION +The +.BR fgetc +function +obtains the next input character (if present) from the stream pointed at by +.IR stream , +or the next character pushed back on the stream via +.BR ungetc (3). +.LP +The +.BR getc +function +acts essentially identically to +.BR fgetc , +but is a macro that expands in-line. +.LP +The +.BR getchar +function +is equivalent to: +getc with the argument stdin. +.LP +The +.BR getw +function +obtains the next +.IR int +(if present) +from the stream pointed at by +.IR stream . +.SH RETURN VALUES +If successful, these routines return the next requested object +from the +.IR stream . +If the stream is at end-of-file or a read error occurs, +the routines return +.BR EOF . +The routines +.BR feof (3) +and +.BR ferror (3) +must be used to distinguish between end-of-file and error. +If an error occurs, the global variable +.IR errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.BR EOF +until the condition is cleared with +.BR clearerr (3). +.SH SEE ALSO +.BR ferror (3), +.BR fread (3), +.BR fopen (3), +.BR putc (3), +.BR ungetc (3) +.SH STANDARDS +The +.BR fgetc , +.BR getc +and +.BR getchar +functions +conform to ANSI/C. +.SH BUGS +Since +.BR EOF +is a valid integer value, +.BR feof (3) +and +.BR ferror (3) +must be used to check for failure after calling +.BR getw . +The size and byte order of an +.IR int +varies from one machine to another, and +.BR getw +is not recommended for portable applications. +.LP diff --git a/usr.man/man3/isblank.3 b/usr.man/man3/isblank.3 new file mode 100644 index 0000000..b394413 --- /dev/null +++ b/usr.man/man3/isblank.3 @@ -0,0 +1,53 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isblank.3 8.1 (Berkeley) 6/4/93 +.\" +.TH ISBLANK 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR isblank +\- space or tab character test +.SH SYNOPSIS +#include +.sp 1 +int \fBisblank\fR (int \fIc\fR); +.SH DESCRIPTION +The +.BR isblank +function tests for a space or tab character. +.SH RETURN VALUES +The +.BR isblank +function returns zero if the character tests false and +returns non-zero if the character tests true. +.SH SEE ALSO +.BR ctype (3), +.BR ascii (7) diff --git a/usr.man/man3/isinf.3 b/usr.man/man3/isinf.3 new file mode 100644 index 0000000..d294783 --- /dev/null +++ b/usr.man/man3/isinf.3 @@ -0,0 +1,71 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isinf.3 8.2 (Berkeley) 1/29/94 +.\" +.TH ISINF 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR isinf , +.BR isnan +\- test for infinity or not-a-number +.SH SYNOPSIS +#include +.sp 1 +int +.BR isinf (extended); +.br +int +.BR isnan (extended); +.SH DESCRIPTION +The +.BR isinf +function +returns 1 if the number is +.IR "+/- Infinity" , +otherwise 0. +.LP +The +.BR isnan +function +returns 1 if the number is +.IR not-a-number " (NaN)," +otherwise 0. +.SH SEE ALSO +.BR math (3), +.sp 1 +.IR "IEEE Standard for Binary Floating-Point Arithmetic" , +ANSI Std 754-1985 +.sp 1 +.IR "Apple Numerics Manual " "(SANE)" +.SH BUGS +Neither the VAX nor the Tahoe floating point have distinguished values +for either infinity or not-a-number. +These routines always return 0 on those architectures. diff --git a/usr.man/man3/printf.3 b/usr.man/man3/printf.3 new file mode 100644 index 0000000..e444ce8 --- /dev/null +++ b/usr.man/man3/printf.3 @@ -0,0 +1,639 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 +.\" +.TH PRINTF 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR printf , +.BR fprintf , +.BR sprintf , +.BR snprintf , +.BR vprintf , +.BR vfprintf, +.BR vsprintf , +.BR vsnprintf +\- formatted output conversion +.SH SYNOPSIS +#include +.sp 1 +int \fBprintf\fR (const char *\fIformat\fR, ...); +.br +int \fBfprintf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, ...); +.br +int \fBsprintf\fR (char *\fIstr\fR, const char *\fIformat\fR, ...); +.br +int \fBsnprintf\fR (char *\fIstr\fR, size_t \fIsize\fR, const char *\fIformat\fR, ...); +.\" .br +.\" int \fBsmprintf\fR (const char *\fIformat\fR, ...); +.sp 1 +#include +.sp 1 +int \fBvprintf\fR (const char *\fIformat\fR, va_list \fIap\fR); +.br +int \fBvfprintf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, va_list \fIap\fR); +.br +int \fBvsprintf\fR (char *\fIstr\fR, char *\fIformat\fR, va_list \fIap\fR); +.br +int \fBvsnprintf\fR (char *\fIstr\fR, size_t \fIsize\fR, const char *\fIformat\fR, va_list \fIap\fR); +.\" .br +.\" int \fBvsmprintf\fR (const char *\fIformat\fR, va_list \fIap\fR); +.SH DESCRIPTION +The +.BR printf +family of functions produces output according to a +.I format +as described below. +.BR Printf +and +.BR vprintf +write output to +.IR stdout, +the standard output stream; +.BR fprintf +and +.BR vfprintf +write output to the given output +.IR stream . +.BR sprintf , +.BR snprintf , +.BR vsprintf , +and +.BR vsnprintf +write to the character string +.IR str . +.\" .IR str ; +.\" and +.\" .I smprintf +.\" and +.\" .I vsmprintf +.\" dynamically allocate a new string with +.\" .IR malloc . +These functions write the output under the control of a +.I format +string that specifies how subsequent arguments +(or arguments accessed via the variable-length argument facilities of +.BR stdarg (3)) +are converted for output. +.\" Except for +.\" .I smprintf +.\" and +.\" .IR vsmprintf , +.\" all of these functions return +These functions return +the number of characters printed +(not including the trailing +.BR \e0 +used to end output to strings). +.\" .I Smprintf +.\" and +.\" .I vsmprintf +.\" return a pointer to a string of an appropriate length; +.\" this pointer should be passed to +.\" .I free +.\" to release the associated storage +.\" when it is no longer needed. +.\" If sufficient space is not avaliable, +.\" .I smprintf +.\" and +.\" .I vsmprintf +.\" will return +.\" .SM +.\" .BR +.BR Snprintf +and +.BR vsnprintf +will write at most +.IR size +of the characters printed into the output string +(the +.I size +character then gets the terminating +.BR \e0 ); +if the return value is greater than or equal to the +.I size +argument, the string was too short +and some of the printed characters were discarded. +.BR Sprintf +and +.BR vsprintf +effectively assume an infinite +.IR size . +.LP +The format string is composed of zero or more directives: +ordinary +.\" multibyte +characters (not +.BR % ), +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 +.BR % . +The arguments must correspond properly (after type promotion) +with the conversion specifier. +After the +.BR % , +the following appear in sequence: +.RS +.sp 1 +Zero or more of the following flags: +.RS +A +.BR # +character +specifying that the value should be converted to an ``alternate form''. +For +.BR c , +.BR d , +.BR i , +.BR n , +.BR p , +.BR s , +and +.BR u , +conversions, this option has no effect. +For +.BR o +conversions, the precision of the number is increased to force the first +character of the output string to a zero (except if a zero value is printed +with an explicit precision of zero). +For +.BR x +and +.BR X +conversions, a non-zero result has the string +.BR 0x +(or +.BR 0X +for +.BR X +conversions) prepended to it. +For +.BR e , +.BR E , +.BR f , +.BR g , +and +.BR G , +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of +those conversions only if a digit follows). +For +.BR g +and +.BR G +conversions, trailing zeros are not removed from the result as they +would otherwise be. +.sp 1 +A zero +.RB ( \&0 ) +character specifying zero padding. +For all conversions except +.BR n , +the converted value is padded on the left with zeros rather than blanks. +If a precision is given with a numeric conversion +.BR d , +.BR i , +.BR o , +.BR u , +.BR i , +.BR x , +and +.BR X ) , +the +.BR \&0 +flag is ignored. +.sp 1 +A negative field width flag +.RB ( \- ) +indicates the converted value is to be left adjusted on the field boundary. +Except for +.BR n +conversions, the converted value is padded on the right with blanks, +rather than on the left with blanks or zeros. +A +.B \- +overrides a +.B \&0 +if both are given. +.sp 1 +A space, specifying that a blank should be left before a positive number +produced by a signed conversion +.RB ( d , +.BR e , +.BR E , +.BR f , +.BR g , +.BR G , +or +.BR i ). +.sp 1 +A +.B + +character specifying that a sign always be placed before a +number produced by a signed conversion. +A +.B + +overrides a space if both are used. +.RE +.sp 1 +An optional decimal digit string specifying a minimum field width. +If the converted value has fewer characters than the field width, it will +be padded with spaces on the left (or right, if the left-adjustment +flag has been given) to fill out +the field width. +.sp 1 +An optional precision, in the form of a period +.RB ( \&. ) +followed by an +optional digit string. If the digit string is omitted, the precision +is taken as zero. This gives the minimum number of digits to appear for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversions, the number of digits to appear after the decimal-point for +.BR e , +.BR E , +and +.BR f +conversions, the maximum number of significant digits for +.BR g +and +.BR G +conversions, or the maximum number of characters to be printed from a +string for +.BR s +conversions. +.sp 1 +The optional character +.BR h , +specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion corresponds to a +.IR "short int" +or +.IR "unsigned short int" +argument, or that a following +.BR n +conversion corresponds to a pointer to a +.IR "short int" +argument. +.sp 1 +The optional character +.BR l +(ell) specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion applies to a pointer to a +.IR "long int" +or +.IR "unsigned long int" +argument, or that a following +.BR n +conversion corresponds to a pointer to a +.IR "long int" +argument. +.sp 1 +The optional character +.BR q , +specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion corresponds to a +.IR "quad int" +or +.IR "unsigned quad int" +argument, or that a following +.BR n +conversion corresponds to a pointer to a +.IR "quad int" +argument. +.sp 1 +The character +.BR L +specifying that a following +.BR e , +.BR E , +.BR f , +.BR g , +or +.BR G +conversion corresponds to a +.IR "long double" +argument (but note that long double values are not currently supported +by the ORCA/C, VAX, and Tahoe compilers). +.sp 1 +A character that specifies the type of conversion to be applied. +.RE +.LP +A field width or precision, or both, may be indicated by +an asterisk +.BR * +instead of a +digit string. +In this case, an +.IR 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 +missing. +.LP +The conversion specifiers and their meanings are: +.RS +.IP \fBdiouxX\fR +The +.IR int +(or appropriate variant) argument is converted to signed decimal +.RB ( d +and +.BR i ), +unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal +.RB ( x +and +.BR X ) +notation. The letters +.BR abcdef +are used for +.BR x +conversions; the letters +.BR ABCDEF +are used for +.BR X +conversions. +The precision, if any, gives the minimum number of digits that must +appear; if the converted value requires fewer digits, it is padded on +the left with zeros. +.IP \fBDOU\fR +The +.IR "long int" +argument is converted to signed decimal, unsigned octal, or unsigned +decimal, as if the format had been +.BR ld , +.BR lo , +or +.BR lu +respectively. +These conversion characters are deprecated, and will eventually disappear. +.IP \fBeE\fR +The +.IR double +argument is rounded and converted in the style +.nf + [\-]\fId\fR\&.\fIddd\fRe(+|-)\fIdd\fR +.fi +where there is one digit before the +decimal-point character +and the number of digits after it is equal to the precision; +if the precision is missing, +it is taken as 6; if the precision is +zero, no decimal-point character appears. +An +.BR E +conversion uses the letter +.BR E +(rather than +.BR e ) +to introduce the exponent. +The exponent always contains at least two digits; if the value is zero, +the exponent is 00. +.IP \fBf\fR +The +.IR double +argument is rounded and converted to decimal notation in the style +.nf + [-]\fIddd\fR\&.\fIddd\fR, +.fi +where the number of digits after the decimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as 6; if the precision is +explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.IP \fBg\fR +The +.IR double +argument is converted in style +.BR f +or +.BR e +(or +.BR E +for +.BR G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.BR e +is used if the exponent from its conversion is less than -4 or greater than +or equal to the precision. +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. +.IP \fBc\fR +The +.IR int +argument is converted to an +.IR "unsigned char" , +and the resulting character is written. +.IP \fBs\fR +The +.I "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 +.BR NULL +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 +.BR NUL +character. +.IP \fBp\fR +The +.I "void *" +pointer argument is printed in hexadecimal (as if by +.BR %#x +or +.BR %#lx ). +.IP \fBn\fR +The number of characters written so far is stored into the +integer indicated by the +.I "int *" +(or variant) pointer argument. +No argument is converted. +.IP \fB%\fR +A +.BR % +is written. No argument is converted. The complete conversion specification +is +.BR %% . +.RE +.LP +In no case does a non-existent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.LP +.SH EXAMPLES +To print a date and time in the form `Sunday, July 3, 10:02', +where +.IR weekday +and +.IR month +are pointers to strings: +.nf + +#include +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); + +.fi +.LP +To print Pi +to five decimal places: +.nf + +#include +#include +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); + +.fi +.LP +To allocate a 128 byte string and print into it: +.nf + +#include +#include +#include +char *newfmt(const char *fmt, ...) +{ + char *p; + va_list ap; + if ((p = malloc(128)) == NULL) + return (NULL); + va_start(ap, fmt); + (void) vsnprintf(p, 128, fmt, ap); + va_end(ap); + return (p); +} +.fi +.SH SEE ALSO +.BR printf (1), +.BR scanf (3) +.SH STANDARDS +The +.BR fprintf , +.BR printf , +.BR sprintf , +.BR vprintf , +.BR vfprintf , +and +.BR vsprintf +functions +conform to ANSI/C. +.SH HISTORY +The functions +.BR snprintf +and +.BR vsnprintf +are new to this release. +.SH BUGS +The ORCA/C stdio implementation also provides a +.BR %b +format specifier, for Pascal-type strings. This is not currently implemented. +.LP +The conversion formats +.BR \&%D , +.BR \&%O , +and +.BR %U +are not standard and +are provided only for backward compatibility. +The effect of padding the +.BR %p +format with zeros (either by the +.B 0 +flag or by specifying a precision), and the benign effect (i.e., none) +of the +.B # +flag on +.BR %n +and +.BR %p +conversions, as well as other +nonsensical combinations such as +.BR %Ld , +are not standard; such combinations +should be avoided. +.LP +Because +.BR sprintf +and +.BR vsprintf +assume an infinitely long string, +callers must be careful not to overflow the actual space; +this is often impossible to assure. +For safety, programmers should use the +.BR snprintf +interface instead. +Unfortunately, this interface is not portable. diff --git a/usr.man/man3/putc.3 b/usr.man/man3/putc.3 new file mode 100644 index 0000000..a0a775b --- /dev/null +++ b/usr.man/man3/putc.3 @@ -0,0 +1,126 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)putc.3 8.1 (Berkeley) 6/4/93 +.\" +.TH PUTC 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fputc , +.BR putc , +.BR putchar , +.BR putw +\- output a character or word to a stream +.SH SYNOPSIS +#include +.sp 1 +int \fBfputc\fR (int \fIc\fR, FILE *\fIstream\fR); +.br +int \fBputc\fR (int \fIc\fR, FILE *\fIstream\fR); +.br +int \fBputchar\fR (int \fIc\fR); +.br +int \fBputw\fR (int \fIw\fR, FILE *\fIstream\fR); +.SH DESCRIPTION +The +.BR fputc +function +writes the character +.I c +(converted to an ``unsigned char'') +to the output stream pointed to by +.IR stream . +.LP +.BR Putc +acts essentially identically to +.BR fputc , +but is a macro that expands in-line. It may evaluate +.I stream +more than once, so arguments given to +.BR putc +should not be expressions with potential side effects. +.LP +.BR Putchar +is identical to +.BR putc +with an output stream of +.IR stdout . +.LP +The +.BR putw +function +writes the specified +.IR int +to the named output +.IR stream . +.SH RETURN VALUES +The functions, +.BR fputc , +.BR putc +and +.BR putchar +return the character written. +If an error occurs, the value +.BR EOF +is returned. +The +.BR putw +function +returns 0 on success; +.BR EOF +is returned if +a write error occurs, +or if an attempt is made to write a read-only stream. +.SH SEE ALSO +.BR ferror (3), +.BR fopen (3), +.BR getc (3), +.BR stdio (3) +.SH STANDARDS +The functions +.BR fputc , +.BR putc , +and +.BR putchar , +conform to ANSI/C. +A function +.BR putw +function appeared in +.BR v6 . +.SH BUGS +The size and byte order of an +.IR int +varies from one machine to another, and +.BR putw +is not recommended for portable applications. diff --git a/usr.man/man3/remove.3 b/usr.man/man3/remove.3 new file mode 100644 index 0000000..26bf970 --- /dev/null +++ b/usr.man/man3/remove.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)remove.3 8.1 (Berkeley) 6/4/93 +.\" +.TH REMOVE 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR remove +\- remove directory entry +.SH SYNOPSIS +#include +.sp 1 +int \fBremove\fR (const char *\fIpath\fR); +.SH DESCRIPTION +The +.BR remove +function +is an alias for the +.BR unlink (2) +system call. +It deletes the file referenced by +.IR path . +.SH RETURN VALUES +Upon successful completion, +.BR remove +returns 0. +Otherwise, \-1 is returned and the global variable +.IR errno +is set to indicate the error. +.SH ERRORS +The +.BR remove +function +may fail and set +.IR errno +for any of the errors specified for the routine +.BR unlink (2). +.SH BUGS +See the BUGS section of the +.BR unlink (2) +manual page. +.SH SEE ALSO +.BR unlink (2) +.SH STANDARDS +The +.BR remove +function conforms to ANSI/C. diff --git a/usr.man/man3/scanf.3 b/usr.man/man3/scanf.3 new file mode 100644 index 0000000..35eb96f --- /dev/null +++ b/usr.man/man3/scanf.3 @@ -0,0 +1,429 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93 +.\" +.TH SCANF 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR scanf , +.BR fscanf , +.BR sscanf , +.BR vscanf , +.BR vsscanf , +.BR vfscanf +\- input format conversion +.SH SYNOPSIS +#include +.sp 1 +int \fBscanf\fR (const char *\fIformat\fR, ...); +.br +int \fBfscanf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, ...); +.br +int \fBsscanf\fR (const char *\fIstr\fR, const char *\fIformat\fR, ...); +.sp 1 +#include +.sp 1 +int \fBvscanf\fR (const char *\fIformat\fR, va_list \fIap\fR); +.br +int \fBvsscanf\fR (const char *\fIstr\fR, const char *\fIformat\fR, va_list \fIap\fR); +.br +int \fBvfscanf\fR (FILE *\fIstream\fR, const char *\fIformat\fR, va_list \fIap\fR); +.SH DESCRIPTION +The +.BR scanf +family of functions scans input according to a +.I format +as described below. +This format may contain +.IR "conversion specifiers" ; +the results from such conversions, if any, +are stored through the +.IR pointer +arguments. +.LP +The +.BR scanf +function +reads input from the standard input stream +.IR stdin , +.BR fscanf +reads input from the stream pointer +.IR stream , +and +.BR sscanf +reads its input from the character string pointed to by +.IR str . +The +.BR vfscanf +function +is analogous to +.BR vfprintf (3) +and reads input from the stream pointer +.I stream +using a variable argument list of pointers (see +.BR stdarg (3)). +The +.BR vscanf +function scans a variable argument list from the standard input and +the +.BR vsscanf +function scans it from a string; +these are analogous to +the +.BR vprintf +and +.BR vsprintf +functions respectively. +.LP +Each successive +.IR pointer +argument must correspond properly with +each successive conversion specifier +(but see `suppression' below). +All conversions are introduced by the +.BR % +(percent sign) character. +The +.I format +string +may also contain other characters. +White space (such as blanks, tabs, or newlines) in the +.I format +string match any amount of white space, 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). +.SH CONVERSIONS +Following the +.BR % +character introducing a conversion +there may be a number of +.IR flag +characters, as follows: +.RS +.IP \fB*\fR +Suppresses assignment. +The conversion that follows occurs as usual, but no pointer is used; +the result of the conversion is simply discarded. +.IP \fBh\fR +Indicates that the conversion will be one of +.BR dioux +or +.BR n +and the next pointer is a pointer to a +.IR "short int" +(rather than +.IR int ). +.IP \fBl\fR +Indicates either that the conversion will be one of +.BR dioux +or +.BR n +and the next pointer is a pointer to a +.IR "long int" +(rather than +.IR int ), +or that the conversion will be one of +.BR efg +and the next pointer is a pointer to +.IR double +(rather than +.IR float ). +.IP \fBL\fR +Indicates that the conversion will be +.BR efg +and the next pointer is a pointer to +.IR "long double" . +(This type is not implemented; the +.BR L +flag is currently ignored.) +.RE +.LP +In addition to these flags, +there may be an optional maximum field width, +expressed as a decimal integer, +between the +.BR % +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 white space; +this white space is not counted against the field width. +.LP +The following conversions are available: +.RS +.IP \fB%\fR +Matches a literal `%'. +That is, `%\&%' in the format string +matches a single input `%' character. +No conversion is done, and assignment does not occur. +.IP \fBd\fR +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR int . +.IP \fBD\fR +Equivalent to +.BR ld ; +this exists only for backwards compatibility. +.IP \fBi\fR +Matches an optionally signed integer; +the next pointer must be a pointer to +.IR int . +The integer is read in base 16 if it begins +with +.BR 0x +or +.BR 0X , +in base 8 if it begins with +.BR 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.IP \fBo\fR +Matches an octal integer; +the next pointer must be a pointer to +.IR "unsigned int" . +.IP \fBO\fR +Equivalent to +.BR lo ; +this exists for backwards compatibility. +.IP \fBu\fR +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR "unsigned int" . +.IP \fBx\fR +Matches an optionally signed hexadecimal integer; +the next pointer must be a pointer to +.IR "unsigned int" . +.IP \fBX\fR +Equivalent to +.BR lx ; +this violates the ANSI/C standard, +but is backwards compatible with previous +UNIX systems. +.IP \fBf\fR +Matches an optionally signed floating-point number; +the next pointer must be a pointer to +.IR float . +.IP \fBe\fR +Equivalent to +.BR f . +.IP \fBg\fR +Equivalent to +.BR f . +.IP \fBE\fR +Equivalent to +.BR lf ; +this violates the ANSI/C standard, +but is backwards compatible with previous +UNIX systems. +.IP \fBF\fR +Equivalent to +.BR lf ; +this exists only for backwards compatibility. +.IP \fBs\fR +Matches a sequence of non-white-space characters; +the next pointer must be a pointer to +.IR char , +and the array must be large enough to accept all the sequence and the +terminating +.BR NUL +character. +The input string stops at white space +or at the maximum field width, whichever occurs first. +.IP \fBc\fR +Matches a sequence of +.IR width +count +characters (default 1); +the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters +(no terminating +.BR NUL +is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.IP \fB\&[\fR +Matches a nonempty sequence of characters from the specified set +of accepted characters; +the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters in the string, +plus a terminating +.BR NUL +character. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in +(or not in) +a particular set; +the set is defined by the characters between the open bracket +.BR [ +character +and a close bracket +.BR ] +character. +The set +.IR excludes +those characters +if the first character after the open bracket is a circumflex +.BR ^ . +To include a close bracket in the set, +make it the first character after the open bracket +or the circumflex; +any other position will end the set. +The hyphen character +.BR - +is also special; +when placed between two other characters, +it adds all intervening characters to the set. +To include a hyphen, +make it the last character before the final close bracket. +For instance, +.BR [^]0-9-] +means the set `everything except close bracket, zero through nine, +and hyphen'. +The string ends with the appearance of a character not in the +(or, with a circumflex, in) set +or when the field width runs out. +.IP \fBp\fR +Matches a pointer value (as printed by +.BR %p +in +.BR printf (3)); +the next pointer must be a pointer to +.IR void . +.IP \fBn\fR +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 +.IR int . +This is +.IR not +a conversion, although it can be suppressed with the +.BR * +flag. +.RE +.LP +For backwards compatibility, +other conversion characters (except +.BR \e0 ) +are taken as if they were +.BR %d +or, if uppercase, +.BR %ld , +and a `conversion' of +.BR %\e0 +causes an immediate return of +.BR EOF . +The +.BR F +and +.BR X +conversions will be changed in the future +to conform to the ANSI/C standard, +after which they will act like +.BR f +and +.BR x +respectively. +.LP +.SH RETURN VALUES +These +functions +return +the number of input items assigned, which can be fewer than provided +for, or even zero, in the event of a matching failure. +Zero +indicates that, while there was input available, +no conversions were assigned; +typically this is due to an invalid input character, +such as an alphabetic character for a +.BR %d +conversion. +.LP +The value +.BR EOF +is returned if an input failure occurs before any conversion such as an +end-of-file occurs. If an error or end-of-file occurs after conversion +has begun, +the number of conversions which were successfully completed is returned. +.SH SEE ALSO +.BR strtol (3), +.BR strtoul (3), +.BR strtod (3), +.BR getc (3), +.BR printf (3) +.SH STANDARDS +The functions +.BR fscanf , +.BR scanf , +and +.BR sscanf +conform to ANSI/C. +.SH HISTORY +The functions +.BR vscanf , +.BR vsscanf +and +.BR vfscanf +are new to this release. +.SH BUGS +The ORCA/C stdio implementation also provides a +.BR %b +format specifier, for Pascal-type strings. This is not currently implemented. +.LP +The current situation with +.BR %F +and +.BR %X +conversions is unfortunate. +.LP +All of the backwards compatibility formats will be removed in the future. +.LP +Numerical strings are truncated to 512 characters; for example, +.BR %f +and +.BR %d +are implicitly +.BR %512f +and +.BR %512d . diff --git a/usr.man/man3/setbuf.3 b/usr.man/man3/setbuf.3 new file mode 100644 index 0000000..088b8bf --- /dev/null +++ b/usr.man/man3/setbuf.3 @@ -0,0 +1,193 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setbuf.3 8.1 (Berkeley) 6/4/93 +.\" +.TH SETBUF 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR setbuf , +.BR setbuffer , +.BR setlinebuf , +.BR setvbuf +\- stream buffering operations +.SH SYNOPSIS +#include +.sp 1 +void \fBsetbuf\fR (FILE *\fIstream\fR, char *\fIbuf\fR); +.br +void \fBsetbuffer\fR (FILE *\fIstream\fR, char *\fIbuf\fR, size_t \fIsize\fR); +.sp 1 +int \fBsetlinebuf\fR (FILE *\fIstream\fR); +.sp 1 +int \fBsetvbuf\fR (FILE *\fIstream\fR, char *\fIbuf\fR, int \fImode\fR, size_t \fIsize\fR); +.SH DESCRIPTION +The three types of 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 +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +.LP +Normally all files are block buffered. +When the first I/O operation occurs on a file, +.BR malloc (3) +is called, +and an optimally-sized buffer is obtained. +If a stream refers to a terminal +(as +.IR stdout +normally does) it is line buffered. +The standard error stream +.IR stderr +is always unbuffered. +.LP +The +.BR setvbuf +function +may be used to alter the buffering behavior of a stream. +The +.I mode +parameter must be one of the following three macros: +.RS +.nf + +\fB_IONBF\fR unbuffered +\fB_IOLBF\fR line buffered +\fB_IOFBF\fR fully buffered +.fi +.RE +.LP +The +.I 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 +.I buf +argument should point to a buffer at least +.I size +bytes long; +this buffer will be used instead of the current buffer. +(If the +.I size +argument +is not zero but +.I buf +is +.BR NULL , +a buffer of the given size will be allocated immediately, +and released on close. +This is an extension to ANSI C; +portable code should use a size of 0 with any +.BR NULL +buffer.) +.LP +The +.BR setvbuf +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''. +Portable applications should call it only once on any given stream, +and before any I/O is performed. +.LP +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf . +Except for the lack of a return value, the +.BR setbuf +function is exactly equivalent to the call +.nf + + setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); + +.fi +The +.BR setbuffer +function +is the same, except that the size of the buffer is up to the caller, +rather than being determined by the default +.BR BUFSIZ . +The +.BR setlinebuf +function +is exactly equivalent to the call: +.nf + + setvbuf(stream, (char *)NULL, _IOLBF, 0); + +.fi +.SH RETURN VALUES +The +.BR setvbuf +function returns 0 on success, or +.BR EOF +if the request cannot be honored +(note that the stream is still functional in this case). +.LP +The +.BR setlinebuf +function returns what the equivalent +.BR setvbuf +would have returned. +.SH SEE ALSO +.BR fopen (3), +.BR fclose (3), +.BR fread (3), +.BR malloc (3), +.BR puts (3), +.BR printf (3) +.SH STANDARDS +The +.BR setbuf +and +.BR setvbuf +functions +conform to ANSI/C. +.SH BUGS +The +.BR setbuffer +and +.BR setlinebuf +functions are not portable to versions of BSD before 4.2BSD. +On 4.2BSD and 4.3BSD systems, +.BR setbuf +always uses a suboptimal buffer size and should be avoided. diff --git a/usr.man/man3/stdio.3 b/usr.man/man3/stdio.3 new file mode 100644 index 0000000..fbf79e2 --- /dev/null +++ b/usr.man/man3/stdio.3 @@ -0,0 +1,283 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 +.\" +.TH STDIO 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR stdio +\- standard input/output library functions +.SH SYNOPSIS +.br +#include +.br +FILE *stdin; +.br +FILE *stdout; +.br +FILE *stderr; +.SH DESCRIPTION +The standard I/O library provides a simple and efficient buffered stream +I/O interface. +Input and output is mapped into logical data streams +and the physical I/O +characteristics are concealed. The functions and macros are listed +below; more information is available from the individual man pages. +.LP +A stream is associated with an external file (which may be a physical +device) by +.IR 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 +.IR "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 +is used, the position indicator will be placed the end-of-file. +The position indicator is maintained by subsequent reads, writes +and positioning requests. All input occurs as if the characters +were read by successive calls to the +.BR fgetc (3) +function; all output takes place as if all characters were +read by successive calls to the +.BR fputc (3) +function. +.LP +A file is disassociated from a stream by +.IR closing +the file. +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 +.BR FILE +object is indeterminate after a file is closed (garbage). +.LP +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be repositioned +at the start). If the main function returns to its original caller, or +the +.BR exit (3) +function is called, all open files are closed (hence all output +streams are flushed) before program termination. Other methods +of program termination, such as +.BR abort (3) +do not bother about closing files properly. +.LP +This implementation makes a distinction between +.I text +and +.I binary +streams. For text streams, all carrige returns are mapped to linefeeds +during input, and all linefeeds are mapped to carrige returns on output. +No extra padding appears on any stream. +.LP +At program startup, three streams are predefined and need not be +opened explicitly: +.RS +.IR "standard input" +(for reading conventional input), +.br +.IR "standard output" +(for writing conventional output), and +.br +.IR "standard error" +(for writing diagnostic output). +.RE +These streams are abbreviated +.IR stdin , +.IR stdout , +and +.IR stderr . +Initially, the standard error stream +is unbuffered; the standard input and output streams are +fully buffered if and only if the streams do not refer to +an interactive or +.I terminal +device, as determined by the +.BR isatty (3) +function. +In fact, +.IR all +freshly-opened streams that refer to terminal devices +default to line buffering, and +pending output to such streams is written automatically +whenever an such an input stream is read. +Note that this applies only to +.IR "true reads" ; +if the read request can be satisfied by existing buffered data, +no automatic flush will occur. +In these cases, +or when a large amount of computation is done after printing +part of a line on an output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output +will appear. +Alternatively, these defaults may be modified via the +.BR setvbuf (3) +function. +.LP +The +.BR stdio +library is a part of the library +.BR libc +and routines are automatically loaded as needed by the linker. +The +.BR SYNOPSIS +sections of the following manual pages indicate which include files +are to be used, what the compiler declaration for the function +looks like and which external variables are of interest. +.LP +The following are defined as macros; +these names may not be re-used +without first removing their current definitions with +.BR #undef : +.BR BUFSIZ , +.BR EOF , +.BR FILENAME_MAX , +.BR FOPEN_MAX , +.BR L_cuserid , +.BR L_ctermid , +.BR L_tmpnam, +.BR NULL , +.BR SEEK_END , +.BR SEEK_SET , +.BR SEE_CUR , +.BR TMP_MAX , +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno , +.BR freopen , +.BR fwopen , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR stderr , +.BR stdin , +.BR stdout . +Function versions of the macro functions +.BR feof , +.BR ferror , +.BR clearerr , +.BR fileno , +.BR getc , +.BR getchar , +.BR putc , +and +.BR putchar +exist and will be used if the macros +definitions are explicitly removed. +.SH SEE ALSO +.BR open (2), +.BR close (2), +.BR read (2), +.BR write (2) +.SH BUGS +The standard buffered functions do not interact well with certain other +library and system functions, especially +.BR fork (2), +.BR fork2 (2), +.BR vfork (2), +and +.BR abort (3). +.SH STANDARDS +The +.BR stdio +library conforms to ANSI/C. +.SH LIST OF FUNCTIONS +.nf +Function Description +-------- ----------- +clearerr check and reset stream status +fclose close a stream +fdopen stream open functions +feof check and reset stream status +ferror check and reset stream status +fflush flush a stream +fgetc get next character or word from input stream +fgetln get a line from a stream +fgetpos reposition a stream +fgets get a line from a stream +fileno check and reset stream status +fopen stream open functions +fprintf formatted output conversion +fpurge flush a stream +fputc output a character or word to a stream +fputs output a line to a stream +fread binary stream input/output +freopen stream open functions +fropen open a stream +fscanf input format conversion +fseek reposition a stream +fsetpos reposition a stream +ftell reposition a stream +funopen open a stream +fwopen open a stream +fwrite binary stream input/output +getc get next character or word from input stream +getchar get next character or word from input stream +gets get a line from a stream +getw get next character or word from input stream +mkstemp create unique temporary file +mktemp create unique temporary file +perror system error messages +printf formatted output conversion +putc output a character or word to a stream +putchar output a character or word to a stream +puts output a line to a stream +putw output a character or word to a stream +remove remove directory entry +rewind reposition a stream +scanf input format conversion +setbuf stream buffering operations +setbuffer stream buffering operations +setlinebuf stream buffering operations +setvbuf stream buffering operations +snprintf formatted output conversion +sprintf formatted output conversion +sscanf input format conversion +strerror system error messages +sys_errlist system error messages +sys_nerr system error messages +tempnam temporary file routines +tmpfile temporary file routines +tmpnam temporary file routines +ungetc un-get character from input stream +vfprintf formatted output conversion +vfscanf input format conversion +vprintf formatted output conversion +vscanf input format conversion +vsnprintf formatted output conversion +vsprintf formatted output conversion +vsscanf input format conversion +.fi diff --git a/usr.man/man3/ungetc.3 b/usr.man/man3/ungetc.3 new file mode 100644 index 0000000..ee9635d --- /dev/null +++ b/usr.man/man3/ungetc.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 +.\" +.TH UNGETC 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR ungetc +\- un-get character from input stream +.SH SYNOPSIS +#include +.sp 1 +int \fBungetc\fR (int \fIc\fR, FILE *\fIstream\fR); +.SH DESCRIPTION +The +.BR ungetc +function pushes the character +.I c +(converted to an unsigned char) +back onto the input stream pointed to by +.IR stream . +The pushed-backed characters will be returned by subsequent reads on the +stream (in reverse order). +A successful intervening call, using the same stream, to one of the file +positioning functions +.BR fseek (3), +.BR fsetpos (3), +or +.BR rewind (3) +will discard the pushed back characters. +.LP +One character of push-back is guaranteed, +but as long as there is +sufficient memory, an effectively infinite amount of pushback is allowed. +.LP +If a character is successfully pushed-back, +the end-of-file indicator for the stream is cleared. +.SH RETURN VALUES +The +.BR ungetc +function +returns +the character pushed-back after the conversion, or +.BR EOF +if the operation fails. +If the value of the argument +.I c +character equals +.BR EOF , +the operation will fail and the stream will remain unchanged. +.SH SEE ALSO +.BR getc (3), +.BR fseek (3), +.BR setvbuf (3) +.SH STANDARDS +The +.BR ungetc +function conforms to ANSI/C.