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