C标准库参考指南系列译文（12）stdio.h（A）

英文原文：http://www.acm.uiuc.edu/webmonkeys/book/c_guide/2.12.html

原文作者：Eric Huss

中文译者：柳惊鸿 Poechant

版权声明：本文的原文版权归Eric Huss所有，中文译文版权归Poechant所有。转载请注明来自"柳大的CSDN博客"：http://blog.csdn.net/poechant

12. stdio.h

标准输入输出头文件提供用于输入和输出的函数。

宏:

NULL

_IOFBF

_IOLBF

_IONBF

BUFSIZ

EOF

FOPEN_MAX

FILENAME_MAX

L_tmpnam

SEEK_CUR

SEEK_END

SEEK_SET

TMP_MAX

stderr

stdin

stdout

函数:

clearerr();

fclose();

feof();

ferror();

fflush();

fgetpos();

fopen();

fread();

freopen();

fseek();

fsetpos();

ftell();

fwrite();

remove();

rename();

rewind();

setbuf();

setvbuf();

tmpfile();

tmpnam();

fprintf();

fscanf();

printf();

scanf();

sprintf();

sscanf();

vfprintf();

vprintf();

vsprintf();

fgetc();

fgets();

fputc();

fputs();

getc();

getchar();

gets();

putc();

putchar();

puts();

ungetc(); 

perror(); 

变量:

typedef size_t

typedef FILE

typedef fpos_t

12.1. 变量和定义

size_t同无符号整型，表示sizeof的结果。

FILE用于存储文件流信息的类型。

fpos_t用于存储文件中的位置信息的类型。

NULL空指针常量值。

_IOFBF,_IOLBF,和_IONBF在setvbuf函数中使用。

BUFSIZ表示在setbuf函数中使用的buffer的大小的整型变量。

EOF是负整型变量，表示文件的末尾位置。

FOPEN_MAX同时最多可以打开的文件数。

FILENAME_MAX一个字符数组表示的文件名的最大长度。如果实现时希望尽量对文件名长度没有限制，则这个值建议设置为最大值。

L_tmpnam由tmpnam函数创建的临时文件的文件名最大长度。

SEEK_CUR,SEEK_END,和SEEK_SET用于函数 fseek。

TMP_MAX函数 tmpnam能够产生的唯一文件名的最大数。

stderr,stdin,和stdout指向响应标准错误、标准输入和标准输出的FILE类型的指针。

12.2. 流和文件

流促进了实现一个介于程序与IO设备之间的抽象层的方式。流允许在多样的IO设备之间读写数据的操作。有两种类型的流，分别是文本流和二进制流。

文本流是由行（line）组成的。每行有0或0个以上字符，并且由一个换行符标示一行的结束。数据的转换发生在文本的输出输出中。文本流由可打印字符、制表符、换行符组成。空格不能在换行符之前出现，尽管这与具体的实现中读取文本时是否移除空格有关。具体的实现至少要支持每行有254个字符（包括换行符）的情形。

二进制流输入输出是将数据以 1:1 比例传输的。没有任何转换存在，所有的字符都会被传输。

一个程序一旦启动，就有标准输入、标准输出和标准错误三个可用流。

程序中所使用到的文件，必须先打开然后通过流进行操作。文件IO中所操作的点，由文件位置（file position）决定。当采用追加模式打开一个文件时，file position 指向文件尾，而其他方式打开时，则指向文件头。file position 随读写操作为变化，始终标示着下一次操作的位置。

关闭文件后，就不能对它进行任何操作了。从 main 函数退出时，所有被打开的文件都会被自动关闭。

12.3. 文件函数

12.3.1. clearerr

声明:

void clearerr(FILE *stream);

清除流stream的文件尾指示器和错误指示器。在错误指示器被表示为有错误产生时，如果不调用clearerr或者rewind函数，则任何流操作都会返回错误。

12.3.2. fclose

声明:

int fclose(FILE *stream);

关闭流。所有的buffer都会被flush。如果关闭成功，则返回0，否则返回EOF。

12.3.3. feof

声明:

int feof(FILE *stream);

