1.\" $OpenBSD: fgets.3,v 1.29 2009/06/02 22:28:18 ray Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: June 2 2009 $ 35.Dt FGETS 3 36.Os 37.Sh NAME 38.Nm fgets , 39.Nm gets 40.Nd get a line from a stream 41.Sh SYNOPSIS 42.Fd #include <stdio.h> 43.Ft char * 44.Fn fgets "char *str" "int size" "FILE *stream" 45.Ft char * 46.Fn gets "char *str" 47.Sh DESCRIPTION 48The 49.Fn fgets 50function reads at most 51.Ar size Ns \-1 52characters from the given 53.Fa stream 54and stores them in the string 55.Fa str . 56Reading stops when a newline character is found, 57at end-of-file, or on error. 58The newline, if any, is retained. 59The string will be NUL-terminated if 60.Fn fgets 61succeeds; otherwise the contents of 62.Fa str 63are undefined. 64.Pp 65The 66.Fn gets 67function is equivalent to 68.Fn fgets 69with an infinite 70.Ar size 71and a 72.Fa stream 73of 74.Em stdin , 75except that the newline character (if any) is not stored in the string. 76It is the caller's responsibility to ensure that the input line, 77if any, is sufficiently short to fit in the string. 78.Sh RETURN VALUES 79Upon successful completion, 80.Fn fgets 81and 82.Fn gets 83return 84a pointer to the string. 85If end-of-file or an error occurs before any characters are read, 86they return 87.Dv NULL . 88The 89.Fn fgets 90and 91.Fn gets 92functions 93do not distinguish between end-of-file and error, and callers must use 94.Xr feof 3 95and 96.Xr ferror 3 97to determine which occurred. 98Whether 99.Fn fgets 100can possibly fail with a 101.Ar size 102argument of 1 is implementation-dependent. 103On 104.Ox , 105.Fn fgets 106will never return 107.Dv NULL 108when 109.Ar size 110is 1. 111.Sh ERRORS 112.Bl -tag -width Er 113.It Bq Er EBADF 114The given 115.Fa stream 116is not a readable stream. 117.It Bq Er EINVAL 118The given 119.Fa size 120is less than or equal to 0. 121.El 122.Pp 123The function 124.Fn fgets 125may also fail and set 126.Va errno 127for any of the errors specified for the routines 128.Xr fflush 3 , 129.Xr fstat 2 , 130.Xr read 2 , 131or 132.Xr malloc 3 . 133.Pp 134The function 135.Fn gets 136may also fail and set 137.Va errno 138for any of the errors specified for the routine 139.Xr getchar 3 . 140.Sh SEE ALSO 141.Xr feof 3 , 142.Xr ferror 3 , 143.Xr fgetln 3 144.Sh STANDARDS 145The functions 146.Fn fgets 147and 148.Fn gets 149conform to 150.St -ansiC . 151.Sh CAVEATS 152The following bit of code illustrates a case where the programmer assumes a 153string is too long if it does not contain a newline: 154.Bd -literal -offset indent 155char buf[1024], *p; 156 157while (fgets(buf, sizeof(buf), fp) != NULL) { 158 if ((p = strchr(buf, '\en')) == NULL) { 159 fprintf(stderr, "input line too long.\en"); 160 exit(1); 161 } 162 *p = '\e0'; 163 printf("%s\en", buf); 164} 165.Ed 166.Pp 167While the error would be true if a line \*(Gt 1023 characters were read, 168it would be false in two other cases: 169.Bl -enum -offset indent 170.It 171If the last line in a file does not contain a newline, the string returned by 172.Fn fgets 173will not contain a newline either. 174Thus 175.Fn strchr 176will return 177.Dv NULL 178and the program will terminate, even if the line was valid. 179.It 180All C string functions, including 181.Fn strchr , 182correctly assume the end of the string is represented by a NUL 183.Pq Sq \e0 184character. 185If the first character of a line returned by 186.Fn fgets 187were NUL, 188.Fn strchr 189would immediately return without considering the rest of the returned text 190which may indeed include a newline. 191.El 192.Pp 193Consider using 194.Xr fgetln 3 195instead when dealing with untrusted input. 196.Pp 197It is erroneous to assume that 198.Fn fgets 199never returns an empty string when successful. 200If a line starts with the NUL character, fgets will store the NUL and 201continue reading until it encounters a newline or end-of-file. 202This will result in an empty string being returned. 203The following bit of code illustrates a case where the programmer assumes 204the string cannot be zero length. 205.Bd -literal -offset indent 206char buf[1024]; 207 208if (fgets(buf, sizeof(buf), fp) != NULL) { 209 /* WRONG */ 210 if (buf[strlen(buf) - 1] == '\en') 211 buf[strlen(buf) - 1] = '\e0'; 212} 213.Ed 214.Pp 215If 216.Fn strlen 217returns 0, the index into the buffer becomes \-1. 218One way to concisely and correctly trim a newline is shown below. 219.Bd -literal -offset indent 220char buf[1024]; 221 222if (fgets(buf, sizeof(buf), fp) != NULL) 223 buf[strcspn(buf, "\en")] = '\e0'; 224.Ed 225.Sh BUGS 226Since it is usually impossible to ensure that the next input line 227is less than some arbitrary length, and because overflowing the 228input buffer is almost invariably a security violation, programs 229should 230.Em NEVER 231use 232.Fn gets . 233The 234.Fn gets 235function exists purely to conform to 236.St -ansiC . 237