1.\" $OpenBSD: fgetln.3,v 1.19 2017/12/01 11:18:40 schwarze Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: December 1 2017 $ 31.Dt FGETLN 3 32.Os 33.Sh NAME 34.Nm fgetln 35.Nd get a line from a stream 36.Sh SYNOPSIS 37.In stdio.h 38.Ft char * 39.Fn fgetln "FILE *stream" "size_t *len" 40.Sh DESCRIPTION 41Using this function is error-prone in multiple ways; 42consider using the safer and more portable function 43.Xr getline 3 44instead. 45.Pp 46The 47.Fn fgetln 48function returns a pointer to the next line from the stream referenced by 49.Fa stream . 50This line is 51.Em not 52a C string as it does not end with a terminating NUL character. 53The length of the line, including the final newline, 54is stored in the memory location to which 55.Fa len 56points and is guaranteed to be greater than 0 upon successful completion. 57(Note, however, that if the last line in the stream does not end in a newline, 58the returned text will not contain a newline.) 59.Sh RETURN VALUES 60Upon successful completion a pointer is returned; 61this pointer becomes invalid after the next I/O operation on 62.Fa stream 63(whether successful or not) 64or as soon as the stream is closed. 65Otherwise, 66.Dv NULL 67is returned. 68.Pp 69The 70.Fn fgetln 71function does not distinguish between end-of-file and error; the routines 72.Xr feof 3 73and 74.Xr ferror 3 75must be used 76to determine which occurred. 77If an error occurs, the global variable 78.Va errno 79is set to indicate the error. 80The end-of-file condition is remembered, even on a terminal, and all 81subsequent attempts to read will return 82.Dv NULL 83until the condition is 84cleared with 85.Xr clearerr 3 . 86.Pp 87The text to which the returned pointer points may be modified, 88provided that no changes are made beyond the returned size. 89These changes are lost as soon as the pointer becomes invalid. 90.Sh ERRORS 91.Bl -tag -width [EBADF] 92.It Bq Er EBADF 93The argument 94.Fa stream 95is not a stream open for reading. 96.El 97.Pp 98The 99.Fn fgetln 100function may also fail and set 101.Va errno 102for any of the errors specified for the routines 103.Xr fflush 3 , 104.Xr malloc 3 , 105.Xr read 2 , 106.Xr stat 2 , 107or 108.Xr realloc 3 . 109.Sh SEE ALSO 110.Xr ferror 3 , 111.Xr fgetc 3 , 112.Xr fgets 3 , 113.Xr fgetwln 3 , 114.Xr fopen 3 , 115.Xr fparseln 3 , 116.Xr getline 3 117.Sh HISTORY 118The 119.Fn fgetln 120function first appeared in 121.Bx 4.4 . 122.Sh CAVEATS 123Since the returned buffer is not a C string (it is not NUL terminated), a 124common practice is to replace the newline character with 125.Sq \e0 . 126However, if the last line in a file does not contain a newline, 127the returned text won't contain a newline either. 128The following code demonstrates how to deal with this problem by allocating a 129temporary buffer: 130.Bd -literal 131 char *buf, *lbuf; 132 size_t len; 133 134 lbuf = NULL; 135 while ((buf = fgetln(fp, &len))) { 136 if (buf[len - 1] == '\en') 137 buf[len - 1] = '\e0'; 138 else { 139 /* EOF without EOL, copy and add the NUL */ 140 if ((lbuf = malloc(len + 1)) == NULL) 141 err(1, NULL); 142 memcpy(lbuf, buf, len); 143 lbuf[len] = '\e0'; 144 buf = lbuf; 145 } 146 printf("%s\en", buf); 147 } 148 free(lbuf); 149 if (ferror(fp)) 150 err(1, "fgetln"); 151.Ed 152