Gets a string from a stream.
Standard I/O Library (libc.a)
The gets subroutine reads bytes from the standard input stream, stdin, into the array pointed to by the String parameter. It reads data until it reaches a new-line character or an end-of-file condition. If a new-line character stops the reading process, the gets subroutine discards the new-line character and terminates the string with a null character.
The fgets subroutine reads bytes from the data pointed to by the Stream parameter into the array pointed to by the String parameter. The fgets subroutine reads data up to the number of bytes specified by the Number parameter minus 1, or until it reads a new-line character and transfers that character to the String parameter, or until it encounters an end-of-file condition. The fgets subroutine then terminates the data string with a null character.
The first successful run of the fgetc (getc, getchar, fgetc, or getw Subroutine), fgets, fgetwc (getwc, fgetwc, or getwchar Subroutine), fgetws (getws or fgetws Subroutine), fread (fread or fwrite Subroutine), fscanf, getc (getc, getchar, fgetc, or getw Subroutine), getchar (getc, getchar, fgetc, or getw Subroutine), gets or scanf subroutine using a stream that returns data not supplied by a prior call to the ungetc or ungetwc subroutine marks the st_atime field for update.
| Item | Description |
|---|---|
| String | Points to a string to receive bytes. |
| Stream | Points to the FILE structure of an open file. |
| Number | Specifies the upper bound on the number of bytes to read. |
If the gets or fgets subroutine encounters the end of the file without reading any bytes, it transfers no bytes to the String parameter and returns a null pointer. If a read error occurs, the gets or fgets subroutine returns a null pointer and sets the errno global variable (errors are the same as for the fgetc (getc, getchar, fgetc, or getw Subroutine) subroutine). Otherwise, the gets or fgets subroutine returns the value of the String parameter.
Note: Depending upon which library routine the application binds to, this subroutine may return EINTR. Refer to the signal subroutine regarding the SA_RESTART value.