检查流stream是否到达文件尾。如果流到达文件尾，则返回非零值；如果流没有到达文件尾，则返回零。（即返回非零表示到文件尾）

12.3.4. ferror

声明:

int ferror(FILE *stream);

检查错误指示器。如果有错误产生，则返回非零；如果错误指示器没有被设置，则表明没有错误，返回零。（即返回非零表示有错误）

12.3.5. fflush

声明:

int fflush(FILE *stream);

Flush流stream 的输出 buffer。如果流是空指针，则所有输出buffer会被 flush。如果成功，返回零。错误则返回EOF。

12.3.6. fgetpos

声明:

int fgetpos(FILE *stream, fpos_t *pos);

获取到文件流的当前位置，将它写到pos中。如果成功，则返回0，如果错误则返回非零值，并且将错误码存储到变量errno中。

12.3.7. fopen

声明:

FILE *fopen(const char *filename, const char *mode);

开启一个由 filename 变量指定文件名的文件。打开的模式参数mode取值及含义如下：

r

读取文本文件

w

写入文本文件 (重置文件，或者创建文件)

a

追加文本文件 (打开文件，或者创建文件，且为追加模式)

rb

读取二进制文件

wb

写入二进制文件 (重置文件，或者创建文件)

ab

追加二进制文件 (打开文件，或者创建文件，且为追加模式)

r+

读取和写入文本文件

w+

读取和写入文本文件 (重置文件，或者创建文件)

a+

读取和写入文本文件 (打开文件，或者创建文件，且为追加模式)

r+b或者 rb+

读取和写入二进制文件

w+b或者 wb+

读取和写入二进制文件 (重置文件，或者创建文件)

a+b或者 ab+

读取和写入二进制文件 (打开文件，或者创建文件，且为追加模式)

如果用 r 模式打开了不存在的文件，则 open 失败。

如果用 a 模式打开文件，则无论当前文件位置在哪里，所有的写入操作都会以追加模式进行。

如果用+ 更新模式打开文件，因为此模式既可以输入，也可以输出，所以在每次在输入与输出操作之间切换时，必须使用函数 fseek, fsetpos, rewind,或 fflush。

打开文件成功，则返回指向文件的指针（根据不同模式，指向不同的位置）。打开失败，则返回空指针。

12.3.8. fread

声明:

size_t fread(void *ptr, size_tsize, size_t nmemb, FILE *stream);

将数据从流 stream 读取到 ptr 所指示的数组。读取nmemb个 size 大小的元素。所以，读取的总字节数为 (size*nmemb)。成功则返回读取的元素个数，错误或到达文件尾则返回目前成功读取的元素数（可能为0）。

12.3.9. freopen

声明:

FILE *freopen(const char *filename, const char *mode, FILE *stream);

用给定的 stream来打开一个新的文件（由 filename 指定文件名）。此前打开的文件会被关闭。如果关闭旧文件而出现错误，错误会被忽略。模式参数 mode 与函数 fopen 中描述的一样。通常用来重新连接 stdin, stdout,或者 stderr。成功则返回指向文件流的指针，错误则返回空指针。

12.3.10. fseek

声明:

int fseek(FILE *stream, long intoffset, int whence);

设置文件流的file position为给定的偏移量参数 offset。参数 offset 的偏移起始点，是参数 whence 指定的位置。参数whence的可选值有：

SEEK_SET

从文件头开始搜索。

SEEK_CUR

从文件当前位置开始搜索。

SEEK_END

从文件尾开始搜索。

在一个文本流中，参数 whence应该是SEEK_SET，并且参数offset 应该是0或者由ftell返回的一个值。

文件尾指示器被重置。错误指示器不被重置。

成功则返回0，错误则返回非零值。

12.3.11. fsetpos

声明:

int fsetpos(FILE *stream, const fpos_t *pos);

设置流stream的 file position为给定的 pos。参数pos 是由函数fgetpos给定的。文件尾指示器会被 clear 。成功则返回0。失败则返回一个非零值，并且errno会被设置。

12.3.12. ftell

声明:

long int ftell(FILE *stream);

返回文件流中当前的 file position。如果是一个二进制流，则值为从文件开始处到当前位置的字节数。如果是一个文本流，则值为 fseek函数使用的用来返回当前的文件位置的值。

