日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
FCNTL(2) FreeBSD システムコールマニュアル FCNTL(2)
名称
fcntl -- ファイル制御
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <fcntl.h>
int
fcntl(int fd, int cmd, ...);
解説
fcntl() システムコールは、記述子の制御を提供しています。引数 fd は、下記
のように cmd によって操作される記述子です。cmd の値によって、fcntl() は、
追加の 3 番目の引数 int arg を取ることができます。
F_DUPFD 次のような新しい記述子を返します:
• arg 以上の最小の番号付けされた利用可能な記述
子。
• オリジナルの記述子と同じオブジェクトの参照。
• 新しい記述子は、オブジェクトがファイルだったな
ら、同じファイルのオフセットを共有します。
• 同じアクセスモード (読み込み、書き込みまたは読
み込み/書き込み)。
• 同じファイル状態フラグ (すなわち、両方のファイ
ル記述子は、同じファイル状態フラグを共有しま
す)。
• 新しいファイル記述子に関連した close-on-exec フ
ラグ FD_CLOEXEC は、クリアされるので、ファイル
記述子は、execve(2) システムコールに渡ってオー
プンされたままであることです。
F_DUPFD_CLOEXEC F_DUPFD に似ていますが、新しいファイル記述子に関連した
FD_CLOEXEC フラグは、設定されるので、execve(2) システム
コールが実行するとき、ファイル記述子は、クローズされま
す。
F_DUP2FD それは、次と機能的に同等です。
dup2(fd, arg)
F_DUP2FD_CLOEXEC F_DUP2FD に似ていますが、新しいファイル記述子に関連した
FD_CLOEXEC フラグが設定されます。
F_DUP2FD と F_DUP2FD_CLOEXEC 定数は、移植性がないので、
移植性を必要とするなら、それらを使用するべきではありま
せん。F_DUP2FD の代わりに dup2() を使用します。
F_GETFD FD_CLOEXEC としてファイル記述子 fd に関連する close-on
exec フラグを取得します。FD_CLOEXEC で論理積 (AND) され
た返された値が 0 であるなら、ファイルは、exec() に渡っ
てオープンされたままとなり、そうでなければ、ファイル
は、exec() の実行時にクローズされます (arg は、無視され
ます)。
F_SETFD fd に関連する close-on-exec フラグを arg に設定します、
ここで arg は、0 または前述のように FD_CLOEXEC です。
F_GETFL 下記のように記述子の状態フラグを取得します (arg は、無
視されます)。
F_SETFL 記述子の状態フラグを arg に設定します。
F_GETOWN 現在 SIGIO と SIGURG シグナルを受信しているプロセス ID
またはプロセスグループを取得します。プロセスグループ
は、負の値として返されます (arg は、無視されます)。
F_SETOWN SIGIO と SIGURG シグナルを受信するようにプロセスまたは
プロセスグループに設定します。プロセスグループは、負の
値として arg を供給することによって指定され、そうでなけ
れば、arg は、プロセス ID として解釈されます。
F_READAHEAD 最も近いブロックサイズに丸められる、3 番目の引数 arg へ
のシーケンシャルアクセスのための先読みの量を設定する
か、またはクリアします。0 の値の arg は、先読みをオフに
し、負の値は、システムデフォルトを復旧します。
F_RDAHEAD 3 番目の引数 arg が 0 でないなとき、128KB の先読みの量
を設定する Darwin 対応物と同等です。0 の値の arg は、先
読みをオフにします。
F_GETFL と F_SETFL のためのフラグは、次の通りです:
O_NONBLOCK 非ブロッキング I/O。データが read(2) システムコールに利用可
能ではないか、または、write(2) 操作がブロックするなら、読み
込みまたは書き込み呼び出しは、エラー EAGAIN で -1 を返しま
す。
O_APPEND 各書き込みをファイルの終わりに追加するように強制します。
open(2) の O_APPEND フラグに対応しています。
O_DIRECT 読み込みと読み書きのキャッシュ効果を最小化するか、または除去
します。システムは、利用者が読み込み、または書き込むデータを
キャッシュすることを避けることを試みます。それが、データの
キャッシュを避けることができないなら、それは、データがキャッ
シュに持っている影響を最小化します。このフラグの使用は、注意
して使用されないなら、性能を大幅に落すかもしれません。
O_ASYNC 例えば、読み込まれるデータの利用可能性で、I/O が可能なとき、
プロセスグループに送られる SIGIO シグナルを有効にします。
いくつかのコマンドがアドバイザリ (advisory) ファイルロックを行うために利
用可能です。それらは、すべて次の構造体で操作を行います:
struct flock {
off_t l_start; /* 開始オフセット */
off_t l_len; /* len = 0 は, ファイルの終りまでを
意味します */
pid_t l_pid; /* ロック所有者 */
short l_type; /* ロックタイプ: 読み込み/書き込み等 */
short l_whence; /* l_start のタイプ */
int l_sysid; /* リモートシステム ID またはローカルの
ための 0 */
};
アドバイザリ (advisory) レコードロックに利用可能なコマンドは、次の通りで
す:
F_GETLK struct flock (上記参照) へのポインタとして取られた 3 番目の引
数 arg によって指されたロック記述をブロックする最初のロックを
取得します。検索され取れ出された情報は、flock 構造体の fcntl()
に渡された情報に上書きします。それと気付かれないならば、作成さ
れるこのロックを防止するロックが見つからないなら、構造体は、
F_UNLCK に設定されるロックタイプを除いて、このシステムコールに
よって変更されないままとなります。
F_SETLK struct flock (上記参照) へのポインタとして取られた 3 番目の引
数 arg によって指されたロック記述にしたがってファイルセグメン
トのロックを設定するか、またはクリアします。F_SETLK は、ロック
(F_UNLCK) のいずれかのタイプを削除するのと同様に、共有 (または
読み込み) ロック (F_RDLCK) または排他的な (または書き込み)
ロック (F_WRLCK) を確立するために使用されます。共有ロックまた
は排他的ロックを設定することができないなら、fcntl() は、EAGAIN
で直ちに返ります。
F_SETLKW このコマンドは、共有ロックまたは排他的ロックが他のロックでブ
ロックされているなら、プロセスが、要求を満たすことができるま
で、待機することを除いて、F_SETLK ど同じです。fcntl() が領域の
ために待機している間に、捕獲されるシグナルが受信されるなら、
fcntl() は、シグナルハンドラが SA_RESTART (sigaction(2) を参
照) を指定しなかったなら、割り込まれます。
共有ロックがファイルのセグメントに設定されたとき、他のプロセスは、そのセ
グメントまたはそれの部分で共有ロックを設定することができます。共有ロック
は、保護された領域のあらゆる部分に排他的ロックを設定することからあらゆる
他のプロセスを防止します。ファイル記述子が、読み込みアクセスでオープンさ
れなかったなら、共有ロックのための要求は、失敗します。
排他的ロックは、保護された領域のあらゆる部分に共有ロックまたは排他的ロッ
クを設定することからあらゆる他のプロセスを防止します。ファイルが書き込み
アクセスでオープンされなかったなら、排他的ロックのための要求は、失敗しま
す。
l_whence の値は、相対的なオフセット l_start バイトが、それぞれ、ファイル
の始め、現在の位置、またはファイルの終わりから測定されることを示す
SEEK_SET, SEEK_CUR または SEEK_END です。l_len の値は、ロックされる連続し
たバイト数です。l_len が負であるなら、l_start は、領域の終端を意味しま
す。l_pid と l_sysid フィールドは、そのプロセスを所有しているシステムのブ
ロックしているロックとシステム ID を保持しているプロセスのプロセス ID を
返すために、F_GETLK でのみ使用されます。ローカルなシステムによって作成さ
れたロックには、0 のシステム ID があります。F_GETLK 要求が成功した後に、
l_whence の値は、SEEK_SET です。
ロックは、現在のファイルの終わりを越えて開始して、拡張できますが、ファイ
ルの始めの前で開始するか、または拡張することはできません。ロックは、l_len
が 0 に設定されるなら、そのファイルのためにファイルオフセットの可能な最大
の値に拡張するように設定されます。l_whence と l_start が、ファイルの始ま
りを指し、l_len が、0 であるなら、ファイル全体が、ロックされます。アプリ
ケーションがファイル全体のロックだけを望むなら、flock(2) システムコール
は、さらに効率的です。
ファイルのバイトごとに設定されたロックの最大 1 つタイプがあります。呼び出
しているプロセスが、要求によって指定された領域のバイトで以前に存在してい
るロックがあるとき、F_SETLK または F_SETLKW 要求から成功して返る前に、指
定された領域のバイトごとの以前のロックタイプは、新しいロックタイプによっ
て置き換えられます。共有ロックと排他的ロックの記述の元で上で指定されたよ
うに、F_SETLK または F_SETLKW 要求は、別のプロセスが、指定された領域のバ
イトに既存のロックがあり、それらのロックのいずれかのタイプが要求で指定さ
れたタイプと衝突するとき、それぞれ、失敗するか、またはブロックします。
ローカルなファイルの F_SETLKW 要求のためのキューは、公正です。すなわち、
スレッドがブロックさる間に、たとえこれらの要求が既存のロックで矛盾してい
なくても、その要求がある矛盾しているその後の要求は、与えられません。
このインタフェースは、そのファイルのためのあらゆるファイル記述子がそのプ
ロセスによってクローズされるとき、与えられたプロセスのためのファイルに関
連したすべてのロックが削除されることを必要とする、System V と IEEE Std
1003.1-1988 (``POSIX.1'') の愚かなセマンティクスに完全に従います。このセ
マンティクスは、アプリケーションが、サブルーチンライブラリがアクセスする
あらゆるファイルに気が付いていなければならないことを意味します。例えば、
パスワードファイルを更新するためのアプリケーションが更新を行う間に、パス
ワードファイルデータベースをロックし、次に、レコードを検索するために、
getpwnam(3) を呼び出すなら、getpwnam(3) がパスワードデータベースをオープ
ンし、読み込み、そしてクローズするので、ロックは、失われます。データベー
スのクローズは、たとえライブラリルーチンがデータベースのロックを決して要
求しなくても、プロセスがデータベースに関連しているすべてのロックを解放し
ます。このインタフェースの別の軽微なセマンティクスの問題は、ロックが、
fork(2) システムコールを使用して作成された子プロセスによって継承されない
ことです。flock(2) インタフェースには、ずっと理性的な最後のクローズのセマ
ンティクスがあり、子プロセスによってロックを継承することができます。
flock(2) システムコールは、ライブラリルーチンを使用するか、またはロックを
それらの子プロセスに渡したいとき、それらのロックの整合性を保証したいアプ
リケーションのために推薦されます。
fcntl(), flock(2) と lockf(3) ロックは、互換性があります。異なったロック
のインタフェースを使用しているプロセスは、同じファイルで安全に協調するこ
とができます。しかしながら、そのようなインタフェースの 1 つだけが、同じプ
ロセス内で使用されるべきです。ファイルが flock(2) を通したプロセスによっ
てロックされるなら、ファイル内のあらゆるレコードは、fcntl() または
lockf(3) を使用している別のプロセスの観点から、逆もまた同様に、ロックされ
ているように見られます。fcntl(F_GETLK) は、ブロックしているロックを保持し
ているプロセスが flock(2) によってファイル記述子を以前にロックしていたな
ら、l_pid に -1 を返すことに注意してください。
与えられたプロセスのためのファイルに関連したすべてのロックは、プロセスが
終了するとき、取り除かれます。
execve(2) の呼び出しの前に取得されていた、すべてのロックは、実際に、新し
いプログラムがそれらを解放するまで、残ります。新しいプログラムがロックに
関して知らないなら、それらは、プログラムが終了するまで解放されません。
ロックされた領域を制御しているプロセスが、別のプロセスのロックされた領域
をロックすることを試みによってスリープ状態にされるなら、デッドロックが起
こる可能性があります。この実装は、ロックされた領域がアンロックされるま
で、スリープすることによって、デッドロックを起こし、EDEADLK エラーで失敗
することを検出します。
戻り値
成功して完了するなら、cmd によって返される値は、次の通りです:
F_DUPFD 新しいファイル記述子。
F_DUP2FD arg と等しいファイル記述子。
F_GETFD フラグの値 (下位ビットだけが定義されています)。
F_GETFL フラグの値。
F_GETOWN ファイル記述子所有者の値。
その他 -1 以外の値。
そうでなければ、-1 の値が返され、エラーを示す値が errno に設定されます。
エラー
fcntl() システムコールは、次の場合に失敗します:
[EAGAIN] 引数 cmd が、F_SETLK であり、ロックのタイプ (l_type)
が、共有ロック (F_RDLCK、) または排他的ロック
(F_WRLCK) で、ロックされるファイルのセグメントが、既に
別のプロセスによって排他的にロックされています。また
は、タイプが排他的なロックで、ロックされるファイルのセ
グメントの一部分が既に別のプロセスによって共有ロックま
たは排他的ロックされています。
[EBADF] fd 引数が有効なオープンされたファイル記述子ではありま
せん。
引数 cmd が、F_DUP2FD であり、arg が有効なファイル記述
子ではありません。
引数 cmd が、F_SETLK または F_SETLKW であり、ロック
(l_type) のタイプが、共有されたロック (F_RDLCK) であ
り、fd が、読み込みのためにオープンされた有効なファイ
ル記述子ではありません。
引数 cmd が、F_SETLK または F_SETLKW であり、ロックの
タイプ (l_type) が、排他的ロック (F_WRLCK) であり、fd
が、書み込みのためにオープンされた有効なファイル記述子
ではありません。
[EDEADLK] 引数 cmd が、F_SETLKW であり、デッドロックの状態が検出
されました。
[EINTR] 引数 cmd が、F_SETLKW であり、システムコールが、シグナ
ルによって割り込まれました。
[EINVAL] cmd 引数が、F_DUPFD であり、arg が、負であるかまたは許
可される最大の数より大きくなっています
(getdtablesize(2) を参照)。
引数 cmd が、F_GETLK, F_SETLK または F_SETLKW であり、
arg が指すデータが、有効でありません。
[EMFILE] 引数 cmd が、F_DUPFD であり、プロセスのために許可され
ているファイル記述子の最大数が、既に使用中であるか、ま
たは arg 以上のファイル記述子が、利用できません。
[ENOLCK] 引数 cmd が、F_SETLK または F_SETLKW であり、ロック要
求またはアンロック要求を満たすことが、システムに課せら
れた制限を越えるシステムのロックされたリージョン (領
域) の結果となります。
[EOPNOTSUPP] 引数 cmd が、F_GETLK, F_SETLK または F_SETLKW であり、
fd が、ロックをサポートしていないファイルを参照してい
ます。
[EOVERFLOW] 引数 cmd が、F_GETLK, F_SETLK または F_SETLKW であり、
off_t の計算が、オーバフローしました。
[EPERM] cmd 引数が、F_SETOWN であり、引数として与えられたプロ
セス ID またはプロセスグループが、呼び出し側と異なる
セッション内にあります。
[ESRCH] cmd 引数が、F_SETOWN であり、引数として与えられたプロ
セス ID が、使用中ではありません。
さらに、fd が (ソケットでオープンされた記述子とは対象的に) 端末デバイスで
オープンされた記述子を参照しているなら、F_SETOWN の cmd が、tcsetpgrp(3)
のような同じ理由のために失敗するかもしれず、F_GETOWN の cmd が、
tcgetpgrp(3) で述べたような理由で失敗するかもしれません。
関連項目
close(2), dup2(2), execve(2), flock(2), getdtablesize(2), open(2),
sigaction(2), lockf(3), tcgetpgrp(3), tcsetpgrp(3)
規格
F_DUP2FD 定数は、移植性がありません。それは、AIX と Solaris との互換性を
提供します。
Version 4 of the Single UNIX Specification (``SUSv4'') ごとに、F_SETLKW
での呼び出しは、あらゆる捕獲されたシグナルの後に、[EINTR] で失敗し、停止
シグナルのようなスレッドの一時停止の間にウェートし続けるべきです。しかし
ながら、この実装で F_SETLKW がある呼び出しは、SA_RESTART ハンドラがあるシ
グナルを捕獲するか、または停止シグナルのようなスレッドの一時停止の後に、
再開されます。
歴史
fcntl() システムコールは、4.2BSD で登場しました。
F_DUP2FD 定数は、FreeBSD 7.1 ではじめて登場しました。
FreeBSD 11.2 July 7, 2016 FreeBSD 11.2