HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

561

562

563

564

565

566

567

568

569

570

gets(3S) gets(3S)

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-ﬁle 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-ﬁle condition is encoun-

tered. 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-ﬁle, the end-of-ﬁle indicator for the stream is set and a null pointer is returned.

When the ﬁle corresponding to an open stream gets extended after the end-of-ﬁle is reached, any subse-

quent calls to these functions will succeed and the end-of-ﬁle indicator will remain set. However, in the

UNIX2003 standards environment (see standards(5)), these functions will return a null pointer and the

end-of-ﬁle 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-ﬁle condi-

tion.

ERRORS

fgets(), fgets_unlocked()

, and gets() fail if data needs to be read into the stream ’s buffer, and:

[EAGAIN] The

O_NONBLOCK ﬂag is set for the ﬁle descriptor underlying stream and the process

would be delayed in the read operation.

[EBADF] The ﬁle descriptor underlying stream is not a valid ﬁle 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 ﬁle.

[EIO] The process is a member of a background process and is attempting to read from its con-

trolling 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().