fgets, fgetws

Run-Time Library Reference

fgets, fgetws

Get a string from a stream.

Copy

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

Parameters

string

Storage location for data.

n

Maximum number of characters to read.

stream

Pointer to FILE structure.

Return Value

Each of these functions returns string. NULL is returned to indicate an error or an end-of-file condition. Use feof orferror to determine whether an error occurred.

Remarks

The fgets function reads a string from the input stream argument and stores it in string. fgets reads characters from the current stream position to and including the first newline character, to the end of the stream, or until the number of characters read is equal to n – 1, whichever comes first. The result stored in string is appended with a null character. The newline character, if read, is included in the string.

fgetws is a wide-character version of fgets.

fgetws reads the wide-character argument string as a multibyte-character string or a wide-character string according to whether stream is opened in text mode or binary mode, respectively. For more information about using text and binary modes in Unicode and multibyte stream-I/O, see Text and Binary Mode File I/O and Unicode Stream I/O in Text and Binary Modes.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined

_fgetts	fgets	fgets	fgetws

Requirements

Function Required header Compatibility

fgets	<stdio.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
fgetws	<stdio.h> or <wchar.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

Copy

// crt_fgets.c
/* This program uses fgets to display
 * a line from a file on the screen.
 */

#include <stdio.h>

int main( void )
{
   FILE *stream;
   char line[100];

   if( (stream = fopen( "crt_fgets.txt", "r" )) != NULL )
   {
      if( fgets( line, 100, stream ) == NULL)
         printf( "fgets error\n" );
      else
         printf( "%s", line);
      fclose( stream );
   }
}

Input: crt_fgets.txt

Copy

Line one.
Line two.

Output

Copy

Line one.

See Also

Stream I/O Routines | fputs | gets | puts | Run-Time Routines and .NET Framework Equivalents