The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System, Second Edition

[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/stdio/fgets.3

Version: -  FREEBSD  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  cheribsd  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1  -  FREEBSD-LIBC  -  FREEBSD8-LIBC  -  FREEBSD7-LIBC  -  FREEBSD6-LIBC  -  GLIBC27 
SearchContext: -  none  -  3  -  10 

    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: head/lib/libc/stdio/fgets.3 208027 2010-05-13 12:07:55Z uqs $
   34 .\"
   35 .Dd June 4, 1993
   36 .Dt FGETS 3
   37 .Os
   38 .Sh NAME
   39 .Nm fgets ,
   40 .Nm gets
   41 .Nd get a line from a stream
   42 .Sh LIBRARY
   43 .Lb libc
   44 .Sh SYNOPSIS
   45 .In stdio.h
   46 .Ft char *
   47 .Fn fgets "char * restrict str" "int size" "FILE * restrict stream"
   48 .Ft char *
   49 .Fn gets "char *str"
   50 .Sh DESCRIPTION
   51 The
   52 .Fn fgets
   53 function
   54 reads at most one less than the number of characters specified by
   55 .Fa size
   56 from the given
   57 .Fa stream
   58 and stores them in the string
   59 .Fa str .
   60 Reading stops when a newline character is found,
   61 at end-of-file or error.
   62 The newline, if any, is retained.
   63 If any characters are read and there is no error, a
   64 .Ql \e0
   65 character is appended to end the string.
   66 .Pp
   67 The
   68 .Fn gets
   69 function
   70 is equivalent to
   71 .Fn fgets
   72 with an infinite
   73 .Fa size
   74 and a
   75 .Fa stream
   76 of
   77 .Dv stdin ,
   78 except that the newline character (if any) is not stored in the string.
   79 It is the caller's responsibility to ensure that the input line,
   80 if any, is sufficiently short to fit in the string.
   81 .Sh RETURN VALUES
   82 Upon successful completion,
   83 .Fn fgets
   84 and
   85 .Fn gets
   86 return
   87 a pointer to the string.
   88 If end-of-file occurs before any characters are read,
   89 they return
   90 .Dv NULL
   91 and the buffer contents remain unchanged.
   92 If an error occurs,
   93 they return
   94 .Dv NULL
   95 and the buffer contents are indeterminate.
   96 The
   97 .Fn fgets
   98 and
   99 .Fn gets
  100 functions
  101 do not distinguish between end-of-file and error, and callers must use
  102 .Xr feof 3
  103 and
  104 .Xr ferror 3
  105 to determine which occurred.
  106 .Sh ERRORS
  107 .Bl -tag -width Er
  108 .It Bq Er EBADF
  109 The given
  110 .Fa stream
  111 is not a readable stream.
  112 .El
  113 .Pp
  114 The function
  115 .Fn fgets
  116 may also fail and set
  117 .Va errno
  118 for any of the errors specified for the routines
  119 .Xr fflush 3 ,
  120 .Xr fstat 2 ,
  121 .Xr read 2 ,
  122 or
  123 .Xr malloc 3 .
  124 .Pp
  125 The function
  126 .Fn gets
  127 may also fail and set
  128 .Va errno
  129 for any of the errors specified for the routine
  130 .Xr getchar 3 .
  131 .Sh SEE ALSO
  132 .Xr feof 3 ,
  133 .Xr ferror 3 ,
  134 .Xr fgetln 3 ,
  135 .Xr fgetws 3 ,
  136 .Xr getline 3
  137 .Sh STANDARDS
  138 The functions
  139 .Fn fgets
  140 and
  141 .Fn gets
  142 conform to
  143 .St -isoC-99 .
  144 .Sh SECURITY CONSIDERATIONS
  145 The
  146 .Fn gets
  147 function cannot be used securely.
  148 Because of its lack of bounds checking,
  149 and the inability for the calling program
  150 to reliably determine the length of the next incoming line,
  151 the use of this function enables malicious users
  152 to arbitrarily change a running program's functionality through
  153 a buffer overflow attack.
  154 It is strongly suggested that the
  155 .Fn fgets
  156 function be used in all cases.
  157 (See
  158 the FSA.)

Cache object: 1b54ad20deacbde770f1e589b0485633


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.