fgets、fgetwsfgets, fgetws

从流获取字符串。Get a string from a stream.

语法Syntax

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

参数Parameters

strstr
数据的存储位置。Storage location for data.

numCharsnumChars
要读取的最大字符数。Maximum number of characters to read.

streamstream
指向文件结构的指针。Pointer to FILE structure.

返回值Return Value

其中每个函数都会返回strEach of these functions returns str. 返回NULL以指示错误或文件尾条件。NULL is returned to indicate an error or an end-of-file condition. 使用feofferror来确定是否发生了错误。Use feof or ferror to determine whether an error occurred. 如果strstream是 Null 指针,或numChars小于或等于零,则此函数将调用无效参数处理程序,如参数验证中所述。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. 如果允许执行继续,则将errno设置为EINVAL ,并且该函数将返回NULLIf execution is allowed to continue, errno is set to EINVAL and the function returns NULL.

有关这些代码以及其他错误代码的详细信息,请参阅 _doserrno、errno、_sys_errlist 和 _sys_nerrSee _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these, and other, error codes.

备注Remarks

Fgets函数从输入参数读取字符串,并将其存储在str中。The fgets function reads a string from the input stream argument and stores it in str. fgets将字符从当前流位置读取到流的末尾,并包含第一个换行符,或直到读取的字符数等于numChars ,以先达到的字符数为准。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. In str中存储的结果追加一个 null 字符。The result stored in str is appended with a null character. 换行符(如果读取)将包括在字符串中。The newline character, if read, is included in the string.

fgetwsfgets的宽字符版本。fgetws is a wide-character version of fgets.

fgetws读取宽字符参数str作为多字节字符字符串或宽字符字符串,具体取决于是以文本模式还是二进制模式打开的。fgetws reads the wide-character argument str as a multibyte-character string or a wide-character string according to whether stream is opened in text mode or binary mode, respectively. 有关在 Unicode 和多字节流 I/O 中使用文本和二进制模式的详细信息,请参阅文本和二进制模式文件 I/O文本和二进制模式下的 Unicode 流 I/OFor 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 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_fgetts_fgetts fgetsfgets fgetsfgets fgetwsfgetws

要求Requirements

函数Function 必需的标头Required header
fgetsfgets <stdio.h><stdio.h>
fgetwsfgetws <stdio.h> 或 <wchar.h><stdio.h> or <wchar.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

// crt_fgets.c
// This program uses fgets to display
// the first line from a file.

#include <stdio.h>

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

   if( fopen_s( &stream, "crt_fgets.txt", "r" ) == 0 )
   {
      if( fgets( line, 100, stream ) == NULL)
         printf( "fgets error\numChars" );
      else
         printf( "%s", line);
      fclose( stream );
   }
}

输入:crt_fgets.txtInput: crt_fgets.txt

Line one.
Line two.

OutputOutput

Line one.

请参阅See also

流 I/OStream I/O
fputs、fputwsfputs, fputws
gets、_getwsgets, _getws
puts、_putwsputs, _putws