NAME    [Toc]    [Back]

       gets, fgets - Get a string from a stream

SYNOPSIS    [Toc]    [Back]

       #include <stdio.h>

       char *gets(
               char *string ); char *fgets(
               char *string,
               int n,
               FILE *stream );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       gets(), fgets():  XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Points  to  a string to receive bytes.  Specifies an upper
       bound on the number of bytes to read.  Points to the  FILE
       structure of an open file.

DESCRIPTION    [Toc]    [Back]

       The  gets()  function  reads bytes from the standard input
       stream, stdin, into the array pointed  to  by  the  string
       parameter.  Data is read until a newline character is read
       or an end-of-file condition is encountered. If reading  is
       stopped  due to a newline character, the newline character
       is discarded and the string  is  terminated  with  a  null
       byte.

       The  fgets() function reads bytes from the data pointed to
       by the stream parameter into the array pointed to  by  the
       string  parameter.  Data is read until n-1 bytes have been
       read, until a newline character is read and transferred to
       string,  or until an end-of-file condition is encountered.
       The string is then terminated with a null byte.

NOTES    [Toc]    [Back]

       The gets function does not check the input for  a  maximum
       size.  Consequently,  if  more bytes are entered than will
       fit in the  space  allocated  for  the  string  parameter,
       gets()  will  write beyond the end of the allocated space,
       producing indeterminate results. To avoid this  condition,
       use fgets() instead of gets().

RETURN VALUES    [Toc]    [Back]

       Upon  successful  completion, the gets() and fgets() functions
 return string. If the stream is at end-of-file,  the
       end-of-file  indicator  for  the  stream is set and a null
       pointer is returned. If a read  error  occurs,  the  error
       indicator  for  the  stream  is  set,  a  null  pointer is
       returned, and errno is set to indicate the error.

ERRORS    [Toc]    [Back]

       The fgets() and gets() functions set errno to  the  specified
  value  for  the following conditions: The O_NONBLOCK
       option is set for the underlying stream  and  the  process
       would be delayed by the read operation.  The file descriptor
 underlying the stream is not a valid  file  descriptor
       or is not open for reading.  The read operation was interrupted
 by a signal which was caught and no data was transferred.
  The call is attempting to read from the process's
       controlling terminal and either the process is ignoring or
       blocking  the  SIGTTIN  signal  or  the  process  group is
       orphaned.  Insufficient memory is available for the operation.
  The device associated with stream does not exist.

SEE ALSO    [Toc]    [Back]

       Functions:  clearerr(3),  feof(3),  ferror(3),  fgetws(3),
       fileno(3),   fopen(3),   fputws(3),   fread(3),   getc(3),
       getwc(3), puts(3), scanf(3)

       Standards: standards(5)



                                                          gets(3)