[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, 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 (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.

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

Related Information

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

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

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]