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