diff options
Diffstat (limited to 'lib/libc/stdio/fgetln.3')
| -rw-r--r-- | lib/libc/stdio/fgetln.3 | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/lib/libc/stdio/fgetln.3 b/lib/libc/stdio/fgetln.3 new file mode 100644 index 000000000000..09fd014cde00 --- /dev/null +++ b/lib/libc/stdio/fgetln.3 @@ -0,0 +1,155 @@ +.\" 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. 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. +.\" +.Dd June 11, 2020 +.Dt FGETLN 3 +.Os +.Sh NAME +.Nm fgetln +.Nd get a line from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn fgetln "FILE *stream" "size_t *len" +.Sh DESCRIPTION +The +.Fn fgetln +function +returns a pointer to the next line from the stream referenced by +.Fa stream . +This line is +.Em not +a C string as it does not end with a terminating +.Dv NUL +character. +The length of the line, including the final newline, +is stored in the memory location to which +.Fa 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 +.Tn I/O +operation on +.Fa stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.Dv NULL +is returned. +The +.Fn fgetln +function +does not distinguish between end-of-file and error; the routines +.Xr feof 3 +and +.Xr ferror 3 +must be used +to determine which occurred. +If an error occurs, the global variable +.Va 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 +.Dv NULL +until the condition is +cleared with +.Xr clearerr 3 . +.Pp +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 +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa stream +is not a stream open for reading. +.It Bq Er ENOMEM +The internal line buffer could not be expanded due to lack of available memory, +or because it would need to expand beyond INT_MAX in size. +.El +.Pp +The +.Fn fgetln +function +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fflush 3 , +.Xr malloc 3 , +.Xr read 2 , +.Xr stat 2 , +or +.Xr realloc 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgets 3 , +.Xr fgetwln 3 , +.Xr fopen 3 , +.Xr getline 3 , +.Xr putc 3 +.Sh HISTORY +The +.Fn fgetln +function first appeared in +.Bx 4.4 . +.Sh CAVEATS +Since the returned buffer is not a C string (it is not NUL terminated), a +common practice is to replace the newline character with +.Sq \e0 . +However, if the last line in a file does not contain a newline, +the returned text won't contain a newline either. +The following code demonstrates how to deal with this problem by allocating a +temporary buffer: +.Bd -literal + char *buf, *lbuf; + size_t len; + + lbuf = NULL; + while ((buf = fgetln(fp, &len)) != NULL) { + if (buf[len - 1] == '\en') + buf[len - 1] = '\e0'; + else { + /* EOF without EOL, copy and add the NUL */ + if ((lbuf = malloc(len + 1)) == NULL) + err(1, NULL); + memcpy(lbuf, buf, len); + lbuf[len] = '\e0'; + buf = lbuf; + } + printf("%s\en", buf); + } + free(lbuf); + if (ferror(fp)) + err(1, "fgetln"); +.Ed |