1.\" $OpenBSD: fgets.3,v 1.32 2014/03/23 23:15:58 tedu 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: March 23 2014 $ 35.Dt FGETS 3 36.Os 37.Sh NAME 38.Nm fgets 39.Nd get a line from a stream 40.Sh SYNOPSIS 41.In stdio.h 42.Ft char * 43.Fn fgets "char *str" "int size" "FILE *stream" 44.Sh DESCRIPTION 45The 46.Fn fgets 47function reads at most 48.Ar size Ns \-1 49characters from the given 50.Fa stream 51and stores them in the string 52.Fa str . 53Reading stops when a newline character is found, 54at end-of-file, or on error. 55The newline, if any, is retained. 56The string will be NUL-terminated if 57.Fn fgets 58succeeds; otherwise the contents of 59.Fa str 60are undefined. 61.Sh RETURN VALUES 62Upon successful completion, 63.Fn fgets 64returns a pointer to the string. 65If end-of-file or an error occurs before any characters are read, 66it returns 67.Dv NULL . 68The 69.Fn fgets 70function does not distinguish between end-of-file and error, 71and callers must use 72.Xr feof 3 73and 74.Xr ferror 3 75to determine which occurred. 76Whether 77.Fn fgets 78can possibly fail with a 79.Ar size 80argument of 1 is implementation-dependent. 81On 82.Ox , 83.Fn fgets 84will never return 85.Dv NULL 86when 87.Ar size 88is 1. 89.Sh ERRORS 90.Bl -tag -width Er 91.It Bq Er EBADF 92The given 93.Fa stream 94is not a readable stream. 95.It Bq Er EINVAL 96The given 97.Fa size 98is less than or equal to 0. 99.El 100.Pp 101The function 102.Fn fgets 103may also fail and set 104.Va errno 105for any of the errors specified for the routines 106.Xr fflush 3 , 107.Xr fstat 2 , 108.Xr read 2 , 109or 110.Xr malloc 3 . 111.Sh SEE ALSO 112.Xr feof 3 , 113.Xr ferror 3 , 114.Xr fgetln 3 115.Sh STANDARDS 116The function 117.Fn fgets 118conforms to 119.St -ansiC . 120.Sh HISTORY 121The function 122.Fn fgets 123first appeared in 124.At v7 . 125.Sh CAVEATS 126The following bit of code illustrates a case where the programmer assumes a 127string is too long if it does not contain a newline: 128.Bd -literal -offset indent 129char buf[1024], *p; 130 131while (fgets(buf, sizeof(buf), fp) != NULL) { 132 if ((p = strchr(buf, '\en')) == NULL) { 133 fprintf(stderr, "input line too long.\en"); 134 exit(1); 135 } 136 *p = '\e0'; 137 printf("%s\en", buf); 138} 139.Ed 140.Pp 141While the error would be true if a line \*(Gt 1023 characters were read, 142it would be false in two other cases: 143.Bl -enum -offset indent 144.It 145If the last line in a file does not contain a newline, the string returned by 146.Fn fgets 147will not contain a newline either. 148Thus 149.Fn strchr 150will return 151.Dv NULL 152and the program will terminate, even if the line was valid. 153.It 154All C string functions, including 155.Fn strchr , 156correctly assume the end of the string is represented by a NUL 157.Pq Sq \e0 158character. 159If the first character of a line returned by 160.Fn fgets 161were NUL, 162.Fn strchr 163would immediately return without considering the rest of the returned text 164which may indeed include a newline. 165.El 166.Pp 167Consider using 168.Xr fgetln 3 169instead when dealing with untrusted input. 170.Pp 171It is erroneous to assume that 172.Fn fgets 173never returns an empty string when successful. 174If a line starts with the NUL character, fgets will store the NUL and 175continue reading until it encounters a newline or end-of-file. 176This will result in an empty string being returned. 177The following bit of code illustrates a case where the programmer assumes 178the string cannot be zero length. 179.Bd -literal -offset indent 180char buf[1024]; 181 182if (fgets(buf, sizeof(buf), fp) != NULL) { 183 /* WRONG */ 184 if (buf[strlen(buf) - 1] == '\en') 185 buf[strlen(buf) - 1] = '\e0'; 186} 187.Ed 188.Pp 189If 190.Fn strlen 191returns 0, the index into the buffer becomes \-1. 192One way to concisely and correctly trim a newline is shown below. 193.Bd -literal -offset indent 194char buf[1024]; 195 196if (fgets(buf, sizeof(buf), fp) != NULL) 197 buf[strcspn(buf, "\en")] = '\e0'; 198.Ed 199