lib/libc/stdio/fgets.3

   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 .\" 4. 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
  54 The
  55 .Fn fgets
  56 function
  57 reads at most one less than the number of characters specified by
  58 .Fa size
  59 from the given
  60 .Fa stream
  61 and stores them in the string
  62 .Fa str .
  63 Reading stops when a newline character is found,
  64 at end-of-file or error.
  65 The newline, if any, is retained.
  66 If any characters are read and there is no error, a
  67 .Ql \e0
  68 character is appended to end the string.
  69 .Pp
  70 The
  71 .Fn gets_s
  72 function
  73 is equivalent to
  74 .Fn fgets
  75 with a
  76 .Fa stream
  77 of
  78 .Dv stdin ,
  79 except that the newline character (if any) is not stored in the string.
  80 .Pp
  81 The
  82 .Fn gets
  83 function
  84 is equivalent to
  85 .Fn fgets
  86 with an infinite
  87 .Fa size
  88 and a
  89 .Fa stream
  90 of
  91 .Dv stdin ,
  92 except that the newline character (if any) is not stored in the string.
  93 It is the caller's responsibility to ensure that the input line,
  94 if any, is sufficiently short to fit in the string.
  95 .Sh RETURN VALUES
  96 Upon successful completion,
  97 .Fn fgets ,
  98 .Fn gets_s ,
  99 and
 100 .Fn gets
 101 return
 102 a pointer to the string.
 103 If end-of-file occurs before any characters are read,
 104 they return
 105 .Dv NULL
 106 and the buffer contents remain unchanged.
 107 If an error occurs,
 108 they return
 109 .Dv NULL
 110 and the buffer contents are indeterminate.
 111 The
 112 .Fn fgets ,
 113 .Fn gets_s ,
 114 and
 115 .Fn gets
 116 functions
 117 do not distinguish between end-of-file and error, and callers must use
 118 .Xr feof 3
 119 and
 120 .Xr ferror 3
 121 to determine which occurred.
 122 .Sh ERRORS
 123 .Bl -tag -width Er
 124 .It Bq Er EBADF
 125 The given
 126 .Fa stream
 127 is not a readable stream.
 128 .El
 129 .Pp
 130 The function
 131 .Fn fgets
 132 may also fail and set
 133 .Va errno
 134 for any of the errors specified for the routines
 135 .Xr fflush 3 ,
 136 .Xr fstat 2 ,
 137 .Xr read 2 ,
 138 or
 139 .Xr malloc 3 .
 140 .Pp
 141 The function
 142 .Fn gets
 143 may also fail and set
 144 .Va errno
 145 for any of the errors specified for the routine
 146 .Xr getchar 3 .
 147 .Sh SEE ALSO
 148 .Xr feof 3 ,
 149 .Xr ferror 3 ,
 150 .Xr fgetln 3 ,
 151 .Xr fgetws 3 ,
 152 .Xr getline 3
 153 .Sh STANDARDS
 154 The functions
 155 .Fn fgets
 156 and
 157 .Fn gets
 158 conform to
 159 .St -isoC-99 .
 160 .Fn gets_s
 161 conforms to
 162 .St -isoC-2011
 163 K.3.7.4.1.
 164 .Fn gets
 165 has been removed from
 166 .St -isoC-2011 .
 167 .Sh SECURITY CONSIDERATIONS
 168 The
 169 .Fn gets
 170 function cannot be used securely.
 171 Because of its lack of bounds checking,
 172 and the inability for the calling program
 173 to reliably determine the length of the next incoming line,
 174 the use of this function enables malicious users
 175 to arbitrarily change a running program's functionality through
 176 a buffer overflow attack.
 177 It is strongly suggested that the
 178 .Fn fgets
 179 function be used in all cases.