GETS(3s,L)                  AIX Technical Reference                  GETS(3s,L)



-------------------------------------------------------------------------------
gets, fgets, getws, fgetws



PURPOSE

Reads characters or wide characters from a stream.

LIBRARY

Standard I/O Library (libc.a)

SYNTAX

#include <stdio.h>




                char *gets (s)              char *fgets (s, n, stream)
                char *s;                    char *s;
                                            int n;
                wchar_t *getws (s)          FILE *stream;
                wchar_t *s;

                wchar_t *fgetws (s, n, stream)
                wchar_t *s;
                int n;
                FILE *stream;



DESCRIPTION

The gets subroutine reads characters from the standard input stream, stdin,
into the array pointed to by the s parameter.  Data is read until a new-line
character is read or an end-of-file condition is encountered.  If reading is
stopped due to a new-line character, the new-line character is discarded and
the string is terminated with a null character.

The fgets subroutine reads characters from the data pointed to by the stream
parameter into the array pointed to by the s parameter.  Data is read until
n - 1 characters have been read, until a new-line character is read and
transferred to s, or until an end-of-file condition is encountered.  The string
is then terminated with a null character.

The getws subroutine reads wide characters from the input stream pointed to by
stdin into the array pointed to by s until end-of-file is encountered or a
new-line character is read. Any new-line character is discarded, and a NULL
character is written immediately after the last character read into the array.




Processed November 7, 1990        GETS(3s,L)                                  1






GETS(3s,L)                  AIX Technical Reference                  GETS(3s,L)



The fgetws subroutine reads wide characters (at most one less than the number
of the characters specified by n) from the stream pointed to by stream into the
array pointed to by s.  No additional characters are read after a new-line
character (which is retained) or after end-of-file. A NULL character is written
immediately after the last character read into the array.

RETURN VALUE

If end-of-file is encountered and no characters have been read, no characters
are transferred to s and a NULL pointer is returned.  If a read error occurs, a
NULL pointer is returned.  Otherwise, s is returned.

ERROR CONDITIONS

The gets and fgets subroutines fail if one or more of the following are true:

EAGAIN    The O_NONBLOCK flag is set for the file descriptor underlying stream
          and the process would be delayed in the fgetc 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
          no data was transferred.

EIO       The process is a member of a background process attempting to read
          from its controlling terminal, the process is either ignoring or
          blocking the SIGTTIN signal or the process group is orphaned.

ENOMEM    Insufficient storage space is available.

ENXIO     A request was made of a non-existent device, or the request was
          outside the capabilities of the device.

RELATED INFORMATION

In this book:  "feof, ferror, clearerr, fileno," "fopen, freopen, fdopen,"
"fread, fwrite," "getc, fgetc, getchar, getw, getwc, fgetwc, getwchar," "puts,
fputs, putws, fputws," "scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf,
wsscanf," and "stdio."















Processed November 7, 1990        GETS(3s,L)                                  2