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