C 库函数 - fgets()

描述

C 库函数 char *fgets(char *str, int n, FILE *stream) 从指定的流 stream 读取一行，并把它存储在 str 所指向的字符串内。当读取 (n-1) 个字符时，或者读取到换行符时，或者到达文件末尾时，它会停止，具体视情况而定。

声明

下面是 fgets() 函数的声明。

char *fgets(char *str, int n, FILE *stream)

参数

str – 这是指向一个字符数组的指针，该数组存储了要读取的字符串。
n – 这是要读取的最大字符数（包括最后的空字符）。通常是使用以 str 传递的数组长度。
stream – 这是指向 FILE 对象的指针，该 FILE 对象标识了要从中读取字符的流。
返回值
如果成功，该函数返回相同的 str 参数。如果到达文件末尾或者没有读取到任何字符，str 的内容保持不变，并返回一个空指针。

如果发生错误，返回一个空指针。

实例

下面的实例演示了 fgets() 函数的用法。

#include <stdio.h>

int main()
{
   FILE *fp;
   char str[60];

   /* 打开用于读取的文件 */
   fp = fopen("file.txt" , "r");
   if(fp == NULL) {
      perror("打开文件时发生错误");
      return(-1);
   }
   if( fgets (str, 60, fp)!=NULL ) {
      /* 向标准输出 stdout 写入内容 */
      puts(str);
   }
   fclose(fp);
   
   return(0);
}

假设我们有一个文本文件 file.txt，它的内容如下。文件将作为实例中的输入：

We are in 2014

让我们编译并运行上面的程序，这将产生以下结果：

We are in 2014

手册

man 3 fgets > fgets.txt

fegts说明

FGETC(3)                                       Linux Programmer's Manual                                      FGETC(3)

NAME
       fgetc, fgets, getc, getchar, ungetc - input of characters and strings

SYNOPSIS
       #include <stdio.h>

       int fgetc(FILE *stream);

       char *fgets(char *s, int size, FILE *stream);

       int getc(FILE *stream);

       int getchar(void);

       int ungetc(int c, FILE *stream);

DESCRIPTION
       fgetc()  reads  the next character from stream and returns it as an unsigned char cast to an int, or EOF on end
       of file or error.

       getc() is equivalent to fgetc() except that it may be implemented as a macro which evaluates stream  more  than
       once.

       getchar() is equivalent to getc(stdin).

       fgets()  reads  in at most one less than size characters from stream and stores them into the buffer pointed to
       by s.  Reading stops after an EOF or a newline.  If a newline is read, it is stored into the buffer.  A  termi‐
       nating null byte ('\0') is stored after the last character in the buffer.

       ungetc()  pushes c back to stream, cast to unsigned char, where it is available for subsequent read operations.
       Pushed-back characters will be returned in reverse order; only one pushback is guaranteed.

       Calls to the functions described here can be mixed with each other and with calls to other input functions from
       the stdio library for the same input stream.

       For nonlocking counterparts, see unlocked_stdio(3).

RETURN VALUE
       fgetc(),  getc()  and  getchar()  return the character read as an unsigned char cast to an int or EOF on end of
       file or error.

       fgets() returns s on success, and NULL on error or when end of file occurs while no characters have been read.

       ungetc() returns c on success, or EOF on error.

ATTRIBUTES
       For an explanation of the terms used in this section, see attributes(7).

       ┌──────────────────────────┬───────────────┬─────────┐
       │Interface                 │ Attribute     │ Value   │
       ├──────────────────────────┼───────────────┼─────────┤
       │fgetc(), fgets(), getc(), │ Thread safety │ MT-Safe │
       │getchar(), ungetc()       │               │         │
       └──────────────────────────┴───────────────┴─────────┘

CONFORMING TO
       POSIX.1-2001, POSIX.1-2008, C89, C99.

       It is not advisable to mix calls to input functions from the stdio library with low-level calls to read(2)  for
       the  file descriptor associated with the input stream; the results will be undefined and very probably not what
       you want.

SEE ALSO
       read(2),  write(2),  ferror(3),  fgetwc(3),  fgetws(3),  fopen(3),  fread(3),  fseek(3),  getline(3),  gets(3),
       getwchar(3), puts(3), scanf(3), ungetwc(3), unlocked_stdio(3), feature_test_macros(7)

COLOPHON
       This  page  is  part of release 4.16 of the Linux man-pages project.  A description of the project, information
       about   reporting   bugs,    and    the    latest    version    of    this    page,    can    be    found    at
       https://www.kernel.org/doc/man-pages/.

GNU                                                   2017-09-15                                              FGETC(3)

翻译说明

fgets（）从流中最多读入一个小于大小的字符，并将它们存储到s指向的缓冲区中。
读取在EOF或换行之后停止。如果一个换行被读取，它将被存储到缓冲区中。
在缓冲区的最后一个字符之后存储一个终端空字节（'\0'）