成功则返回当前的 file position。错误则返回-1L，并且errno被设置。

12.3.13. fwrite

声明:

size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);

将数据从ptr指示的数组，写入到流 stream 中。写入nmemb 个size 大小的元素。所以，总的写入字节数为 (size*nmemb)。成功则返回写入的元素个数。错误则返回成功写入的元素个数（可能为0）。

12.3.14. remove

声明:

int remove(const char *filename);

删除文件（硬盘删除），之后该文件无法在被访问（解除到文件的连接）。如果当前文件是打开状态，则结果由实现决定。成功则返回0。错误则返回非零值。

12.3.15. rename

声明:

int rename(const char *old_filename, const char *new_filename);

将名为old_filename文件，更名为 new_filename文件。如果由new_filename 指定的文件名存在，则结果是由实现所确定的。成功则返回0。错误则返回一个非零值，并且仍可以通过旧文件名（old_filename）来访问。

12.3.16. rewind

声明:

void rewind(FILE *stream);

设置 file position为给定文件流的开始处。错误指示器和文件尾指示器会被重置。

12.3.17. setbuf

声明:

void setbuf(FILE *stream, char *buffer);

定义流如何被缓冲（buffer）。这个函数要在打开流之后、任何操作还没有进行之前被调用。输入和输出是全缓冲的（fully buffered）。默认值BUFSIZ是缓冲区的大小。参数 buffer 指向用作缓冲区的数组变量。如果 buffer 是一个空指针，则流被当做无缓冲的。

12.3.18. setvbuf

声明:

int setvbuf(FILE *stream, char *buffer, int mode, size_tsize);

这个函数与 12.3.17 中的 setvbuf 函数功能相同，只是参数不同。参数mode定义了流采取的缓冲方式，可以设置为如下值：

_IOFBF

输入和输出全缓冲（fully buffered）。如果缓冲区为空，一个输入操作可以填充 buffer。On output the buffer will be completely filled至于输出的情况，缓冲区在任何信息被写入文件之前(或者流关闭)会被完全填满.

_IOLBF

输入和输出行缓冲（line buffered）。如果缓冲区为空，一个输入操作可以填充 buffer。当向缓冲区写入一个换行符时，缓冲区会被 flush。

_IONBF

输入和输出不缓冲（not buffered）。输入和输出都不缓冲。

参数buffer指向当做缓冲区的数组。如果 buffer 为空指针，则setvbuf调用malloc创建一个它自己的 buffer。

参数size是 buffer 所指定的数组的大小。

成功则返回0。错误则返回非零值。

12.3.19. tmpfile

声明:

FILE *tmpfile(void);

以二进制更新模式(wb+)创建临时文件。当程序结束或者流被关闭时，tempfile会被移除。

成功则返回指向文件流的FILE指针，错误则返回空。

12.3.20. tmpnam

声明:

char *tmpnam(char *str);

产生并返回一个当前不存在的可用文件名。最多产生TMP_MAX个不同的文件名。

如果参数str是空指针，则函数返回一个指向可用文件名的指针。如果参数 str 是一个指向字符数组的有效指针，则产生的文件名会被写入到这个数组，并且返回指向这个数组的指针。文件名长度的字节数最多为L_tmpnam。

该系列译文在持续更新中⋯⋯

C标准库参考指南系列译文（1）assert.h

C标准库参考指南系列译文（2）ctype.h

C标准库参考指南系列译文（3）errno.h

C标准库参考指南系列译文（4）float.h

C标准库参考指南系列译文（5）limits.h

C标准库参考指南系列译文（6）locale.h

C标准库参考指南系列译文（7）math.h

C标准库参考指南系列译文（8）setjmp.h

C标准库参考指南系列译文（9）signal.h

C标准库参考指南系列译文（10）stdarg.h

C标准库参考指南系列译文（11）stddef.h

C标准库参考指南系列译文（12）stdio.h（A）

版权声明：本文的原文版权归Eric Huss所有，中文译文版权归Poechant所有。转载请注明来自"柳大的CSDN博客"：http://blog.csdn.net/poechant

-