标准 IO 输入函数

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.
	   /*fgetc 从流中读取下一个字符并将其转换成无符号 char 型后再作为 int 型返回，如果读取到文件的结尾或者读取错误时返回 EOF（-1）*/

       getc() is equivalent to fgetc() except that it may be implemented as a macro which evaluates stream more  than once.
	   /*getc 等价于 fgetc，但是 getc 是作为一个宏来执行的，因此在操作时 getc 的参数不应当是具有副作用的表达式，否则可能会被计算多次（参加 APUE 中文版 P121）
	   from APUE:
	   1. The argument to getc should not be an expression with side effects.
	   2.Since fgetcis guaranteed to be a function, we can take its address. This allows us to pass the address of fgetcas an argument to another function. 
	   3.Calls to fgetcprobably take longer than calls togetc, as it usually takes more time to call a function*/

       getchar() is equivalent to getc(stdin).
	   /*getchar 等价于 getc(stdin)
	   在<stdio.h>中：
	   #define getc(_fp) _IO_getc(_fp)
	   
	   __STDIO_INLINE int getchar(void)
	   {return _IO_getc(stdin);}
	   
	   __STDIO_INLINE = inline 内联函数标志，C++ 关键字*/

       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.
	   /*fgets 最多从流中读取小于 size 字节的字符然后把他们存储到 s 指向的缓存区内。当读取遇到 EOF（文件结束标志）或 换行符时停止。如果最后读取的是换行符，那么同样也会将换行符储存到缓存区内。缓存区在最后一次字符之后会全部填充
	   空字符 NULL（'\0'）*/

       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.
	   /*ungetc 函数是将参数 c 转换成无符号字符然后重新压回流中，可用于后续的读操作，但是在后序读出字符的顺序与压回去的 顺序相反。一次只能压送回去一个字符
	   注：ungetc 压送回的字符并没有将它们写到底层文件或设备中，知是将它们写回标准 I/O 的流缓冲区中*/

       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).
	   /*对于非锁定的输入函数，请参阅 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.
	   /*fgetc, getc 和 getchar 会将读取到的字符转换成无符号类型字符后再以 int 类型作为返回值，如果读取到文件末尾或者 出错时返回 EOF
	   注：为了区分是读取到文件末尾还是出错，必须调用 ferror 或 feof 函数*/

       fgets() returns s on success, and NULL on error or when end of file occurs while no characters have been read.
	   /*fgets 成功返回指针 s 所指向的字符串首地址，出错或者读取时正好处于文件末尾处（没有可读的字符）时返回 NULL*/

       ungetc() returns c on success, or EOF on error.
	   /*ungetc 成功返回所压送的字符 c（转换成 int 型），出错返回 EOF*/

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.
	   /*对于和输入流相关的文件描述符，不建议将标准库的输入函数与低级（这里的低级指的是更接近硬件底层的函数，一般为系统调用）的read 混合使用，如果这样做可能会产生一些未知的问题，并且结果非常有可能并不是你想要的*/

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.04 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 http://www.kernel.org/doc/man-pages/.

GNU                                                   2015-08-08                                             FGETC(3)