162885Sbostic.\" Copyright (c) 1990, 1991, 1993 262885Sbostic.\" The Regents of the University of California. All rights reserved. 347005Sbostic.\" 447005Sbostic.\" %sccs.include.redist.man% 547005Sbostic.\" 6*66941Sbostic.\" @(#)fgetln.3 8.3 (Berkeley) 04/19/94 747005Sbostic.\" 848352Scael.Dd 965327Sbostic.Dt FGETLN 3 1048352Scael.Os 1148352Scael.Sh NAME 1265327Sbostic.Nm fgetln 1348352Scael.Nd get a line from a stream 1448352Scael.Sh SYNOPSIS 1548352Scael.Fd #include <stdio.h> 1648352Scael.Ft char * 1765327Sbostic.Fn fgetln "FILE *stream" "size_t *len" 1848352Scael.Sh DESCRIPTION 1948352ScaelThe 2065327Sbostic.Fn fgetln 2148352Scaelfunction 2248352Scaelreturns a pointer to the next line from the stream referenced by 2348352Scael.Fa stream . 2458421StorekThis line is 2558421Storek.Em not 2658421Storeka C string as it does not end with a terminating 2758421Storek.Dv NUL 2858421Storekcharacter. 2958421StorekThe length of the line, including the final newline, 3058421Storekis stored in the memory location to which 3148352Scael.Fa len 3258421Storekpoints. 3358421Storek(Note, however, that if the line is the last 3458421Storekin a file that does not end in a newline, 3558421Storekthe returned text will not contain a newline.) 3648352Scael.Sh RETURN VALUES 3747005SbosticUpon successful completion a pointer is returned; 3848352Scaelthis pointer becomes invalid after the next 3948352Scael.Tn I/O 4048352Scaeloperation on 4148352Scael.Fa stream 4247005Sbostic(whether successful or not) 4347005Sbosticor as soon as the stream is closed. 4448352ScaelOtherwise, 4548352Scael.Dv NULL 4648352Scaelis returned. 4748352ScaelThe 4865327Sbostic.Fn fgetln 4948352Scaelfunction 5048352Scaeldoes not distinguish between end-of-file and error; the routines 5148352Scael.Xr feof 3 5247005Sbosticand 5348352Scael.Xr ferror 3 5448352Scaelmust be used 5547005Sbosticto determine which occurred. 56*66941SbosticIf an error occurs, the global variable 5748352Scael.Va errno 5847005Sbosticis set to indicate the error. 5947005SbosticThe end-of-file condition is remembered, even on a terminal, and all 6048352Scaelsubsequent attempts to read will return 6148352Scael.Dv NULL 6248352Scaeluntil the condition is 6347005Sbosticcleared with 6448352Scael.Xr clearerr 3 . 6548352Scael.Pp 6647005SbosticThe text to which the returned pointer points may be modified, 6758421Storekprovided that no changes are made beyond the returned size. 6847005SbosticThese changes are lost as soon as the pointer becomes invalid. 6948352Scael.Sh ERRORS 7048352Scael.Bl -tag -width [EBADF] 7148352Scael.It Bq Er EBADF 7248352ScaelThe argument 7348352Scael.Fa stream 7447005Sbosticis not a stream open for reading. 7548352Scael.El 7648352Scael.Pp 7748352ScaelThe 7865327Sbostic.Fn fgetln 7948352Scaelfunction 8047005Sbosticmay also fail and set 8148352Scael.Va errno 8247005Sbosticfor any of the errors specified for the routines 8348352Scael.Xr fflush 3 , 8448352Scael.Xr malloc 3 , 8548352Scael.Xr read 2 , 8648352Scael.Xr stat 2 , 8747005Sbosticor 8848352Scael.Xr realloc 3 . 8948352Scael.Sh SEE ALSO 9048352Scael.Xr ferror 3 , 9148352Scael.Xr fgets 3 , 9248352Scael.Xr fopen 3 , 9348352Scael.Xr putc 3 9448352Scael.Sh HISTORY 9548352ScaelThe 9665327Sbostic.Fn fgetln 9762884Sbosticfunction first appeared in 4.4BSD. 98