[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

gets or fgets Subroutine

Purpose

Gets a string from a stream.

Library

Standard I/O Library (libc.a)

Syntax

#include <stdio.h>
char *gets (String)
char *String;

char *fgets (String, Number, Stream)
char *String;
int Number;
FILE *Stream;

Description

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, fgets, fgetwc, fgetws, fread, fscanf, getc, getchar, 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.

Parameters

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.

Return Values

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 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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The feof, ferror, clearerr, or fileno macro, fopen, freopen, or fdopen subroutine, fread subroutine, getc, getchar, fgetc, or getw subroutine, getwc, fgetwc, or getwchar subroutine, getws or fgetws subroutine, puts or fputs subroutine, putws or fputws subroutine, scanf, fscanf, or sscanf subroutine, ungetc or ungetwc subroutine.

List of String Manipulation Services, Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]