diff --git a/usr.man/man3/fgetln.3 b/usr.man/man3/fgetln.3 new file mode 100644 index 0000000..d94e049 --- /dev/null +++ b/usr.man/man3/fgetln.3 @@ -0,0 +1,119 @@ +.\" 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. +.\" +.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94 +.\" +.TH FGETLN 3 "19 April 1997" GNO "Library Routines" +.SH NAME +.BR fgetln +\- get a line from a stream +.SH SYNOPSIS +#include +.sp 1 +char *\fBfgetln\fR (FILE *\fIstream\fR, size_t *\fIlen\fR); +.SH DESCRIPTION +The +.BR fgetln +function +returns a pointer to the next line from the stream referenced by +.IR stream +This line is +.IR not +a C string as it does not end with a terminating +.BR NUL +character. +The length of the line, including the final newline, +is stored in the memory location to which +.I len +points. +(Note, however, that if the line is the last +in a file that does not end in a newline, +the returned text will not contain a newline.) +.SH RETURN VALUES +Upon successful completion a pointer is returned; +this pointer becomes invalid after the next I/O operation on +.I stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.BR NULL +is returned. +The +.BR fgetln +function +does not distinguish between end-of-file and error; the routines +.BR feof (3) +and +.BR ferror (3) +must be used +to determine which occurred. +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 NULL +until the condition is +cleared with +.BR clearerr (3). +.LP +The text to which the returned pointer points may be modified, +provided that no changes are made beyond the returned size. +These changes are lost as soon as the pointer becomes invalid. +.SH ERRORS +.RS +.IP \fBEBADF\fR +The argument +.I stream +is not a stream open for reading. +.RE +.LP +The +.BR fgetln +function +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR fflush (3), +.BR malloc (3), +.BR read (2), +.BR stat (2), +or +.BR realloc (3). +.SH SEE ALSO +.BR ferror (3), +.BR fgets (3), +.BR fopen (3), +.BR putc (3) +.SH HISTORY +The +.BR fgetln +function first appeared in 4.4BSD. diff --git a/usr.man/man3/fopen.3 b/usr.man/man3/fopen.3 new file mode 100644 index 0000000..d81a982 --- /dev/null +++ b/usr.man/man3/fopen.3 @@ -0,0 +1,250 @@ +.\" 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. +.\" +.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 +.\" +.TH FOPEN 3 "29 April 1997" GNO "Library Routines" +.SH NAME +.BR fopen , +.BR fdopen , +.BR freopen +\- stream open functions +.SH SYNOPSIS +#include +.sp 1 +FILE *\fBfopen\fR(const char *\fIpath\fR, const char *\fImode\fR); +.sp 1 +FILE *\fBfdopen\fR(int \fIfildes\fR, const char *\fImode\fR); +.sp 1 +FILE *\fBfreopen\fR(const char *\fIpath\fR, const char *\fImode\fR, FILE *\fIstream\fR); +.SH DESCRIPTION +The +.BR fopen +function +opens the file whose name is the string pointed to by +.I path +and associates a stream with it. +.LP +The argument +.I mode +points to a string beginning with one of the following +sequences (Additional characters may follow these sequences.): +.RS +.IP \fBr\fR +Open text file for reading. +The stream is positioned at the beginning of the file. +.IP \fBr+\fR +Open for reading and writing. +The stream is positioned at the beginning of the file. +.IP \fBw\fR +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. +.IP \fBw+\fR +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of the file. +.IP \fBa\fR +Open for writing. +The file is created if it does not exist. +The stream is positioned at the end of the file. +.IP \fBa+\fR +Open for reading and writing. +The file is created if it does not exist. +The stream is positioned at the end of the file. +.RE +.LP +The +.I mode +string can also include the letter ``b'' either as a third character or +as a character between the characters in any of the two-character strings +described above. +If the ``b'' is +.I not +specified, then the file is assumed to contain text. +On input, carrige returns (``\\r'') will be translated into +line feeds (``\\n''). +The reverse translation will occur on output. +If the ``b'' +.I is +specified, no such translation will occur. +.LP +Any created files will have mode +.BR S_IRUSR +\&| +.BR S_IWUSR +\&| +.BR S_IRGRP +\&| +.BR S_IWGRP +\&| +.BR S_IROTH +\&| +.BR S_IWOTH " (0666)," +as modified by the process' +umask value (see +.BR umask (2)). +.LP +The +.BR fdopen +function associates a stream with the existing file descriptor, +.IR fildes +The +.I mode +of the stream must be compatible with the mode of the file descriptor. +See the section on BUGS. +.LP +The +.BR freopen +function +opens the file whose name is the string pointed to by +.I path +and associates the stream pointed to by +.I stream +with it. +The original stream (if it exists) is closed. +The +.I mode +argument is used just as in the +.BR fopen +function. +The primary use of the +.BR freopen +function +is to change the file associated with a +standard text stream +.IR ( stderr , +.IR stdin , +or +.IR stdout ). +.SH RETURN VALUES +Upon successful completion +.BR fopen , +.BR fdopen +and +.BR freopen +return a FILE +pointer. +Otherwise, +.BR NULL +is returned and the global variable +.IR errno +is set to indicate the error. +.SH ERRORS +.RS +.IP \fBEINVAL\fR +The +.I mode +provided to +.BR fopen , +.BR fdopen , +or +.BR freopen +was invalid. +.RE +.LP +The +.BR fopen , +.BR fdopen +and +.BR freopen +functions +may also fail and set +.IR errno +for any of the errors specified for the routine +.BR malloc (3). +.LP +The +.BR fopen +function +may also fail and set +.IR errno +for any of the errors specified for the routine +.BR open (2). +.LP +The +.BR fdopen +function +may also fail and set +.IR errno +for any of the errors specified for the routine +.BR fcntl (2) +or +.BR stat (2). +.LP +The +.BR freopen +function +may also fail and set +.IR errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3) +and +.BR fflush (3). +.SH BUGS +If +.BR fdopen +is passed a file descriptor in use by another stdio stream (such +as that available from the +.BR fileno +macro), +the result is currently undefined. +If you need to do such an operation, you should +.BR dup (2) +the result of the +.BR fileno +macro before passing it to +.BR fdopen . +.LP +Access bits are not currently checked for any file descriptor passed to +.BR fdopen +which is a character-special file. +.SH SEE ALSO +.BR open (2), +.BR stat (2), +.BR fclose (3), +.BR fseek (3), +.BR funopen (3) +.SH STANDARDS +The +.BR fopen +and +.BR freopen +functions +conform to ANSI/C. +The +.BR fdopen +function +conforms to POSIX 1003.1 (1988).