Get a string from a stream.
char *fgets( char *string, int n, FILE *stream );
wchar_t *fgetws( wchar_t *string, int n, FILE *stream );
| Function | Required Header | Compatibility |
| fgets | <stdio.h> | ANSI, Win 95, Win NT |
| fgetws | <stdio.h> or <wchar.h> | ANSI, Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
Return Value
Each of these functions returns string. NULL is returned to indicate an error or an end-of-file condition. Use feof or ferror to determine whether an error occurred.
Parameters
string
Storage location for data
n
Maximum number of characters to read
stream
Pointer to FILE structure
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.
fgets is similar to the gets function; however, gets replaces the newline character with NULL. 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 |
Example
/* FGETS.C: This program uses fgets to display
* a line from a file on the screen.
*/
#include <stdio.h>
void main( void )
{
FILE *stream;
char line[100];
if( (stream = fopen( "fgets.c", "r" )) != NULL )
{
if( fgets( line, 100, stream ) == NULL)
printf( "fgets error\n" );
else
printf( "%s", line);
fclose( stream );
}
}
Output
/* FGETS.C: This program uses fgets to display