Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
open, openat, creat - ファイルのオープン、作成を行う
書式
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);
int creat(const char *pathname, mode_t mode);
int openat(int dirfd, const char *pathname, int flags);
int openat(int dirfd, const char *pathname, int flags, mode_t mode);
/* Documented separately, in openat2(2): */
int openat2(int dirfd, const char *pathname,
const struct open_how *how, size_t size);
glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):
openat():
glibc 2.10 以降:
_POSIX_C_SOURCE >= 200809L
glibc 2.10 より前:
_ATFILE_SOURCE
説明
The open() system call opens the file specified by pathname. If the specified file does
not exist, it may optionally (if O_CREAT is specified in flags) be created by open().
The return value of open() is a file descriptor, a small, nonnegative integer that is
used in subsequent system calls (read(2), write(2), lseek(2), fcntl(2), etc.) to refer to
the open file. The file descriptor returned by a successful call will be the
lowest-numbered file descriptor not currently open for the process.
デフォルトでは、新しいファイルディスクリプターは execve(2) を実行した後も オープンされたま
まとなる (つまり、 fcntl(2) に説明がある FD_CLOEXEC ファイルディスクリプターフラグは最初は
無効である); 後述の O_CLOEXEC フラグ を使うとこのデフォルトを変更することができる。 ファイ
ルオフセット (file offset) はファイルの先頭に設定される (lseek(2) 参照)。
open() を呼び出すと、「オープンファイル記述」 (open file description) が作成される。ファ
イル記述とは、システム全体のオープン中のファイルのテーブルのエントリーである。 このオープ
ンファイル記述は、ファイルオフセットとファイル状態フラグ (下記参照) が保持する。 ファイル
ディスクリプターはオープンファイルっ記述への参照である。 この後で pathname が削除された
り、他のファイルを参照するように変更されたりしても、 この参照は影響を受けない。 オープン
ファイル記述の詳細な説明は「注意」の節を参照。
引数 flags には、アクセスモード O_RDONLY, O_WRONLY, O_RDWR のどれかひとつが入っていなけれ
ばならない。 これらはそれぞれ読み込み専用、書き込み専用、読み書き用に ファイルをオープンす
ることを要求するものである。
In addition, zero or more file creation flags and file status flags can be bitwise-or'd in
flags. The file creation flags are O_CLOEXEC, O_CREAT, O_DIRECTORY, O_EXCL, O_NOCTTY,
O_NOFOLLOW, O_TMPFILE, and O_TRUNC. The file status flags are all of the remaining flags
listed below. The distinction between these two groups of flags is that the file creation
flags affect the semantics of the open operation itself, while the file status flags
affect the semantics of subsequent I/O operations. The file status flags can be retrieved
and (in some cases) modified; see fcntl(2) for details.
すべてのファイル作成フラグとファイル状態フラグを以下のリストに示す。
O_APPEND
The file is opened in append mode. Before each write(2), the file offset is
positioned at the end of the file, as if with lseek(2). The modification of the
file offset and the write operation are performed as a single atomic step.
O_APPEND may lead to corrupted files on NFS filesystems if more than one process
appends data to a file at once. This is because NFS does not support appending to
a file, so the client kernel has to simulate it, which can't be done without a race
condition.
O_ASYNC
シグナル駆動 I/O (signal-driven I/O) を有効にする: このファイルディスクリプターへの
入力または出力が可能になった場合に、シグナルを生成する (デフォルトは SIGIO である
が、 fcntl(2) によって変更可能である)。 この機能が使用可能なのは端末、疑似端末、ソ
ケットのみであり、 (Linux 2.6 以降では) パイプと FIFO に対しても使用できる。 さらに
詳しい説明は fcntl(2) を参照すること。 下記の「バグ」も参照。
O_CLOEXEC (Linux 2.6.23 以降)
新しいファイルディスクリプターに対して close-on-exec フラグを有効にする。 このフラ
グを指定することで、 プログラムは FD_CLOEXEC フラグをセットするために fcntl(2)
F_SETFD 操作を別途呼び出す必要がなくなる。
ある種のマルチスレッドのプログラムはこのフラグの使用は不可欠である点に注意するこ
と。 なぜなら、個別に FD_CLOEXEC フラグを設定する fcntl(2) F_SETFD 操作を呼び出した
としても、あるスレッドがファイルディスクリプターを オープンするのと同時に別のスレッ
ドが fork(2) と execve(2) を実行するという競合条件を避けるのには十分ではないからで
ある。 実行の順序に依存して、この競合条件の結果、 open() が返したファイルディスクリ
プターが fork(2) で作成された子プロセスにより実行されるプログラムに意図せず見えてし
まう可能性がある。 (この種の競合は、 本質的に、 close-on-exec フラグをセットすべき
ファイルディスクリプターを作成するどのシステムコールでも起こり得るものであり、 他の
いろいろな Linux システムコールでこの問題に対処するために O_CLOEXEC と同等の機能が
提供されている。)
O_CREAT
If pathname does not exist, create it as a regular file.
The owner (user ID) of the new file is set to the effective user ID of the process.
The group ownership (group ID) of the new file is set either to the effective group
ID of the process (System V semantics) or to the group ID of the parent directory
(BSD semantics). On Linux, the behavior depends on whether the set-group-ID mode
bit is set on the parent directory: if that bit is set, then BSD semantics apply;
otherwise, System V semantics apply. For some filesystems, the behavior also
depends on the bsdgroups and sysvgroups mount options described in mount(8).
The mode argument specifies the file mode bits to be applied when a new file is
created. If neither O_CREAT nor O_TMPFILE is specified in flags, then mode is
ignored (and can thus be specified as 0, or simply omitted). The mode argument
must be supplied if O_CREAT or O_TMPFILE is specified in flags; if it is not
supplied, some arbitrary bytes from the stack will be applied as the file mode.
The effective mode is modified by the process's umask in the usual way: in the
absence of a default ACL, the mode of the created file is (mode & ~umask).
Note that mode applies only to future accesses of the newly created file; the
open() call that creates a read-only file may well return a read/write file
descriptor.
mode のために以下のシンボル定数が提供されている :
S_IRWXU 00700 ユーザー (ファイルの所有者) に読み込み、書き込み、 実行の許可があ
る。
S_IRUSR 00400 ユーザーに読み込みの許可がある。
S_IWUSR 00200 ユーザーに書き込みの許可がある。
S_IXUSR 00100 ユーザーに実行の許可がある。
S_IRWXG 00070 グループに読み込み、書き込み、実行の許可がある。
S_IRGRP 00040 グループに読み込みの許可がある。
S_IWGRP 00020 グループに書き込みの許可がある。
S_IXGRP 00010 グループに実行の許可がある。
S_IRWXO 00007 他人 (others) に読み込み、書き込み、実行の許可がある。
S_IROTH 00004 他人に読み込みの許可がある。
S_IWOTH 00002 他人に書き込みの許可がある。
S_IXOTH 00001 他人に実行の許可がある。
According to POSIX, the effect when other bits are set in mode is unspecified. On
Linux, the following bits are also honored in mode:
S_ISUID 0004000 set-user-ID bit
S_ISGID 0002000 set-group-ID bit (see inode(7)).
S_ISVTX 0001000 sticky bit (see inode(7)).
O_DIRECT (Linux 2.4.10 以降)
このファイルに対する I/O のキャッシュの効果を最小化しようとする。このフラグを使う
と、一般的に性能が低下する。 しかしアプリケーションが独自にキャッシングを行っている
ような 特別な場合には役に立つ。 ファイルの I/O はユーザー空間バッファーに対して直接
行われる。 O_DIRECT フラグ自身はデータを同期で転送しようとはするが、 O_SYNC フラグ
のようにデータと必要なメタデータの転送が保証されるわけではない。同期 I/O を保証する
ためには、 O_DIRECT に加えて O_SYNC を使用しなければならない。下記の「注意」の節の
議論も参照。
ブロックデバイスに対する似通った意味のインターフェースが raw(8) で説明されている
(但し、このインターフェースは非推奨である)。
O_DIRECTORY
pathname がディレクトリでなければオープンは失敗する。 このフラグは、 opendir(3) が
FIFO やテープデバイスに対してコールされた場合の サービス不能 (denial-of-service) 攻
撃を避けるために カーネル 2.1.126 で追加された。
O_DSYNC
ファイルに対する書き込み操作は、同期 I/O のデータ完全性完了の要件に基づいて行われ
る。
write(2) (や同様のコール) が返るまでに、 書き込まれたデータおよびデータを取得するの
に必要なファイルメタデータが裏で利用されているハードウェアに転送される (つま
り、write(2) の後に fdatasync(2) を呼び出したのと同じようになる)。 下記の「注意」も
参照のこと。
O_EXCL この呼び出しでファイルが作成されることを保証する。このフラグが O_CREAT と一緒に指定
され、 pathname のファイルが既に存在した場合、 open() は EEXIST エラーで失敗する。
これら二つのフラグが指定された際、シンボリックリンクは辿られない。 pathname がシン
ボリックリンクの場合、 シンボリックリンクがどこを指しているかに関わらず open() は
失敗する。
一般的には、 O_CREAT を指定せずに O_EXCL を使用した場合の O_EXCL の動作は規定されて
いない。 これには一つ例外があり、Linux 2.6 以降では、 pathname がブロックデバイスを
参照している場合、 O_CREAT なしで O_EXCL を使用することができる。 システムがそのブ
ロックデバイスを使用中の場合 (例えば、 マウントされているなど)、 open() はエラー
EBUSY で失敗する。
NFS では、 O_EXCL は、Linux 2.6 以降で NFSv3 以降を使っている場合でのみサポートされ
る。 O_EXCL サポートが提供されていない NFS 環境では、このフラグに頼って ロック処理
を実行するプログラムは競合状態 (race condition) に出会う 可能性がある。 ロックファ
イルを使用して不可分 (atomic) なファイルロックを実現し、 NFS が O_EXCL をサポートし
ているかに依存しないようにしたい場合、 移植性のある方法は、同じファイルシステム上に
他と名前の重ならない ファイル (例えばホスト名と PID を組み合わせた名前) を作成し、
link(2) を使用してそのロックファイルへのリンクを作成することである。 link(2) コー
ルの返り値が 0 ならばロックに成功している。 あるいは、そのファイルに stat(2) を使
用してリンク数 (link count) が 2 になっているかをチェックする。 そうなっていれ
ば、同じくロックに成功しているということである。
O_LARGEFILE
(LFS) off_t ではサイズを表せない (だだし off64_t ではサイズを表せる)ファ イルをオー
プン可能にする。この定義を有効にするためには、(どのヘッダーファイ ルをインクルード
するよりも前に) _LARGEFILE64_SOURCE マクロを定義しなければ ならない。 32 ビットシス
テムにおいて大きなファイルにアクセスしたい場合、 (O_LARGEFILE を使うよりも)
_FILE_OFFSET_BITS 機能検査マクロを 64 に セットする方が望ましい方法である
(feature_test_macros(7) を参照)。
O_NOATIME (Linux 2.6.8 以降)
Do not update the file last access time (st_atime in the inode) when the file is
read(2).
This flag can be employed only if one of the following conditions is true:
* The effective UID of the process matches the owner UID of the file.
* The calling process has the CAP_FOWNER capability in its user namespace and the
owner UID of the file has a mapping in the namespace.
このフラグはインデックス作成やバックアッププログラムで使うことを意図している。 これ
を使うとディスクに対する操作を大幅に減らすことができる。 このフラグは全てのファイル
システムに対して有効であるわけではない。 その一例が NFS であり、サーバがアクセス時
刻を管理している。
O_NOCTTY
pathname が端末 (terminal) デバイス — tty(4) 参照 — を指している 場合に、たとえその
プロセスが制御端末を持っていなくても、オープンしたファイル は制御端末にはならない。
O_NOFOLLOW
If the trailing component (i.e., basename) of pathname is a symbolic link, then the
open fails, with the error ELOOP. Symbolic links in earlier components of the
pathname will still be followed. (Note that the ELOOP error that can occur in this
case is indistinguishable from the case where an open fails because there are too
many symbolic links found while resolving components in the prefix part of the
pathname.)
This flag is a FreeBSD extension, which was added to Linux in version 2.1.126, and
has subsequently been standardized in POSIX.1-2008.
See also O_PATH below.
O_NONBLOCK または O_NDELAY
可能ならば、ファイルは非停止 (nonblocking) モードでオープンされる。 open() も、返し
たファイルディスクリプターに対する以後のすべての操作も呼び出したプロセスを待たせる
ことはない。
Note that the setting of this flag has no effect on the operation of poll(2),
select(2), epoll(7), and similar, since those interfaces merely inform the caller
about whether a file descriptor is "ready", meaning that an I/O operation performed
on the file descriptor with the O_NONBLOCK flag clear would not block.
Note that this flag has no effect for regular files and block devices; that is, I/O
operations will (briefly) block when device activity is required, regardless of
whether O_NONBLOCK is set. Since O_NONBLOCK semantics might eventually be
implemented, applications should not depend upon blocking behavior when specifying
this flag for regular files and block devices.
FIFO (名前付きパイプ) を扱う場合には fifo(7) も参照すること。 強制ファイルロック
(mandatory file lock) やファイルリース (file lease) と組み合わせた場合の、
O_NONBLOCK の効果についての議論は、 fcntl(2) を参照すること。
O_PATH (Linux 2.6.39 以降)
このフラグを指定して取得したファイルディスクリプターは、 ファイルシステムツリー内で
の場所を示すため、 純粋にファイルディスクリプターレベルでの作用する操作を実行するた
め、 の二つの目的で使用することができる。 ファイル自身はオープンされず、 他のファイ
ル操作 (例えば read(2), write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2),
mmap(2)) はエラー EBADF で失敗する。
取得したファイルディスクリプターに対して以下の操作を行うことが「できる」。
* close(2).
* fchdir(2), if the file descriptor refers to a directory (since Linux 3.5).
* fstat(2) (Linux 3.6 以降).
* fstatfs(2) (Linux 3.12 以降).
* ファイルディスクリプターの複製 (dup(2), fcntl(2) F_DUPFD など)
* ファイルディスクリプターフラグの取得と設定 (fcntl(2) の F_GETFD と F_SETFD)
* fcntl(2) の F_GETFL 操作を使ったオープンされたファイルの状態フラグの取得。 返さ
れるフラグには O_PATH ビットが含まれる。
* openat() や他の "*at()" 系のシステムコールの dirfd 引数としてそのファイルディス
クリプターを渡す。 これには、 ファイルがディレクトリでない場合に linkat(2) に
AT_EMPTY_PATH が指定された場合 (や procfs 経由で AT_SYMLINK_FOLLOW が使用された
場合) を含む。
* そのファイルディスクリプターを別のプロセスに UNIX ドメインソケット経由で渡す。
(unix(7) の SCM_RIGHTS を参照)
flags に O_PATH が指定された場合、 O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW 以外のフラグ
ビットは無視される。
Opening a file or directory with the O_PATH flag requires no permissions on the
object itself (but does require execute permission on the directories in the path
prefix). Depending on the subsequent operation, a check for suitable file
permissions may be performed (e.g., fchdir(2) requires execute permission on the
directory referred to by its file descriptor argument). By contrast, obtaining a
reference to a filesystem object by opening it with the O_RDONLY flag requires that
the caller have read permission on the object, even when the subsequent operation
(e.g., fchdir(2), fstat(2)) does not require read permission on the object.
pathname がシンボリックリンクで O_NOFOLLOW フラグも合わせて指定された場合、 この呼
び出しではシンボリックリンクを参照するファイルディスクリプターを返す。 このファイル
ディスクリプターは、 空のパス名を指定した fchownat(2), fstatat(2), linkat(2),
readlinkat(2) の呼び出しで dirfd 引数として使うことで、 そのシンボリックリンクに対
して操作を行うことができる。
If pathname refers to an automount point that has not yet been triggered, so no
other filesystem is mounted on it, then the call returns a file descriptor
referring to the automount directory without triggering a mount. fstatfs(2) can
then be used to determine if it is, in fact, an untriggered automount point
(.f_type == AUTOFS_SUPER_MAGIC).
One use of O_PATH for regular files is to provide the equivalent of POSIX.1's
O_EXEC functionality. This permits us to open a file for which we have execute
permission but not read permission, and then execute that file, with steps
something like the following:
char buf[PATH_MAX];
fd = open("some_prog", O_PATH);
snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
execl(buf, "some_prog", (char *) NULL);
An O_PATH file descriptor can also be passed as the argument of fexecve(3).
O_SYNC ファイルに対する書き込み操作は、同期 I/O のファイル完全性完了の要件に基づいて行われ
る (これに対し O_DSYNC では同期 I/O のデータ完全性完了が提供される)。
write(2) (や同様のコール) が返るまでに、 書き込まれたデータと関連するファイルメタ
データが裏で利用されているハードウェアに転送される (つまり、write(2) の後に
fsync(2) を呼び出したのと同じようになる)。 下記の「注意」も参照のこと。
O_TMPFILE (Linux 3.11 以降)
名前なしの一時的な通常ファイルを作成する。 pathname 引数はディレクトリを指定する。
名前なしの inode がそのディレクトリが存在するファイルシステムに作成される。 その
ファイルに名前を付与しない限り、 作成されたファイルに書き込まれた内容は、 最後の
ファイルディスクリプターがクローズされる際に失われる。
O_TMPFILE は必ず O_RDWR か O_WRONLY のいずれかと一緒に使わなければならない。 O_EXCL
も指定することができる。 O_EXCL が指定されなかった場合、 linkat(2) を使って、その
ファイルシステムにこの一時ファイルへのリンクを作成し、ファイルを永続化することがで
きる。 以下のコードのようにすればよい。
char path[PATH_MAX];
fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
S_IRUSR | S_IWUSR);
/* 'fd' に対するファイル I/O ... */
linkat(fd, NULL, AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
/* If the caller doesn't have the CAP_DAC_READ_SEARCH
capability (needed to use AT_EMPTY_PATH with linkat(2)),
and there is a proc(5) filesystem mounted, then the
linkat(2) call above can be replaced with:
snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
AT_SYMLINK_FOLLOW);
*/
この場合、 open() の mode 引数は O_CREAT と同様にファイルのアクセス許可モードの決定
に使われる。
O_TMPFILE とともに O_EXCL を指定すると、 一時ファイルに対して上記の方法でファイルシ
ステムへのリンクを行うことができなくなる (この場合の O_EXCL の意味は他の場合の
O_EXCL の意味とは異なる点に注意)。
O_TMPFILE には主に二つの用途がある。
* 改善された tmpfile(3) の機能: (1) クローズ時に自動的に削除される、 (2) パス名で
は決して参照できない、 (3) シンボリックリンク攻撃ができない、 (4) 呼び出し元が一
意な名前を考える必要がない、 という特長を持つ競合のない一時ファイルの作成。
* 最初は見えないファイルを作成し、 それからデータを書き込んだり、適切なファイルシ
ステム属性を持つように調整したり (fchown(2), fchmod(2), fsetxattr(2) など) した
後、 準備が全て整った状態で (上述の linkat(2) を使って) ファイルシステム内にアト
ミックにリンクを行う。
O_TMPFILE requires support by the underlying filesystem; only a subset of Linux
filesystems provide that support. In the initial implementation, support was
provided in the ext2, ext3, ext4, UDF, Minix, and shmem filesystems. Support for
other filesystems has subsequently been added as follows: XFS (Linux 3.15); Btrfs
(Linux 3.16); F2FS (Linux 3.16); and ubifs (Linux 4.9)
O_TRUNC
ファイルが既に存在し、通常ファイルであり、 アクセスモードで書き込みが許可されている
(つまり、 O_RDWR または O_WRONLY の) 場合、長さ 0 に切り詰め (truncate) られる。
ファイルが FIFO または端末デバイスファイルの場合、 O_TRUNC フラグは無視される。 そ
れ以外の場合、 O_TRUNC の効果は未定義である。
creat()
creat() の呼び出しは、 flags に O_CREAT|O_WRONLY|O_TRUNC を指定して open() を呼び出すのと
等価である。
openat()
openat() システムコールは open() と全く同様に動作するが、以下で説明する点が異なる。
pathname で指定されたパス名が相対パスの場合、このパス名はファイルディスクリプター dirfd が
参照するディレクトリに対する相対パスと解釈される (open() に相対パス名を渡した場合のよう
に、呼び出したプロセスのカレントワーキングディレクトリに対する相対パスではない)。
pathname で指定されたパス名が相対パスで、 dirfd が特別な値 AT_FDCWD の場合、 (open() と同
様に) pathname は呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈
される。
pathname で指定されたパス名が絶対パスの場合、 dirfd は無視される。
openat2(2)
The openat2(2) system call is an extension of openat(), and provides a superset of the
features of openat(). It is documented separately, in openat2(2).
返り値
open(), openat(), and creat() return the new file descriptor (a nonnegative integer), or
-1 if an error occurred (in which case, errno is set appropriately).
エラー
open(), openat(), creat() は以下のエラーで失敗する。
EACCES ファイルに対する要求されたアクセスが許されていないか、 pathname のディレクトリ部分
の何れかのディレクトリに検索許可がなかった。 またはファイルが存在せず、親ディレクト
リへの書き込み許可がなかった。 (path_resolution(7) も参照すること。)
EACCES Where O_CREAT is specified, the protected_fifos or protected_regular sysctl is
enabled, the file already exists and is a FIFO or regular file, the owner of the
file is neither the current user nor the owner of the containing directory, and the
containing directory is both world- or group-writable and sticky. For details, see
the descriptions of /proc/sys/fs/protected_fifos and /proc/sys/fs/protected_regular
in proc(5).
EBUSY O_EXCL was specified in flags and pathname refers to a block device that is in use
by the system (e.g., it is mounted).
EDQUOT O_CREAT が指定された場合で、そのファイルが存在せず、ディスクブロックか inode がその
ファイルシステムのユーザークォータに達していた。
EEXIST pathname は既に存在し、 O_CREAT と O_EXCL が使用された。
EFAULT pathname がアクセス可能なアドレス空間の外を指している。
EFBIG EOVERFLOW 参照。
EINTR 遅いデバイス (例えば FIFO、 fifo(7) 参照) のオープンが完了するのを待って停止してい
る間に システムコールがシグナルハンドラーにより割り込まれた。 signal(7) 参照。
EINVAL ファイルシステムが O_DIRECT フラグをサポートしていない。 詳細は注意を参照。
EINVAL flags に無効な値が入っている。
EINVAL flags に O_TMPFILE が指定されたが、 O_WRONLY も O_RDWR も指定されていなかった。
EINVAL O_CREAT was specified in flags and the final component ("basename") of the new
file's pathname is invalid (e.g., it contains characters not permitted by the
underlying filesystem).
EINVAL The final component ("basename") of pathname is invalid (e.g., it contains
characters not permitted by the underlying filesystem).
EISDIR pathname はディレクトリを参照しており、書き込み要求が含まれていた (つまり O_WRONLY
または O_RDWR が設定されている)。
EISDIR pathname が存在するディレクトリを参照していて、 O_TMPFILE および O_WRONLY と O_RDWR
の一方が flags に指定されていたが、 このカーネルバージョンでは O_TMPFILE 機能が提供
されていない。
ELOOP pathname を解決する際に遭遇したシンボリックリンクが多過ぎる。
ELOOP pathname がシンボリックリンクで、 flags に O_NOFOLLOW が指定されたが、 O_PATH が指
定されていなかった。
EMFILE The per-process limit on the number of open file descriptors has been reached (see
the description of RLIMIT_NOFILE in getrlimit(2)).
ENAMETOOLONG
pathname が長過ぎる。
ENFILE オープンされているファイルの総数がシステム全体の制限に達している。
ENODEV pathname がデバイススペシャルファイルを参照しており、対応するデバイスが存在しない。
(これは Linux カーネルのバグであり、この場合には ENXIO が返されるべきである)
ENOENT O_CREAT is not set and the named file does not exist.
ENOENT pathname の中のディレクトリ部分が存在しないか、壊れた (dangling) シンボリックリン
ク (symbolic link) である。
ENOENT pathname が存在しないディレクトリを参照していて、 O_TMPFILE および O_WRONLY と
O_RDWR の一方が flags に指定されていたが、 このカーネルバージョンでは O_TMPFILE 機
能が提供されていない。
ENOMEM The named file is a FIFO, but memory for the FIFO buffer can't be allocated because
the per-user hard limit on memory allocation for pipes has been reached and the
caller is not privileged; see pipe(7).
ENOMEM 十分なカーネルメモリーがない。
ENOSPC pathname を作成する必要があるが、 pathname を含んでいるデバイスに新しいファイルのた
めの空き容量がない。
ENOTDIR
pathname に含まれるディレクトリ部分のどれかが実際にはディレクトリでない。 または
O_DIRECTORY が指定されており、 pathname がディレクトリでない。
ENXIO O_NONBLOCK | O_WRONLY が設定されており、指定したファイルが FIFO で そのファイルを読
み込み用でオープンしている FIFO が存在しない。
ENXIO ファイルがデバイススペシャルファイルで、対応するデバイスが存在しない。
ENXIO The file is a UNIX domain socket.
EOPNOTSUPP
pathname を含んでいるファイルシステムが O_TMPFILE をサポートしていない。
EOVERFLOW
pathname が参照しているのが、大き過ぎてオープンできない通常のファイルである。 通
常、このエラーが発生するは、32 ビットプラットフォーム上で -D_FILE_OFFSET_BITS=64 を
指定せずにコンパイルされたアプリケーションが、ファイルサイズが (1<31)-1 バイトを超
えるファイルを開こうとした場合である。 上記の O_LARGEFILE も参照。 これは POSIX.1
で規定されているエラーである。 2.6.24 より前のカーネルでは、Linux はこの場合にエ
ラー EFBIG を返していた。
EPERM O_NOATIME フラグが指定されたが、呼び出し元の実効ユーザー ID が ファイルの所有者と一
致せず、かつ呼び出し元に特権がない。
EPERM 操作が file seal により禁止されている。 fcntl(2) 参照。
EROFS pathname が読み込み専用のファイルシステム上のファイルを参照しており、 書き込みアク
セスが要求された。
ETXTBSY
pathname が現在実行中の実行イメージを参照しており、書き込みが要求された。
ETXTBSY
pathname refers to a file that is currently in use as a swap file, and the O_TRUNC
flag was specified.
ETXTBSY
pathname refers to a file that is currently being read by the kernel (e.g., for
module/firmware loading), and write access was requested.
EWOULDBLOCK
O_NONBLOCK フラグが指定されたが、そのファイルには矛盾するリースが設定されていた
(fcntl(2) 参照)。
openat() では以下のエラーも発生する。
EBADF dirfd が有効なファイルディスクリプターではない。
ENOTDIR
pathname が相対パス名で、 dirfd がディレクトリ以外のファイルを参照しているファイル
ディスクリプターである。
バージョン
openat() はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョン
2.4 で glibc に追加された。
準拠
open(), creat() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
openat(): POSIX.1-2008.
openat2() は Linux 固有である。
フラグ O_DIRECT, O_NOATIME, O_PATH, O_TMPFILE は Linux 特有のものである。 これらのフラグの
定義を得るためには _GNU_SOURCE を定義しなければならない。
フラグ O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW は POSIX.1-2001 では規定されていないが、
POSIX.1-2008 では規定されている。 glibc 2.12 以降では、これらの定義を得るには、
_POSIX_C_SOURCE を 200809L 以上の値で定義するか、 _XOPEN_SOURCE を 700 以上の値で定義す
る。 glibc 2.11 以前では、 これらの定義を得るには _GNU_SOURCE を定義する。
feature_test_macros(7) に注意書きがあるように、 _POSIX_C_SOURCE, _XOPEN_SOURCE,
_GNU_SOURCE などの機能検査マクロはどのヘッダーファイルをインクルードするより前に定義しなけ
ればならない。
注意
Under Linux, the O_NONBLOCK flag is sometimes used in cases where one wants to open but
does not necessarily have the intention to read or write. For example, this may be used
to open a device in order to get a file descriptor for use with ioctl(2).
O_RDONLY | O_TRUNC の影響は未定義であり、その動作は実装によって異なる。 多くのシステムでは
ファイルは実際に切り詰められる。
open() はスペシャルファイルをオープンすることができるが、 creat() でスペシャルファイルを
作成できない点に注意すること。 代わりに mknod(2) を使用する。
ファイルが新しく作成されると、 ファイルの st_atime, st_ctime, st_mtime フィールド (それぞ
れ最終アクセス時刻、最終状態変更時刻、最終修正時刻である。 stat(2) 参照) が現在時刻に設定
される。 さらに親ディレクトリの st_ctime と st_mtime も現在時刻に設定される。 それ以外の場
合で、O_TRUNC フラグでファイルが修正されたときは、 ファイルの st_ctime と st_mtime フィー
ルドが現在時刻に設定される。
The files in the /proc/[pid]/fd directory show the open file descriptors of the process
with the PID pid. The files in the /proc/[pid]/fdinfo directory show even more
information about these file descriptors. See proc(5) for further details of both of
these directories.
The Linux header file <asm/fcntl.h> doesn't define O_ASYNC; the (BSD-derived) FASYNC
synonym is defined instead.
オープンファイル記述
オープンファイル記述という用語は POSIX で使用されている用語で、オープンされているファイル
のシステム共通のテーブルのエントリーを参照するものである。 別の文脈では、このオブジェクト
はいろいろな呼び方があり、 「オープンファイルオブジェクト」、「ファイルハンドル」、「オー
プンファイルテーブルエントリー」、 カーネル開発者の用語では struct file などと呼ばれる。
ファイルディスクリプターが (dup(2) や同様のシステムコールを使って) 複製される際に、 複製さ
れたファイルディスクリプターは元のファイルディスクリプターと同じオープンファイル記述を参照
する。 結果として 2 つのファイルディスクリプターはファイルオフセットとファイル状態フラグを
共有する。 このような共有はプロセス間でも起こり得る。 fork(2) で作成された子プロセスは親プ
ロセスのファイルディスクリプターの複製を継承し、これらの複製は同じオープンファイル記述を参
照する。
1 つのファイルに対して open() を行う毎に、新しいオープンファイル記述が作成される。 した
がって、 1 つのファイル inode に対して複数のオープンファイル記述が存在することがありえる。
On Linux, one can use the kcmp(2) KCMP_FILE operation to test whether two file
descriptors (in the same process or in two different processes) refer to the same open
file description.
同期 I/O
POSIX.1-2008 の「同期 I/O」の選択肢として複数種類が規定されており、 動作を制御するために
open() フラグとして O_SYNC, O_DSYNC, O_RSYNC が規定されている。 この選択肢を実装がサポート
しているかに関わらず、 各実装では少なくとも通常のファイルに対して O_SYNC が利用できなけれ
ばならない。
Linux implements O_SYNC and O_DSYNC, but not O_RSYNC. Somewhat incorrectly, glibc defines
O_RSYNC to have the same value as O_SYNC. (O_RSYNC is defined in the Linux header file
<asm/fcntl.h> on HP PA-RISC, but it is not used.)
O_SYNC は、 同期 I/O でのファイル完全性完了を提供する。 つまり、 書き込み操作はデータとす
べての関連メタデータを裏で利用されているハードウェアにフラッシュすることを意味する。
O_DSYNC は、 同期 I/O でのデータ完全性完了を提供する。 つまり、 書き込み操作はデータを裏で
利用されているハードウェアにフラッシュするが、 それ以降の読み出し操作が正常に完了するのに
必要なメタデータの更新のみをフラッシュする。 データ完全性完了は、 ファイル完全性完了を必要
としないアプリケーションで、 ディスク操作の数を減らすことができる。
2 種類の完了の違いを理解するために、 ファイルメタデータの 2 つの要素、 ファイルの最終修正
時刻 (st_mtime) とファイル長、を考える。 すべての書き込み操作は最終修正時刻を更新するが、
ファイルの末尾にデータを追加する書き込み操作のみがファイル長を変更する。 最終修正時刻は、
読み出しが正常に完了するのに必要ではないが、 ファイル長は必要である。 したがって、 O_DSYNC
はファイル長のメタデータの更新がフラッシュされることだけを保証する (これに対して O_SYNC で
は最終修正時刻のメタデータも常にフラッシュされる)。
Linux 2.6.33 より前では、 Linux は open() では O_SYNC フラグのみを実装していた。 しかしな
がら、 このフラグが指定された場合、 ほとんどのファイルシステムで提供されていたのは実際には
同期 I/O でのデータ完全性完了と等価なものであった (つまり、 O_SYNC は実際には O_DSYNC と等
価なものとして実装されていた)。
Linux 2.6.33 以降では、 正しい O_SYNC のサポートが提供されている。しかしながら、バイナリレ
ベルの後方互換性を保証するため、 O_DSYNC は以前の O_SYNC と同じ値で定義されており、 O_SYNC
は O_DSYNC フラグの値を含む新しい (2 ビットの) フラグ値として定義されている。これによ
り、新しいヘッダーを使ってコンパイルされたアプリケーションで、 2.6.33 より前のカーネルで少
なくとも O_DSYNC の動作は同じになることが保証される。
C ライブラリとカーネルの違い
Since version 2.26, the glibc wrapper function for open() employs the openat() system
call, rather than the kernel's open() system call. For certain architectures, this is
also true in glibc versions before 2.26.
NFS
NFS を実現しているプロトコルには多くの不備があり、特に O_SYNC と O_NDELAY に影響する。
UID マッピングを使用している NFS ファイルシステムでは、 open() がファイルディスクリプター
を返した場合でも read(2) が EACCES で拒否される場合がある。 これはクライアントがアクセス許
可のチェックを行って open() を実行するが、読み込みや書き込みの際には サーバーで UID マッピ
ングが行われるためである。
FIFOs
Opening the read or write end of a FIFO blocks until the other end is also opened (by
another process or thread). See fifo(7) for further details.
ファイルアクセスモード
「アクセスモード」の値 O_RDONLY, O_WRONLY, O_RDWR は、 flags に指定できる他の値と違
い、個々のビットを指定するものではなく、 これらの値は flags の下位 2 ビットを定義する。
O_RDONLY, O_WRONLY, O_RDWR はそれぞれ 0, 1, 2 に定義されている。 言い換えると、 O_RDONLY |
O_WRONLY の組み合わせは論理的に間違いであり、確かに O_RDWR と同じ意味ではない。
Linux では、特別な、非標準なアクセスモードとして 3 (バイナリでは 11) が 予約されており
flags に指定できる。 このアクセスモードを指定すると、ファイルの読み出し/書き込み許可を
チェックし、 読み出しにも書き込みにも使用できないファイルディスクリプターを返す。 この非標
準のアクセスモードはいくつかの Linux ドライバで、デバイス固有の ioctl(2) 操作にのみ使用さ
れるファイルディスクリプターを返すために使われている。
openat() や他のディレクトリファイルディスクリプター API の基本原理
openat() and the other system calls and library functions that take a directory file
descriptor argument (i.e., execveat(2), faccessat(2), fanotify_mark(2), fchmodat(2),
fchownat(2), fspick(2), fstatat(2), futimesat(2), linkat(2), mkdirat(2), move_mount(2),
mknodat(2), name_to_handle_at(2), open_tree(2), openat2(2), readlinkat(2), renameat(2),
statx(2), symlinkat(2), unlinkat(2), utimensat(2), mkfifoat(3), and scandirat(3)) address
two problems with the older interfaces that preceded them. Here, the explanation is in
terms of the openat() call, but the rationale is analogous for the other interfaces.
First, openat() allows an application to avoid race conditions that could occur when
using open() to open files in directories other than the current working directory.
These race conditions result from the fact that some component of the directory prefix
given to open() could be changed in parallel with the call to open(). Suppose, for
example, that we wish to create the file dir1/dir2/xxx.dep if the file dir1/dir2/xxx
exists. The problem is that between the existence check and the file-creation step, dir1
or dir2 (which might be symbolic links) could be modified to point to a different
location. Such races can be avoided by opening a file descriptor for the target
directory, and then specifying that file descriptor as the dirfd argument of (say)
fstatat(2) and openat(). The use of the dirfd file descriptor also has other benefits:
* the file descriptor is a stable reference to the directory, even if the directory is
renamed; and
* the open file descriptor prevents the underlying filesystem from being dismounted, just
as when a process has a current working directory on a filesystem.
二つ目として、 openat() を使うと、アプリケーションが管理するファイルディスクリプターによ
り、 スレッド単位の「カレントワーキングディレクトリ」を実装することができる (この機能は、
/proc/self/fd/dirfd を使った方法でも実現することができるが、 効率の面で落とる)。
The dirfd argument for these APIs can be obtained by using open() or openat() to open a
directory (with either the O_RDONLY or the O_PATH flag). Alternatively, such a file
descriptor can be obtained by applying dirfd(3) to a directory stream created using
opendir(3).
When these APIs are given a dirfd argument of AT_FDCWD or the specified pathname is
absolute, then they handle their pathname argument in the same way as the corresponding
conventional APIs. However, in this case, several of the APIs have a flags argument that
provides access to functionality that is not available with the corresponding conventional
APIs.
O_DIRECT
O_DIRECT フラグを使用する場合、ユーザー空間バッファーの長さやアドレス、 I/O のファイルオフ
セットに関してアラインメントの制限が課されることがある。 Linux では、アラインメントの制限
はファイルシステムやカーネルのバージョンに よって異なり、全く制限が存在しない場合もある。
しかしながら、現在のところ、指定されたファイルやファイルシステムに対して こうした制限があ
るかを見つけるための、アプリケーション向けのインターフェースで ファイルシステム非依存のも
のは存在しない。 いくつかのファイルシステムでは、制限を確認するための独自のインターフェー
スが 提供されている。例えば、 xfsctl(3) の XFS_IOC_DIOINFO 命令である。
Linux 2.4 では、転送サイズ、 ユーザーバッファーのアライメント、ファイルオフセットは、 ファ
イルシステムの論理ブロックサイズの倍数でなければならない。 Linux 2.6.0 以降では、 内部で使
われるストレージの論理ブロックサイズのアライメント (通常は 512 バイト) で十分である。 論理
ブロックサイズは ioctl(2) BLKSSZGET 操作や以下のシェルコマンドから知ることができる。
blockdev --getss
メモリーバッファーがプライベートマッピング (mmap(2) の MAP_PRIVATE フラグで作成されたマッ
ピング) の場合には、O_DIRECT I/O は fork(2) システムコールと同時に決して実行すべきではない
(プライベートマッピングには、ヒープ領域に割り当てられたメモリーや静的に 割り当てたバッ
ファーも含まれる)。非同期 I/O インターフェース (AIO) 経由 やプロセス内の他のスレッドから発
行された、このような I/O は、 fork(2) が呼び出される前に完了されるべきである。 そうしな
かった場合、データ破壊や、親プロセスや子プロセスでの予期しない 動作が起こる可能性がある。
O_DIRECT I/O 用のメモリーバッファーが shmat(2) やMAP_SHARED フラグ 付きの mmap(2) で作成さ
れた場合には、この制限はあてはまらない。 madvise(2) でメモリーバッファーにアドバイス
MADV_DONTFORK が設定され ている場合にも、この制限はあてはまらない(MADV_DONTFORK はそのメモ
リー バッファーが fork(2) 後に子プロセスからは利用できないことを保証するも のである)。
O_DIRECT フラグは SGI IRIX で導入された。SGI IRIX にも Linux 2.4 と同様の (ユーザーバッ
ファーの) アラインメントの制限がある。 また、IRIX には適切な配置とサイズを取得するための
fcntl(2) コールがある。 FreeBSD 4.x も同じ名前のフラグを導入したが、アラインメントの制限
はない。
O_DIRECT support was added under Linux in kernel version 2.4.10. Older Linux kernels
simply ignore this flag. Some filesystems may not implement the flag, in which case
open() fails with the error EINVAL if it is used.
アプリケーションは、同じファイル、 特に同じファイルの重複するバイト領域に対して、 O_DIRECT
と通常の I/O を混ぜて使うのは避けるべきである。 ファイルシステムがこのような状況において一
貫性の問題を正しく 扱うことができる場合であっても、全体の I/O スループットは どちらか一方
を使用するときと比べて低速になるであろう。 同様に、アプリケーションは、同じファイルに対し
て mmap(2) と直接 I/O (O_DIRECT) を混ぜて使うのも避けるべきである。
NFS で O_DIRECT を使った場合の動作はローカルのファイルシステムの場合と違う。 古いカーネル
や、ある種の設定でコンパイルされたカーネルは、 O_DIRECT と NFS の組み合わせをサポートして
いないかもしれない。 NFS プロトコル自体はサーバにフラグを渡す機能は持っていないので、
O_DIRECT I/O はクライアント上のページキャッシュをバイパスするだけになり、 サーバは I/O を
キャッシュしているかもしれない。 クライアントは、 O_DIRECT の同期機構を保持するため、サー
バに対して I/O を同期して行うように依頼する。 サーバによっては、こうした状況下、特に I/O
サイズが小さい場合に 性能が大きく劣化する。 また、サーバによっては、I/O が安定したストレー
ジにまで行われたと、 クライアントに対して嘘をつくものもある。 これは、サーバの電源故障が起
こった際にデータの完全性が保たれない 危険は少しあるが、性能面での不利な条件を回避するため
に行われている。 Linux の NFS クライアントでは O_DIRECT I/O でのアラインメントの制限はな
い。
まとめると、 O_DIRECT は、注意して使うべきであるが、強力なツールとなる可能性を持っている。
アプリケーションは O_DIRECT をデフォルトでは無効になっている性能向上のためのオプションと
考えておくのがよいであろう。
バグ
現在のところ、 open() の呼び出し時に O_ASYNC を指定してシグナル駆動 I/O を有効にすること
はできない。 このフラグを有効にするには fcntl(2) を使用すること。
カーネルが O_TMPFILE 機能をサポートしているかを判定する際に、 EISDIR と ENOENT の 2 つのエ
ラーコードをチェックしなければならない。
When both O_CREAT and O_DIRECTORY are specified in flags and the file specified by
pathname does not exist, open() will create a regular file (i.e., O_DIRECTORY is
ignored).
関連項目
chmod(2), chown(2), close(2), dup(2), fcntl(2), link(2), lseek(2), mknod(2), mmap(2),
mount(2), open_by_handle_at(2), openat2(2), read(2), socket(2), stat(2), umask(2),
unlink(2), write(2), fopen(3), acl(5), fifo(7), inode(7), path_resolution(7), symlink(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。