関数CKfopen マニュアル

(The documentation of function CKfopen)

Last Update: 2023/4/11

◆機能・用途(Purpose)

関数fopen(ファイルのオープン)をエラーチェック付きで実行する。
Call function fopen (opening a file) with error checks.

◆形式(Format)

#include <functions_with_errcheck.h>
inline FILE_L CKfopen (const char ∗filename,const char ∗openmode)

◆引数(Arguments)

filename

開きたいファイル名。
The name of the file to open.

openmode

開くモード。以下のいずれかとする。
The mode to open, which must be one of the followings.

読み込みモード (Reading mode):
"r", "r+", "rb", "r+b" ,"rb+"
書き込みモード (Writing mode):
"w", "w+", "wb", "w+b" ,"wb+"
"w-", "w+-", "wb-", "w+b-" ,"wb+-"
追加書き込みモード (Addition mode):
"a", "a+", "ab", "a+b" ,"ab+"

書き込みモードでは同名のファイルが既に存在する場合、プログラムはその旨をユーザに知らせ、古いファイルを削除(上書き)しても良いか否かをユーザに尋ねる。但し「-」が付くモードを選択した場合にはユーザへの確認なしに上書きが行われる。これ以外は関数fopenの第2引数と同じ意味である。なお「+」が付くモードは検証を行っていないので利用は非推奨とする。
If the file already exists in case of the writing mode, the program informs it to the user, and consults the user if he/she allows the program to remove the old file and overwrite it by the new file. The modes with “-” skips this procedure and overwrites the existing file without consulting the user. Except for this behaviour, the meanings of this argument are identical to those of the 2nd argument of function fopen. Note that the modes with “+” are discouraged, as the behaviour of these modes have not been checked.

◆動作とエラーチェック (Behaviour and error checks)

下表で桃色のセルがエラー処理を表す。
The pick colored cells in the table below represent error checks.

条件 Condition	動作 Behaviour of the function
引数filenameの文字列長が0 The string length of the argument filename is 0	プログラムをエラー終了する。 The program finishes as an error.
引数openmodeがいずれの候補とも一致しない The argument openmode is equal to none of the candidates	プログラムをエラー終了する。 The program finishes as an error.
引数openmodeが「r」から始まり(読み込みモード)、引数filenameで指定されたファイルが存在しない The argument openmode begins with “r” (a reading mode) and the file specified by argument filename is absent	プログラムをエラー終了する。 The program finishes as an error.
引数filenameで指定されたファイルが存在し、通常のファイルではない (関数stat, S_ISREGにより判定) The file specified by argument filename is present and not a regular file according to functions stat and S_ISREG	プログラムをエラー終了する。 The program finishes as an error.
引数filenameで指定されたファイルが存在し、引数openmodeが「w」で始まり「-」以外で終わる (上書き前チェック有りの書き込みモード) The file specified by argument filename is present, and the argument openmode begins with “w” and does not end with “-”; (a writing mode with checks before overwriting)	ファイルを上書きして良いか否かをユーザに尋ねる。ユーザの回答が「y」以外であればプログラムをエラー終了する。ユーザの回答が「y」の場合は次の処理に進む。 Consult the user if he/she allows overwriting the existing file. If the answer was other than “y”, the program finishes as an error. If the answer was “y”, the program continues to the next procedure.
引数filenameで指定されたファイルが存在せず、そのディレクトリパスも存在しない The file specified by argument filename is absent and its directory path is also absent	引数openmodeが「r」から始まる場合(読み込みモード)、プログラムをエラー終了する。引数openmodeが「-」で終わる場合(確認なし上書きモード)、ディレクトリパスを作成する。それ以外の場合はディレクトリパスを作成するか否かをユーザに訪ねる。ディレクトリの作成後は次の処理に進む。 The program finishes as an error if the argument openmode begins with “r” (a reading mode). The program automatically creates the path directory if the argument openmode ends with “-’ (a writing mode without checks for overwriting). In the other cases, the program consults the user to allow creating a directory or not. After creating the directory, the program continues to the next procedure.
ここまでのチェックでエラーが起きていない No error has occurred until this step	ファイルをオープンし、排他ロックをかける。 Open the file and apply an exclusive lock.
オープンした際の戻り値がNULL The opening of the file returned NULL	プログラムをエラー終了する。 The program finishes as an error.

◆戻り値(Return value)

オープンしたファイルのファイルポインタから成る構造体。各メンバの値は以下のようになる。
A structure composed of the file pointers returned by opening the file. The values of the members are as follows.

引数openmodeの値 The value of argument openmode	メンバmain Member main	メンバkeep Member keep
"r"または"rb" "r" or "rb"	関数fopenを用いてファイルfilenameをモードopenmodeで開いた戻り値 The return value of function fopen for opening the file filename with the mode openmode	ファイルの排他ロックのため、関数myflock を用いてファイルfilenameをモード"a"(追加書き込み)で開いた戻り値 The return value of function myflock for opening the file filename with the mode "a" (an addition mode)
その他 Other	関数myflock を用いてファイルfilenameをモードopenmode(但し末尾の「-」は除く)で開いた戻り値 The return value of function myflock for opening the file filename with the mode openmode without “-” at the end	NULL

◆使用例(Example)

FILE_L fp=CKfopen("data.dat","w");
fprintf(fp.main,"%d\n",1);
CKfclose(fp);

◆補足(Additional nodes)

実際のファイルの読み書きには上の例のように戻り値のメンバmainを用いること。またファイルを閉じるには関数CKfcloseを用いること。
To read and write the file opened, use the member main of the return value, as the example above shows. To close the file, use function CKfclose.

メンバkeepはファイルの排他ロックをかけるためのものであり、ユーザは意識する必要は無い。内部的な処理としては、読み込み専用モード("r"または"rb")でファイルを開く際に同じファイルを追加書き込みモードで開いてその戻り値をメンバkeepに代入することにより、読み込みの途中で他のプログラムによってファイルが改変されることを防ぐ仕組みである。
Users need not be aware of the member keep. This member is used for an exclusive file lock. Internally, a file opened with a read-only mode ("r" or "rb") is also opened with an addition mode and its return value is inserted into the member keep. This avoids changes of the file by other programs while reading.