1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)fgetln.3 8.3 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt FGETLN 3 10.Os 11.Sh NAME 12.Nm fgetln 13.Nd get a line from a stream 14.Sh SYNOPSIS 15.Fd #include <stdio.h> 16.Ft char * 17.Fn fgetln "FILE *stream" "size_t *len" 18.Sh DESCRIPTION 19The 20.Fn fgetln 21function 22returns a pointer to the next line from the stream referenced by 23.Fa stream . 24This line is 25.Em not 26a C string as it does not end with a terminating 27.Dv NUL 28character. 29The length of the line, including the final newline, 30is stored in the memory location to which 31.Fa len 32points. 33(Note, however, that if the line is the last 34in a file that does not end in a newline, 35the returned text will not contain a newline.) 36.Sh RETURN VALUES 37Upon successful completion a pointer is returned; 38this pointer becomes invalid after the next 39.Tn I/O 40operation on 41.Fa stream 42(whether successful or not) 43or as soon as the stream is closed. 44Otherwise, 45.Dv NULL 46is returned. 47The 48.Fn fgetln 49function 50does not distinguish between end-of-file and error; the routines 51.Xr feof 3 52and 53.Xr ferror 3 54must be used 55to determine which occurred. 56If an error occurs, the global variable 57.Va errno 58is set to indicate the error. 59The end-of-file condition is remembered, even on a terminal, and all 60subsequent attempts to read will return 61.Dv NULL 62until the condition is 63cleared with 64.Xr clearerr 3 . 65.Pp 66The text to which the returned pointer points may be modified, 67provided that no changes are made beyond the returned size. 68These changes are lost as soon as the pointer becomes invalid. 69.Sh ERRORS 70.Bl -tag -width [EBADF] 71.It Bq Er EBADF 72The argument 73.Fa stream 74is not a stream open for reading. 75.El 76.Pp 77The 78.Fn fgetln 79function 80may also fail and set 81.Va errno 82for any of the errors specified for the routines 83.Xr fflush 3 , 84.Xr malloc 3 , 85.Xr read 2 , 86.Xr stat 2 , 87or 88.Xr realloc 3 . 89.Sh SEE ALSO 90.Xr ferror 3 , 91.Xr fgets 3 , 92.Xr fopen 3 , 93.Xr putc 3 94.Sh HISTORY 95The 96.Fn fgetln 97function first appeared in 4.4BSD. 98