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