fgets-fgetws.md

description	title	ms.date	api_name	api_location	api_type	topic_type	f1_keywords	helpviewer_keywords	ms.assetid
Learn more about: fgets, fgetws	fgets, fgetws	4/2/2020	fgets fgetws _o_fgets _o_fgetws	msvcrt.dll msvcr80.dll msvcr90.dll msvcr100.dll msvcr100_clr0400.dll msvcr110.dll msvcr110_clr0400.dll msvcr120.dll msvcr120_clr0400.dll ucrtbase.dll api-ms-win-crt-stdio-l1-1-0.dll	DLLExport	apiref	_fgetts fgetws fgets	_fgetts function streams, getting strings from streams, reading from fgets function fgetws function fgetts function	ad549bb5-df98-4ccd-a53f-95114e60c4fc

fgets, fgetws

Get a string from a stream.

Syntax

char*fgets( char*str, intnumChars, FILE*stream ); wchar_t*fgetws( wchar_t*str, intnumChars, FILE*stream );

Parameters

str
Storage location for data.

numChars
Maximum number of characters to read.

stream
Pointer to FILE structure.

Return value

Each of these functions returns str. NULL is returned to indicate an error or an end-of-file condition. Use feof or ferror to determine whether an error occurred. If str or stream is a null pointer, or numChars is less than or equal to zero, this function invokes the invalid parameter handler, as described in Parameter validation. If execution is allowed to continue, errno is set to EINVAL and the function returns NULL.

For more information about return codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Remarks

The fgets function reads a string from the input stream argument and stores it in str. 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 numChars - 1, whichever comes first. The result stored in str 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 str as a multibyte-character string or as a wide-character string when 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.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

TCHAR.H routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_fgetts	fgets	fgets	fgetws

Requirements

Function	Required header
fgets	<stdio.h>
fgetws	<stdio.h> or <wchar.h>

For more compatibility information, see Compatibility.

Example

// crt_fgets.c// This program uses fgets to display// the first line from a file.#include<stdio.h>intmain( void ) { FILE*stream; charline[100]; if( fopen_s( &stream, "crt_fgets.txt", "r" ) ==0 ) { if( fgets( line, 100, stream ) ==NULL) printf( "fgets error\numChars" ); elseprintf( "%s", line); fclose( stream ); } }

Input: crt_fgets.txt

Line one. Line two. 

Output

Line one. 

See also

Stream I/O
fputs, fputws
gets, _getws
puts, _putws