NAME
gets(), fgets() — get a string from a stream
SYNOPSIS
#include <stdio.h>
char *gets(char *s);
char *fgets(char *__restrict s, int n, FILE *__restrict stream);
Obsolescent Interface
char *fgets_unlocked(char *s, int n, FILE *stream);
DESCRIPTION
- gets()
Reads characters from the standard input stream,
stdin,
into the array pointed to by
s,
until a new-line character is read
or an end-of-file condition is encountered.
The new-line character is discarded
and the string is terminated with a null character.
- fgets()
Reads characters from the
stream
into the array pointed to by
s,
until
n-1
characters are read,
a new-line character is read and transferred to
s,
or an end-of-file condition is encountered.
The string is then terminated with a null character.
Obsolescent Interface
fgets_unlocked()
gets a string from a stream.
APPLICATION USAGE
After
gets()
or
fgets()
is applied to a stream, the stream becomes byte-oriented (see
orientation(5)).
RETURN VALUE
Upon successful completion,
fgets(),
fgets_unlocked(),
and
gets()
return
s.
If the stream is at end-of-file,
the end-of-file indicator for the stream is set
and a null pointer is returned.
When the file corresponding to an open stream gets extended after the
end-of-file is reached, any subsequent calls to these functions
will succeed and the end-of-file indicator will remain set.
However, in the UNIX2003 standards environment (see
standards(5)),
these functions will return a null pointer and the
end-of-file indicator will still remain set.
If a read error occurs, the error indicator for the stream is set,
errno
is set to indicate the error, and a null pointer is returned.
ferror()
and
feof()
can be used to distinguish between an error condition
and an end-of-file condition.
ERRORS
fgets(),
fgets_unlocked(),
and
gets()
fail if data needs to be read into the
stream's
buffer, and:
- EAGAIN
The
O_NONBLOCK
flag is set for the file descriptor underlying
stream
and the process would be delayed in the read operation.
- EBADF
The file descriptor underlying
stream
is not a valid file descriptor open for reading.
- EINTR
The read operation was terminated due to the receipt of a signal,
and either no data was transferred
or the implementation does not report partial transfer for this file.
- EIO
The process is a member of a background process
and is attempting to read from its controlling terminal,
and either the process is ignoring or blocking the
SIGTTIN
signal or the process group of the process is orphaned.
Additional
errno
values can be set by the underlying
read()
function (see
read(2)).
WARNINGS
fgets_unlocked()
is an obsolescent interface supported only for compatibility with existing
DCE applications. New multithreaded applications should use
fgets().
SEE ALSO
ferror(3S),
flockfile(3S),
fopen(3S),
fread(3S),
getc(3S),
puts(3S),
scanf(3S),
orientation(5),
standards(5),
thread_safety(5),
glossary(9).
STANDARDS CONFORMANCE
gets(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
fgets(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
Printable version
