Differential D12298 Diff 61529 head/lib/libc/stdio/fgets.3

Changeset View

Standalone View

head/lib/libc/stdio/fgets.3

	Show All 26 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93			.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd April 3, 2018			.Dd September 1, 2019
	.Dt FGETS 3			.Dt FGETS 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm fgets ,			.Nm fgets ,
	.Nm gets ,
	.Nm gets_s			.Nm gets_s
	.Nd get a line from a stream			.Nd get a line from a stream
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In stdio.h			.In stdio.h
	.Ft char *			.Ft char *
	.Fn fgets "char * restrict str" "int size" "FILE * restrict stream"			.Fn fgets "char * restrict str" "int size" "FILE * restrict stream"
	.Ft char *			.Ft char *
	.Fn gets_s "char *str" "rsize_t size"			.Fn gets_s "char *str" "rsize_t size"
	.Ft char *
	.Fn gets "char *str"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Fn fgets			.Fn fgets
	function			function
	reads at most one less than the number of characters specified by			reads at most one less than the number of characters specified by
	.Fa size			.Fa size
	from the given			from the given
	.Fa stream			.Fa stream
	Show All 15 Lines
	.Fa stream			.Fa stream
	of			of
	.Dv stdin ,			.Dv stdin ,
	except that the newline character (if any) is not stored in the string.			except that the newline character (if any) is not stored in the string.
	.Pp			.Pp
	The			The
	.Fn gets			.Fn gets
	function			function
	is equivalent to			was unsafe and is no longer available.
	.Fn fgets
	with an infinite
	.Fa size
	and a
	.Fa stream
	of
	.Dv stdin ,
	except that the newline character (if any) is not stored in the string.
	It is the caller's responsibility to ensure that the input line,
	if any, is sufficiently short to fit in the string.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	Upon successful completion,			Upon successful completion,
	.Fn fgets ,			.Fn fgets
	.Fn gets_s ,
	and			and
	.Fn gets			.Fn gets_s
	return			return
	a pointer to the string.			a pointer to the string.
	If end-of-file occurs before any characters are read,			If end-of-file occurs before any characters are read,
	they return			they return
	.Dv NULL			.Dv NULL
	and the buffer contents remain unchanged.			and the buffer contents remain unchanged.
	If an error occurs,			If an error occurs,
	they return			they return
	.Dv NULL			.Dv NULL
	and the buffer contents are indeterminate.			and the buffer contents are indeterminate.
	The			The
	.Fn fgets ,			.Fn fgets
	.Fn gets_s ,
	and			and
	.Fn gets			.Fn gets_s
	functions			functions
	do not distinguish between end-of-file and error, and callers must use			do not distinguish between end-of-file and error, and callers must use
	.Xr feof 3			.Xr feof 3
	and			and
	.Xr ferror 3			.Xr ferror 3
	to determine which occurred.			to determine which occurred.
	.Sh ERRORS			.Sh ERRORS
	.Bl -tag -width Er			.Bl -tag -width Er
	Show All 10 Lines
	for any of the errors specified for the routines			for any of the errors specified for the routines
	.Xr fflush 3 ,			.Xr fflush 3 ,
	.Xr fstat 2 ,			.Xr fstat 2 ,
	.Xr read 2 ,			.Xr read 2 ,
	or			or
	.Xr malloc 3 .			.Xr malloc 3 .
	.Pp			.Pp
	The function			The function
	.Fn gets
	and
	.Fn gets_s			.Fn gets_s
	may also fail and set			may also fail and set
	.Va errno			.Va errno
	for any of the errors specified for the routine			for any of the errors specified for the routine
	.Xr getchar 3 .			.Xr getchar 3 .
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr feof 3 ,			.Xr feof 3 ,
	.Xr ferror 3 ,			.Xr ferror 3 ,
	.Xr fgetln 3 ,			.Xr fgetln 3 ,
	.Xr fgetws 3 ,			.Xr fgetws 3 ,
	.Xr getline 3			.Xr getline 3
	.Sh STANDARDS			.Sh STANDARDS
	The functions			The
	.Fn fgets			.Fn fgets
	and			function conforms to
	.Fn gets
	conform to
	.St -isoC-99 .			.St -isoC-99 .
	.Fn gets_s			.Fn gets_s
	conforms to			conforms to
	.St -isoC-2011			.St -isoC-2011
	K.3.7.4.1.			K.3.7.4.1.
	.Fn gets			.Fn gets
	has been removed from			has been removed from
	.St -isoC-2011 .			.St -isoC-2011 .
	.Sh SECURITY CONSIDERATIONS
	The
	.Fn gets
	function cannot be used securely.
	Because of its lack of bounds checking,
	and the inability for the calling program
	to reliably determine the length of the next incoming line,
	the use of this function enables malicious users
	to arbitrarily change a running program's functionality through
	a buffer overflow attack.
	It is strongly suggested that the
	.Fn fgets
	function be used in all cases.