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.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd April 3, 2018 36.Dt FGETS 3 37.Os 38.Sh NAME 39.Nm fgets , 40.Nm gets , 41.Nm gets_s 42.Nd get a line from a stream 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdio.h 47.Ft char * 48.Fn fgets "char * restrict str" "int size" "FILE * restrict stream" 49.Ft char * 50.Fn gets_s "char *str" "rsize_t size" 51.Ft char * 52.Fn gets "char *str" 53.Sh DESCRIPTION 54The 55.Fn fgets 56function 57reads at most one less than the number of characters specified by 58.Fa size 59from the given 60.Fa stream 61and stores them in the string 62.Fa str . 63Reading stops when a newline character is found, 64at end-of-file or error. 65The newline, if any, is retained. 66If any characters are read and there is no error, a 67.Ql \e0 68character is appended to end the string. 69.Pp 70The 71.Fn gets_s 72function 73is equivalent to 74.Fn fgets 75with a 76.Fa stream 77of 78.Dv stdin , 79except that the newline character (if any) is not stored in the string. 80.Pp 81The 82.Fn gets 83function 84is equivalent to 85.Fn fgets 86with an infinite 87.Fa size 88and a 89.Fa stream 90of 91.Dv stdin , 92except that the newline character (if any) is not stored in the string. 93It is the caller's responsibility to ensure that the input line, 94if any, is sufficiently short to fit in the string. 95.Sh RETURN VALUES 96Upon successful completion, 97.Fn fgets , 98.Fn gets_s , 99and 100.Fn gets 101return 102a pointer to the string. 103If end-of-file occurs before any characters are read, 104they return 105.Dv NULL 106and the buffer contents remain unchanged. 107If an error occurs, 108they return 109.Dv NULL 110and the buffer contents are indeterminate. 111The 112.Fn fgets , 113.Fn gets_s , 114and 115.Fn gets 116functions 117do not distinguish between end-of-file and error, and callers must use 118.Xr feof 3 119and 120.Xr ferror 3 121to determine which occurred. 122.Sh ERRORS 123.Bl -tag -width Er 124.It Bq Er EBADF 125The given 126.Fa stream 127is not a readable stream. 128.El 129.Pp 130The function 131.Fn fgets 132may also fail and set 133.Va errno 134for any of the errors specified for the routines 135.Xr fflush 3 , 136.Xr fstat 2 , 137.Xr read 2 , 138or 139.Xr malloc 3 . 140.Pp 141The function 142.Fn gets 143and 144.Fn gets_s 145may also fail and set 146.Va errno 147for any of the errors specified for the routine 148.Xr getchar 3 . 149.Sh SEE ALSO 150.Xr feof 3 , 151.Xr ferror 3 , 152.Xr fgetln 3 , 153.Xr fgetws 3 , 154.Xr getline 3 155.Sh STANDARDS 156The functions 157.Fn fgets 158and 159.Fn gets 160conform to 161.St -isoC-99 . 162.Fn gets_s 163conforms to 164.St -isoC-2011 165K.3.7.4.1. 166.Fn gets 167has been removed from 168.St -isoC-2011 . 169.Sh SECURITY CONSIDERATIONS 170The 171.Fn gets 172function cannot be used securely. 173Because of its lack of bounds checking, 174and the inability for the calling program 175to reliably determine the length of the next incoming line, 176the use of this function enables malicious users 177to arbitrarily change a running program's functionality through 178a buffer overflow attack. 179It is strongly suggested that the 180.Fn fgets 181function be used in all cases. 182