1.\" Copyright (c) 1990, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Chris Torek. 6.\" %sccs.include.redist.man% 7.\" 8.\" @(#)fgets.3 6.8 (Berkeley) 04/19/91 9.\" 10.Dd 11.Dt FGETS 3 12.Os 13.Sh NAME 14.Nm fgets , 15.Nm gets 16.Nd get a line from a stream 17.Sh SYNOPSIS 18.Fd #include <stdio.h> 19.Ft char * 20.Fn fgets "char *str" "size_t size" "FILE *stream" 21.Ft char * 22.Fn gets "char *str" 23.Sh DESCRIPTION 24The 25.Fn fgets 26function 27reads at most one less than the number of characters specified by 28.Xr size 29from the given 30.Fa stream 31and stores them in the string 32.Fa str . 33Reading stops when a newline character is found, 34at end-of-file or error. 35The newline, if any, is retained. 36In any case a 37.Ql \e0 38character is appended to end the string. 39.Pp 40The 41.Fn gets 42function 43is equivalent to 44.Fn fgets 45with an infinite 46.Xr size 47and a 48.Fa stream 49of 50.Em stdin , 51except that the newline character (if any) is not stored in the string. 52It is the caller's responsibility to ensure that the input line, 53if any, is sufficiently short to fit in the string. 54.Sh RETURN VALUES 55.Pp 56Upon successful completion, 57.Fn fgets 58and 59.Fn gets 60return 61a pointer to the string. 62If end-of-file or an error occurs before any characters are read, 63they return 64.Dv NULL. 65The 66.Fn fgets 67and 68functions 69.Fn gets 70do not distinguish between end-of-file and error, and callers must use 71.Xr feof 3 72and 73.Xr ferror 3 74to determine which occurred. 75.Sh ERRORS 76.Bl -tag -width [EBADF] 77.It Bq Er EBADF 78The given 79.Fa stream 80is not a readable stream. 81.El 82.Pp 83The function 84.Fn fgets 85may also fail and set 86.Va errno 87for any of the errors specified for the routines 88.Xr fflush 3 , 89.Xr fstat 2 , 90.Xr read 2 , 91or 92.Xr malloc 3 . 93.Pp 94The function 95.Fn gets 96may also fail and set 97.Va errno 98for any of the errors specified for the routine 99.Xr getchar 3 . 100.Sh SEE ALSO 101.Xr feof 3 , 102.Xr ferror 3 , 103.Xr fgetline 3 104.Sh STANDARDS 105The functions 106.Fn fgets 107and 108.Fn gets 109conform to 110.St -ansiC . 111.Sh BUGS 112Since it is usually impossible to ensure that the next input line 113is less than some arbitrary length, and because overflowing the 114input buffer is almost invariably a security violation, programs 115should 116.Em NEVER 117use 118.Fn gets . 119The 120.Fn gets 121function 122exists purely to conform to 123.St -ansiC . 124