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

-