.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
.\" and Copyright (C) 2008 Greg Banks
.\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1994-08-21 by Michael Haardt
.\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 1996-05-13 by Thomas Koenig
.\" Modified 1996-12-20 by Michael Haardt
.\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk>
.\" Modified 1999-06-03 by Michael Haardt
.\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" 2004-12-08, mtk, reordered flags list alphabetically
.\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
.\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
.\" 2008-01-03, mtk, with input from Trond Myklebust
.\"     <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
.\"     Rewrite description of O_EXCL.
.\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
.\"     on O_DIRECT.
.\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
.\"
.\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
.\" O_TTYINIT.  Eventually these may need to be documented.  --mtk
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1997-1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated 1999-08-14, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated 2001-05-25, Yuichi SATO <ysato444@yahoo.co.jp>
.\" Updated & Modified 2002-01-02, Yuichi SATO
.\" Updated & Modified 2002-07-07, Yuichi SATO
.\" Updated & Modified 2002-09-19, Yuichi SATO
.\" Updated & Modified 2003-07-30, Yuichi SATO
.\" Updated & Modified 2003-11-27, Yuichi SATO
.\" Updated & Modified 2005-01-01, Yuichi SATO
.\" Updated & Modified 2005-09-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated & Modified 2005-10-14, Akihiro MOTOKI
.\" Updated & Modified 2006-01-18, Akihiro MOTOKI
.\" Updated & Modified 2006-04-15, Akihiro MOTOKI, LDP v2.29
.\" Updated 2007-01-07, Akihiro MOTOKI, LDP v2.43
.\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
.\" Updated 2007-10-12, Akihiro MOTOKI, LDP v2.66
.\" Updated 2008-02-12, Akihiro MOTOKI, LDP v2.77
.\" Updated 2008-04-04, Akihiro MOTOKI, LDP v2.79
.\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05
.\" Updated 2010-04-23, Akihiro MOTOKI, LDP v3.24
.\" Updated 2012-05-08, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2012-05-30, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-08-16, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH OPEN 2 2020\-11\-01 Linux "Linux Programmer's Manual"
.SH 名前
open, openat, creat \- ファイルのオープン、作成を行う
.SH 書式
.nf
\fB#include <sys/types.h>\fP
\fB#include <sys/stat.h>\fP
\fB#include <fcntl.h>\fP
.PP
\fBint open(const char *\fP\fIpathname\fP\fB, int \fP\fIflags\fP\fB);\fP
\fBint open(const char *\fP\fIpathname\fP\fB, int \fP\fIflags\fP\fB, mode_t \fP\fImode\fP\fB);\fP
.PP
\fBint creat(const char *\fP\fIpathname\fP\fB, mode_t \fP\fImode\fP\fB);\fP
.PP
\fBint openat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB, int \fP\fIflags\fP\fB);\fP
\fBint openat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB, int \fP\fIflags\fP\fB, mode_t \fP\fImode\fP\fB);\fP
.PP
/* Documented separately, in \fBopenat2\fP(2): */
\fBint openat2(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB,\fP
\fB            const struct open_how *\fP\fIhow\fP\fB, size_t \fP\fIsize\fP\fB);\fP
.fi
.PP
.RS -4
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.RE
.PP
\fBopenat\fP():
.PD 0
.ad l
.RS 4
.TP  4
glibc 2.10 以降:
_POSIX_C_SOURCE\ >=\ 200809L
.TP 
glibc 2.10 より前:
_ATFILE_SOURCE
.RE
.ad
.PD
.SH 説明
The \fBopen\fP()  system call opens the file specified by \fIpathname\fP.  If the
specified file does not exist, it may optionally (if \fBO_CREAT\fP is specified
in \fIflags\fP)  be created by \fBopen\fP().
.PP
The return value of \fBopen\fP()  is a file descriptor, a small, nonnegative
integer that is used in subsequent system calls (\fBread\fP(2), \fBwrite\fP(2),
\fBlseek\fP(2), \fBfcntl\fP(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.
.PP
デフォルトでは、新しいファイルディスクリプターは \fBexecve\fP(2) を実行した後も
オープンされたままとなる (つまり、 \fBfcntl\fP(2) に説明がある \fBFD_CLOEXEC\fP
ファイルディスクリプターフラグは最初は無効である); 後述の \fBO_CLOEXEC\fP フラグ
を使うとこのデフォルトを変更することができる。 ファイルオフセット
(file offset) はファイルの先頭に設定される (\fBlseek\fP(2) 参照)。
.PP
\fBopen\fP()  を呼び出すと、「オープンファイル記述」 \fI(open file description)\fP
が作成される。ファイル記述とは、システム全体のオープン中のファイルのテーブルのエントリーである。
このオープンファイル記述は、ファイルオフセットとファイル状態フラグ (下記参照) が保持する。
ファイルディスクリプターはオープンファイルっ記述への参照である。 この後で \fIpathname\fP
が削除されたり、他のファイルを参照するように変更されたりしても、 この参照は影響を受けない。 オープンファイル記述の詳細な説明は「注意」の節を参照。
.PP
引数 \fIflags\fP には、アクセスモード \fBO_RDONLY\fP, \fBO_WRONLY\fP, \fBO_RDWR\fP
のどれかひとつが入っていなければならない。 これらはそれぞれ読み込み専用、書き込み専用、読み書き用に ファイルをオープンすることを要求するものである。
.PP
.\" SUSv4 divides the flags into:
.\" * Access mode
.\" * File creation
.\" * File status
.\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
.\" though it's not clear what the difference between "other" and
.\" "File creation" flags is.  I raised an Aardvark to see if this
.\" can be clarified in SUSv4; 10 Oct 2008.
.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
.\" TC1 (balloted in 2013), resolved this, so that those three constants
.\" are also categorized" as file status flags.
.\"
In addition, zero or more file creation flags and file status flags can be
bitwise\-\fIor\fP'd in \fIflags\fP.  The \fIfile creation flags\fP are \fBO_CLOEXEC\fP,
\fBO_CREAT\fP, \fBO_DIRECTORY\fP, \fBO_EXCL\fP, \fBO_NOCTTY\fP, \fBO_NOFOLLOW\fP,
\fBO_TMPFILE\fP, and \fBO_TRUNC\fP.  The \fIfile status flags\fP 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 \fBfcntl\fP(2)  for details.
.PP
すべてのファイル作成フラグとファイル状態フラグを以下のリストに示す。
.TP 
\fBO_APPEND\fP
The file is opened in append mode.  Before each \fBwrite\fP(2), the file offset
is positioned at the end of the file, as if with \fBlseek\fP(2).  The
modification of the file offset and the write operation are performed as a
single atomic step.
.IP
.\" For more background, see
.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
.\" http://nfs.sourceforge.net/
\fBO_APPEND\fP 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.
.TP 
\fBO_ASYNC\fP
シグナル駆動 I/O (signal\-driven I/O) を有効にする: このファイルディスクリプターへの
入力または出力が可能になった場合に、シグナルを生成する (デフォルトは \fBSIGIO\fP であるが、 \fBfcntl\fP(2)
によって変更可能である)。 この機能が使用可能なのは端末、疑似端末、ソケットのみであり、 (Linux 2.6 以降では) パイプと FIFO
に対しても使用できる。 さらに詳しい説明は \fBfcntl\fP(2)  を参照すること。 下記の「バグ」も参照。
.TP 
\fBO_CLOEXEC\fP (Linux 2.6.23 以降)
.\" NOTE! several other man pages refer to this text
.\" FIXME . for later review when Issue 8 is one day released...
.\" POSIX proposes to fix many APIs that provide hidden FDs
.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
.\" http://austingroupbugs.net/view.php?id=368
新しいファイルディスクリプターに対して close\-on\-exec フラグを有効にする。 このフラグを指定することで、 プログラムは
\fBFD_CLOEXEC\fP フラグをセットするために \fBfcntl\fP(2) \fBF_SETFD\fP 操作を別途呼び出す必要がなくなる。
.IP
.\" This flag fixes only one form of the race condition;
.\" The race can also occur with, for example, file descriptors
.\" returned by accept(), pipe(), etc.
ある種のマルチスレッドのプログラムはこのフラグの使用は不可欠である点に注意すること。 なぜなら、個別に \fBFD_CLOEXEC\fP フラグを設定する
\fBfcntl\fP(2) \fBF_SETFD\fP 操作を呼び出したとしても、あるスレッドがファイルディスクリプターを オープンするのと同時に別のスレッドが
\fBfork\fP(2) と \fBexecve\fP(2) を実行するという競合条件を避けるのには十分ではないからである。
実行の順序に依存して、この競合条件の結果、 \fBopen\fP() が返したファイルディスクリプターが \fBfork\fP(2)
で作成された子プロセスにより実行されるプログラムに意図せず見えてしまう可能性がある。 (この種の競合は、 本質的に、 close\-on\-exec
フラグをセットすべきファイルディスクリプターを作成するどのシステムコールでも起こり得るものであり、 他のいろいろな Linux
システムコールでこの問題に対処するために \fBO_CLOEXEC\fP と同等の機能が提供されている。)
.TP 
\fBO_CREAT\fP
If \fIpathname\fP does not exist, create it as a regular file.
.IP
The owner (user ID) of the new file is set to the effective user ID of the
process.
.IP
.\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
.\" XFS (since 2.6.14).
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 \fIbsdgroups\fP and
\fIsysvgroups\fP mount options described in \fBmount\fP(8).
.IP
The \fImode\fP argument specifies the file mode bits to be applied when a new
file is created.  If neither \fBO_CREAT\fP nor \fBO_TMPFILE\fP is specified in
\fIflags\fP, then \fImode\fP is ignored (and can thus be specified as 0, or simply
omitted).  The \fImode\fP argument \fBmust\fP be supplied if \fBO_CREAT\fP or
\fBO_TMPFILE\fP is specified in \fIflags\fP; if it is not supplied, some arbitrary
bytes from the stack will be applied as the file mode.
.IP
The effective mode is modified by the process's \fIumask\fP in the usual way:
in the absence of a default ACL, the mode of the created file is \fI(mode\ &\ \(tiumask)\fP.
.IP
Note that \fImode\fP applies only to future accesses of the newly created file;
the \fBopen\fP()  call that creates a read\-only file may well return a
read/write file descriptor.
.IP
\fImode\fP のために以下のシンボル定数が提供されている :
.RS
.TP  9
\fBS_IRWXU\fP
00700 ユーザー (ファイルの所有者) に読み込み、書き込み、 実行の許可がある。
.TP 
\fBS_IRUSR\fP
00400 ユーザーに読み込みの許可がある。
.TP 
\fBS_IWUSR\fP
00200 ユーザーに書き込みの許可がある。
.TP 
\fBS_IXUSR\fP
00100 ユーザーに実行の許可がある。
.TP 
\fBS_IRWXG\fP
00070 グループに読み込み、書き込み、実行の許可がある。
.TP 
\fBS_IRGRP\fP
00040 グループに読み込みの許可がある。
.TP 
\fBS_IWGRP\fP
00020 グループに書き込みの許可がある。
.TP 
\fBS_IXGRP\fP
00010 グループに実行の許可がある。
.TP 
\fBS_IRWXO\fP
00007 他人 (others) に読み込み、書き込み、実行の許可がある。
.TP 
\fBS_IROTH\fP
00004 他人に読み込みの許可がある。
.TP 
\fBS_IWOTH\fP
00002 他人に書き込みの許可がある。
.TP 
\fBS_IXOTH\fP
00001 他人に実行の許可がある。
.RE
.IP
According to POSIX, the effect when other bits are set in \fImode\fP is
unspecified.  On Linux, the following bits are also honored in \fImode\fP:
.RS
.TP  9
\fBS_ISUID\fP
0004000 set\-user\-ID bit
.TP 
\fBS_ISGID\fP
0002000 set\-group\-ID bit (see \fBinode\fP(7)).
.TP 
\fBS_ISVTX\fP
0001000 sticky bit (see \fBinode\fP(7)).
.RE
.TP 
\fBO_DIRECT\fP (Linux 2.4.10 以降)
このファイルに対する I/O のキャッシュの効果を最小化しようとする。このフラグを使うと、一般的に性能が低下する。
しかしアプリケーションが独自にキャッシングを行っているような 特別な場合には役に立つ。 ファイルの I/O
はユーザー空間バッファーに対して直接行われる。 \fBO_DIRECT\fP フラグ自身はデータを同期で転送しようとはするが、 \fBO_SYNC\fP
フラグのようにデータと必要なメタデータの転送が保証されるわけではない。同期 I/O を保証するためには、 \fBO_DIRECT\fP に加えて
\fBO_SYNC\fP を使用しなければならない。下記の「注意」の節の議論も参照。
.IP
ブロックデバイスに対する似通った意味のインターフェースが \fBraw\fP(8)  で説明されている (但し、このインターフェースは非推奨である)。
.TP 
\fBO_DIRECTORY\fP
.\" But see the following and its replies:
.\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
.\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
.\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
\fIpathname\fP がディレクトリでなければオープンは失敗する。 このフラグは、 \fBopendir\fP(3)  が FIFO
やテープデバイスに対してコールされた場合の サービス不能 (denial\-of\-service) 攻撃を避けるために カーネル 2.1.126
で追加された。
.TP 
\fBO_DSYNC\fP
ファイルに対する書き込み操作は、同期 I/O の\fIデータ\fP完全性完了の要件に基づいて行われる。
.IP
\fBwrite\fP(2) (や同様のコール) が返るまでに、
書き込まれたデータおよびデータを取得するのに必要なファイルメタデータが裏で利用されているハードウェアに転送される (つまり、\fBwrite\fP(2)
の後に \fBfdatasync\fP(2) を呼び出したのと同じようになる)。 \fI下記の「注意」も参照のこと\fP。
.TP 
\fBO_EXCL\fP
この呼び出しでファイルが作成されることを保証する。このフラグが \fBO_CREAT\fP と一緒に指定され、 \fIpathname\fP
のファイルが既に存在した場合、 \fBopen\fP() は \fBEEXIST\fP エラーで失敗する。
.IP
.\" POSIX.1-2001 explicitly requires this behavior.
これら二つのフラグが指定された際、シンボリックリンクは辿られない。 \fIpathname\fP がシンボリックリンクの場合、
シンボリックリンクがどこを指しているかに関わらず \fBopen\fP()  は失敗する。
.IP
一般的には、 \fBO_CREAT\fP を指定せずに \fBO_EXCL\fP を使用した場合の
\fBO_EXCL\fP の動作は規定されていない。
これには一つ例外があり、Linux 2.6 以降では、
\fIpathname\fP がブロックデバイスを参照している場合、
\fBO_CREAT\fP なしで \fBO_EXCL\fP を使用することができる。
システムがそのブロックデバイスを使用中の場合 (例えば、
マウントされているなど)、 \fBopen\fP() はエラー \fBEBUSY\fP で失敗する。
.IP
NFS では、 \fBO_EXCL\fP は、Linux 2.6 以降で NFSv3 以降を使っている場合でのみサポートされる。 \fBO_EXCL\fP
サポートが提供されていない NFS 環境では、このフラグに頼って ロック処理を実行するプログラムは競合状態 (race condition) に出会う
可能性がある。 ロックファイルを使用して不可分 (atomic) なファイルロックを実現し、 NFS が \fBO_EXCL\fP
をサポートしているかに依存しないようにしたい場合、 移植性のある方法は、同じファイルシステム上に他と名前の重ならない ファイル (例えばホスト名と
PID を組み合わせた名前) を作成し、 \fBlink\fP(2)  を使用してそのロックファイルへのリンクを作成することである。 \fBlink\fP(2)
コールの返り値が 0 ならばロックに成功している。 あるいは、そのファイルに \fBstat\fP(2)  を使用してリンク数 (link count) が
2 になっているかをチェックする。 そうなっていれば、同じくロックに成功しているということである。
.TP 
\fBO_LARGEFILE\fP
(LFS) \fIoff_t\fP ではサイズを表せない (だだし \fIoff64_t\fP ではサイズを表せる)ファ
イルをオープン可能にする。この定義を有効にするためには、(\fIどの\fPヘッダーファイ
ルをインクルードするよりも前に) \fB_LARGEFILE64_SOURCE\fP マクロを定義しなければ
ならない。
32 ビットシステムにおいて大きなファイルにアクセスしたい場合、
(\fBO_LARGEFILE\fP を使うよりも) \fB_FILE_OFFSET_BITS\fP 機能検査マクロを 64 に
セットする方が望ましい方法である (\fBfeature_test_macros\fP(7) を参照)。
.TP 
\fBO_NOATIME\fP (Linux 2.6.8 以降)
Do not update the file last access time (\fIst_atime\fP in the inode)  when the
file is \fBread\fP(2).
.IP
This flag can be employed only if one of the following conditions is true:
.RS
.IP * 3
.\" Strictly speaking: the filesystem UID
The effective UID of the process matches the owner UID of the file.
.IP *
The calling process has the \fBCAP_FOWNER\fP capability in its user namespace
and the owner UID of the file has a mapping in the namespace.
.RE
.IP
.\" The O_NOATIME flag also affects the treatment of st_atime
.\" by mmap() and readdir(2), MTK, Dec 04.
このフラグはインデックス作成やバックアッププログラムで使うことを意図している。 これを使うとディスクに対する操作を大幅に減らすことができる。
このフラグは全てのファイルシステムに対して有効であるわけではない。 その一例が NFS であり、サーバがアクセス時刻を管理している。
.TP 
\fBO_NOCTTY\fP
\fIpathname\fP が端末 (terminal) デバイス \(em \fBtty\fP(4) 参照 \(em を指している
場合に、たとえそのプロセスが制御端末を持っていなくても、オープンしたファイル
は制御端末にはならない。
.TP 
\fBO_NOFOLLOW\fP
If the trailing component (i.e., basename) of \fIpathname\fP is a symbolic
link, then the open fails, with the error \fBELOOP\fP.  Symbolic links in
earlier components of the pathname will still be followed.  (Note that the
\fBELOOP\fP 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.)
.IP
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.
.IP
.\" The headers from glibc 2.0.100 and later include a
.\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
.\" used\fP.
See also \fBO_PATH\fP below.
.TP 
\fBO_NONBLOCK\fP または \fBO_NDELAY\fP
可能ならば、ファイルは非停止 (nonblocking) モードでオープンされる。 \fBopen\fP()
も、返したファイルディスクリプターに対する以後のすべての操作も呼び出したプロセスを待たせることはない。
.IP
Note that the setting of this flag has no effect on the operation of
\fBpoll\fP(2), \fBselect\fP(2), \fBepoll\fP(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
\fBO_NONBLOCK\fP flag \fIclear\fP would not block.
.IP
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 \fBO_NONBLOCK\fP is set.  Since \fBO_NONBLOCK\fP semantics
might eventually be implemented, applications should not depend upon
blocking behavior when specifying this flag for regular files and block
devices.
.IP
FIFO (名前付きパイプ) を扱う場合には \fBfifo\fP(7) も参照すること。 強制ファイルロック (mandatory file lock)
やファイルリース (file lease) と組み合わせた場合の、 \fBO_NONBLOCK\fP の効果についての議論は、 \fBfcntl\fP(2)
を参照すること。
.TP 
\fBO_PATH\fP (Linux 2.6.39 以降)
.\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
.\" commit 326be7b484843988afe57566b627fb7a70beac56
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
.\"
.\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
.\"	Subject: Re: [PATCH] open(2): document O_PATH
.\"	Newsgroups: gmane.linux.man, gmane.linux.kernel
.\"
このフラグを指定して取得したファイルディスクリプターは、 ファイルシステムツリー内での場所を示すため、
純粋にファイルディスクリプターレベルでの作用する操作を実行するため、 の二つの目的で使用することができる。 ファイル自身はオープンされず、
他のファイル操作 (例えば \fBread\fP(2), \fBwrite\fP(2), \fBfchmod\fP(2), \fBfchown\fP(2),
\fBfgetxattr\fP(2), \fBioctl\fP(2), \fBmmap\fP(2)) はエラー \fBEBADF\fP で失敗する。
.IP
取得したファイルディスクリプターに対して以下の操作を行うことが「できる」。
.RS
.IP * 3
\fBclose\fP(2).
.IP *
.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
\fBfchdir\fP(2), if the file descriptor refers to a directory (since Linux
3.5).
.IP *
\fBfstat\fP(2) (Linux 3.6 以降).
.IP *
.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
\fBfstatfs\fP(2) (Linux 3.12 以降).
.IP *
ファイルディスクリプターの複製 (\fBdup\fP(2), \fBfcntl\fP(2)  \fBF_DUPFD\fP など)
.IP *
ファイルディスクリプターフラグの取得と設定 (\fBfcntl\fP(2) の \fBF_GETFD\fP と \fBF_SETFD\fP)
.IP *
\fBfcntl\fP(2) の \fBF_GETFL\fP 操作を使ったオープンされたファイルの状態フラグの取得。 返されるフラグには \fBO_PATH\fP
ビットが含まれる。
.IP *
\fBopenat\fP() や他の "*at()" 系のシステムコールの \fIdirfd\fP 引数としてそのファイルディスクリプターを渡す。 これには、
ファイルがディレクトリでない場合に \fBlinkat\fP(2) に \fBAT_EMPTY_PATH\fP が指定された場合 (や procfs 経由で
\fBAT_SYMLINK_FOLLOW\fP が使用された場合) を含む。
.IP *
そのファイルディスクリプターを別のプロセスに UNIX ドメインソケット経由で渡す。 (\fBunix\fP(7) の \fBSCM_RIGHTS\fP を参照)
.RE
.IP
\fIflags\fP に \fBO_PATH\fP が指定された場合、 \fBO_CLOEXEC\fP, \fBO_DIRECTORY\fP, \fBO_NOFOLLOW\fP
以外のフラグビットは無視される。
.IP
Opening a file or directory with the \fBO_PATH\fP 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., \fBfchdir\fP(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 \fBO_RDONLY\fP flag requires that the caller have read
permission on the object, even when the subsequent operation (e.g.,
\fBfchdir\fP(2), \fBfstat\fP(2))  does not require read permission on the object.
.IP
\fIpathname\fP がシンボリックリンクで \fBO_NOFOLLOW\fP フラグも合わせて指定された場合、
この呼び出しではシンボリックリンクを参照するファイルディスクリプターを返す。 このファイルディスクリプターは、 空のパス名を指定した
\fBfchownat\fP(2), \fBfstatat\fP(2), \fBlinkat\fP(2), \fBreadlinkat\fP(2) の呼び出しで
\fIdirfd\fP 引数として使うことで、 そのシンボリックリンクに対して操作を行うことができる。
.IP
If \fIpathname\fP 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.
\fBfstatfs\fP(2)  can then be used to determine if it is, in fact, an
untriggered automount point (\fB.f_type == AUTOFS_SUPER_MAGIC\fP).
.IP
One use of \fBO_PATH\fP for regular files is to provide the equivalent of
POSIX.1's \fBO_EXEC\fP 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:
.IP
.in +4n
.EX
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);
.EE
.in
.IP
An \fBO_PATH\fP file descriptor can also be passed as the argument of
\fBfexecve\fP(3).
.TP 
\fBO_SYNC\fP
ファイルに対する書き込み操作は、同期 I/O の\fIファイル\fP完全性完了の要件に基づいて行われる (これに対し \fBO_DSYNC\fP では同期 I/O
の\fIデータ\fP完全性完了が提供される)。
.IP
\fBwrite\fP(2) (や同様のコール) が返るまでに、 書き込まれたデータと関連するファイルメタデータが裏で利用されているハードウェアに転送される
(つまり、\fBwrite\fP(2) の後に \fBfsync\fP(2) を呼び出したのと同じようになる)。 \fI下記の「注意」も参照のこと\fP。
.TP 
\fBO_TMPFILE\fP (Linux 3.11 以降)
.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
名前なしの一時的な通常ファイルを作成する。 \fIpathname\fP 引数はディレクトリを指定する。 名前なしの inode
がそのディレクトリが存在するファイルシステムに作成される。 そのファイルに名前を付与しない限り、 作成されたファイルに書き込まれた内容は、
最後のファイルディスクリプターがクローズされる際に失われる。
.IP
\fBO_TMPFILE\fP は必ず \fBO_RDWR\fP か \fBO_WRONLY\fP のいずれかと一緒に使わなければならない。 \fBO_EXCL\fP
も指定することができる。 \fBO_EXCL\fP が指定されなかった場合、 \fBlinkat\fP(2)
を使って、そのファイルシステムにこの一時ファイルへのリンクを作成し、ファイルを永続化することができる。 以下のコードのようにすればよい。
.IP
.in +4n
.EX
char path[PATH_MAX];
fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
                        S_IRUSR | S_IWUSR);

/* \(aqfd\(aq に対するファイル I/O ... */

linkat(fd, NULL, AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);

/* If the caller doesn\(aqt 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);
*/
.EE
.in
.IP
この場合、 \fBopen\fP() の \fImode\fP 引数は \fBO_CREAT\fP と同様にファイルのアクセス許可モードの決定に使われる。
.IP
\fBO_TMPFILE\fP とともに \fBO_EXCL\fP を指定すると、
一時ファイルに対して上記の方法でファイルシステムへのリンクを行うことができなくなる (この場合の \fBO_EXCL\fP の意味は他の場合の
\fBO_EXCL\fP の意味とは異なる点に注意)。
.IP
.\" Inspired by http://lwn.net/Articles/559147/
\fBO_TMPFILE\fP には主に二つの用途がある。
.RS
.IP * 3
改善された \fBtmpfile\fP(3) の機能: (1) クローズ時に自動的に削除される、 (2) パス名では決して参照できない、 (3)
シンボリックリンク攻撃ができない、 (4) 呼び出し元が一意な名前を考える必要がない、 という特長を持つ競合のない一時ファイルの作成。
.IP *
最初は見えないファイルを作成し、 それからデータを書き込んだり、適切なファイルシステム属性を持つように調整したり (\fBfchown\fP(2),
\fBfchmod\fP(2), \fBfsetxattr\fP(2) など) した後、 準備が全て整った状態で (上述の \fBlinkat\fP(2) を使って)
ファイルシステム内にアトミックにリンクを行う。
.RE
.IP
.\" To check for support, grep for "tmpfile" in kernel sources
.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
.\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c
.\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c
\fBO_TMPFILE\fP 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)
.TP 
\fBO_TRUNC\fP
ファイルが既に存在し、通常ファイルであり、 アクセスモードで書き込みが許可されている (つまり、 \fBO_RDWR\fP または \fBO_WRONLY\fP
の) 場合、長さ 0 に切り詰め (truncate) られる。 ファイルが FIFO または端末デバイスファイルの場合、 \fBO_TRUNC\fP
フラグは無視される。 それ以外の場合、 \fBO_TRUNC\fP の効果は未定義である。
.SS creat()
\fBcreat\fP() の呼び出しは、 \fIflags\fP に \fBO_CREAT|O_WRONLY|O_TRUNC\fP を指定して \fBopen\fP()
を呼び出すのと等価である。
.SS openat()
\fBopenat\fP() システムコールは \fBopen\fP() と全く同様に動作するが、以下で説明する点が異なる。
.PP
\fIpathname\fP で指定されたパス名が相対パスの場合、このパス名はファイルディスクリプター \fIdirfd\fP
が参照するディレクトリに対する相対パスと解釈される (\fBopen\fP()
に相対パス名を渡した場合のように、呼び出したプロセスのカレントワーキングディレクトリに対する相対パスではない)。
.PP
\fIpathname\fP で指定されたパス名が相対パスで、 \fIdirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、 (\fBopen\fP()
と同様に) \fIpathname\fP は呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈される。
.PP
.\"
\fIpathname\fP で指定されたパス名が絶対パスの場合、 \fIdirfd\fP は無視される。
.SS openat2(2)
The \fBopenat2\fP(2)  system call is an extension of \fBopenat\fP(), and provides
a superset of the features of \fBopenat\fP().  It is documented separately, in
\fBopenat2\fP(2).
.SH 返り値
\fBopen\fP(), \fBopenat\fP(), and \fBcreat\fP()  return the new file descriptor (a
nonnegative integer), or \-1 if an error occurred (in which case, \fIerrno\fP is
set appropriately).
.SH エラー
\fBopen\fP(), \fBopenat\fP(), \fBcreat\fP() は以下のエラーで失敗する。
.TP 
\fBEACCES\fP
ファイルに対する要求されたアクセスが許されていないか、 \fIpathname\fP のディレクトリ部分の何れかのディレクトリに検索許可がなかった。
またはファイルが存在せず、親ディレクトリへの書き込み許可がなかった。 (\fBpath_resolution\fP(7)  も参照すること。)
.TP 
\fBEACCES\fP
.\" commit 30aba6656f61ed44cba445a3c0d38b296fa9e8f5
Where \fBO_CREAT\fP is specified, the \fIprotected_fifos\fP or
\fIprotected_regular\fP 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
\fI/proc/sys/fs/protected_fifos\fP and \fI/proc/sys/fs/protected_regular\fP in
\fBproc\fP(5).
.TP 
\fBEBUSY\fP
\fBO_EXCL\fP was specified in \fIflags\fP and \fIpathname\fP refers to a block device
that is in use by the system (e.g., it is mounted).
.TP 
\fBEDQUOT\fP
\fBO_CREAT\fP が指定された場合で、そのファイルが存在せず、ディスクブロックか inode がそのファイルシステムのユーザークォータに達していた。
.TP 
\fBEEXIST\fP
\fIpathname\fP は既に存在し、 \fBO_CREAT\fP と \fBO_EXCL\fP が使用された。
.TP 
\fBEFAULT\fP
\fIpathname\fP がアクセス可能なアドレス空間の外を指している。
.TP 
\fBEFBIG\fP
\fBEOVERFLOW\fP 参照。
.TP 
\fBEINTR\fP
遅いデバイス (例えば FIFO、 \fBfifo\fP(7)  参照) のオープンが完了するのを待って停止している間に
システムコールがシグナルハンドラーにより割り込まれた。 \fBsignal\fP(7)  参照。
.TP 
\fBEINVAL\fP
ファイルシステムが \fBO_DIRECT\fP フラグをサポートしていない。 詳細は\fB注意\fPを参照。
.TP 
\fBEINVAL\fP
.\" In particular, __O_TMPFILE instead of O_TMPFILE
\fIflags\fP に無効な値が入っている。
.TP 
\fBEINVAL\fP
\fIflags\fP に \fBO_TMPFILE\fP が指定されたが、 \fBO_WRONLY\fP も \fBO_RDWR\fP も指定されていなかった。
.TP 
\fBEINVAL\fP
\fBO_CREAT\fP was specified in \fIflags\fP and the final component ("basename") of
the new file's \fIpathname\fP is invalid (e.g., it contains characters not
permitted by the underlying filesystem).
.TP 
\fBEINVAL\fP
The final component ("basename") of \fIpathname\fP is invalid (e.g., it
contains characters not permitted by the underlying filesystem).
.TP 
\fBEISDIR\fP
\fIpathname\fP はディレクトリを参照しており、書き込み要求が含まれていた (つまり \fBO_WRONLY\fP または \fBO_RDWR\fP
が設定されている)。
.TP 
\fBEISDIR\fP
\fIpathname\fP が存在するディレクトリを参照していて、 \fBO_TMPFILE\fP および \fBO_WRONLY\fP と \fBO_RDWR\fP
の一方が \fIflags\fP に指定されていたが、 このカーネルバージョンでは \fBO_TMPFILE\fP 機能が提供されていない。
.TP 
\fBELOOP\fP
\fIpathname\fP を解決する際に遭遇したシンボリックリンクが多過ぎる。
.TP 
\fBELOOP\fP
\fIpathname\fP がシンボリックリンクで、 \fIflags\fP に \fBO_NOFOLLOW\fP が指定されたが、 \fBO_PATH\fP
が指定されていなかった。
.TP 
\fBEMFILE\fP
The per\-process limit on the number of open file descriptors has been
reached (see the description of \fBRLIMIT_NOFILE\fP in \fBgetrlimit\fP(2)).
.TP 
\fBENAMETOOLONG\fP
\fIpathname\fP が長過ぎる。
.TP 
\fBENFILE\fP
オープンされているファイルの総数がシステム全体の制限に達している。
.TP 
\fBENODEV\fP
\fIpathname\fP がデバイススペシャルファイルを参照しており、対応するデバイスが存在しない。 (これは Linux
カーネルのバグであり、この場合には \fBENXIO\fP が返されるべきである)
.TP 
\fBENOENT\fP
\fBO_CREAT\fP is not set and the named file does not exist.
.TP 
\fBENOENT\fP
\fIpathname\fP の中のディレクトリ部分が存在しないか、壊れた (dangling)  シンボリックリンク (symbolic link)
である。
.TP 
\fBENOENT\fP
\fIpathname\fP が存在しないディレクトリを参照していて、 \fBO_TMPFILE\fP および \fBO_WRONLY\fP と \fBO_RDWR\fP
の一方が \fIflags\fP に指定されていたが、 このカーネルバージョンでは \fBO_TMPFILE\fP 機能が提供されていない。
.TP 
\fBENOMEM\fP
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 \fBpipe\fP(7).
.TP 
\fBENOMEM\fP
十分なカーネルメモリーがない。
.TP 
\fBENOSPC\fP
\fIpathname\fP を作成する必要があるが、 \fIpathname\fP を含んでいるデバイスに新しいファイルのための空き容量がない。
.TP 
\fBENOTDIR\fP
\fIpathname\fP に含まれるディレクトリ部分のどれかが実際にはディレクトリでない。 または \fBO_DIRECTORY\fP が指定されており、
\fIpathname\fP がディレクトリでない。
.TP 
\fBENXIO\fP
\fBO_NONBLOCK\fP | \fBO_WRONLY\fP が設定されており、指定したファイルが FIFO で そのファイルを読み込み用でオープンしている
FIFO が存在しない。
.TP 
\fBENXIO\fP
ファイルがデバイススペシャルファイルで、対応するデバイスが存在しない。
.TP 
\fBENXIO\fP
The file is a UNIX domain socket.
.TP 
\fBEOPNOTSUPP\fP
\fIpathname\fP を含んでいるファイルシステムが \fBO_TMPFILE\fP をサポートしていない。
.TP 
\fBEOVERFLOW\fP
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
.\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
.\" Reported 2006-10-03
\fIpathname\fP が参照しているのが、大き過ぎてオープンできない通常のファイルである。 通常、このエラーが発生するは、32
ビットプラットフォーム上で \fI\-D_FILE_OFFSET_BITS=64\fP を指定せずにコンパイルされたアプリケーションが、ファイルサイズが
\fI(1<31)\-1\fP バイトを超えるファイルを開こうとした場合である。 上記の \fBO_LARGEFILE\fP も参照。 これは POSIX.1
で規定されているエラーである。 2.6.24 より前のカーネルでは、Linux はこの場合にエラー \fBEFBIG\fP を返していた。
.TP 
\fBEPERM\fP
.\" Strictly speaking, it's the filesystem UID... (MTK)
\fBO_NOATIME\fP フラグが指定されたが、呼び出し元の実効ユーザー ID が ファイルの所有者と一致せず、かつ呼び出し元に特権がない。
.TP 
\fBEPERM\fP
操作が file seal により禁止されている。 \fBfcntl\fP(2)  参照。
.TP 
\fBEROFS\fP
\fIpathname\fP が読み込み専用のファイルシステム上のファイルを参照しており、 書き込みアクセスが要求された。
.TP 
\fBETXTBSY\fP
\fIpathname\fP が現在実行中の実行イメージを参照しており、書き込みが要求された。
.TP 
\fBETXTBSY\fP
\fIpathname\fP refers to a file that is currently in use as a swap file, and
the \fBO_TRUNC\fP flag was specified.
.TP 
\fBETXTBSY\fP
\fIpathname\fP refers to a file that is currently being read by the kernel
(e.g., for module/firmware loading), and write access was requested.
.TP 
\fBEWOULDBLOCK\fP
\fBO_NONBLOCK\fP フラグが指定されたが、そのファイルには矛盾するリースが設定されていた (\fBfcntl\fP(2)  参照)。
.PP
\fBopenat\fP() では以下のエラーも発生する。
.TP 
\fBEBADF\fP
\fIdirfd\fP が有効なファイルディスクリプターではない。
.TP 
\fBENOTDIR\fP
\fIpathname\fP が相対パス名で、 \fIdirfd\fP がディレクトリ以外のファイルを参照しているファイルディスクリプターである。
.SH バージョン
\fBopenat\fP()  はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョン 2.4 で glibc
に追加された。
.SH 準拠
\fBopen\fP(), \fBcreat\fP()  SVr4, 4.3BSD, POSIX.1\-2001, POSIX.1\-2008.
.PP
\fBopenat\fP(): POSIX.1\-2008.
.PP
\fBopenat2\fP()  は Linux 固有である。
.PP
フラグ \fBO_DIRECT\fP, \fBO_NOATIME\fP, \fBO_PATH\fP, \fBO_TMPFILE\fP は Linux 特有のものである。
これらのフラグの定義を得るためには \fB_GNU_SOURCE\fP を定義しなければならない。
.PP
フラグ \fBO_CLOEXEC\fP, \fBO_DIRECTORY\fP, \fBO_NOFOLLOW\fP は POSIX.1\-2001 では規定されていないが、
POSIX.1\-2008 では規定されている。 glibc 2.12 以降では、これらの定義を得るには、 \fB_POSIX_C_SOURCE\fP を
200809L 以上の値で定義するか、 \fB_XOPEN_SOURCE\fP を 700 以上の値で定義する。 glibc 2.11 以前では、
これらの定義を得るには \fB_GNU_SOURCE\fP を定義する。
.PP
\fBfeature_test_macros\fP(7) に注意書きがあるように、 \fB_POSIX_C_SOURCE\fP, \fB_XOPEN_SOURCE\fP,
\fB_GNU_SOURCE\fP などの機能検査マクロは\fIどの\fPヘッダーファイルをインクルードするより前に定義しなければならない。
.SH 注意
Under Linux, the \fBO_NONBLOCK\fP 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 \fBioctl\fP(2).
.PP
.\" Linux 2.0, 2.5: truncate
.\" Solaris 5.7, 5.8: truncate
.\" Irix 6.5: truncate
.\" Tru64 5.1B: truncate
.\" HP-UX 11.22: truncate
.\" FreeBSD 4.7: truncate
\fBO_RDONLY | O_TRUNC\fP の影響は未定義であり、その動作は実装によって異なる。 多くのシステムではファイルは実際に切り詰められる。
.PP
\fBopen\fP()  はスペシャルファイルをオープンすることができるが、 \fBcreat\fP()  でスペシャルファイルを作成できない点に注意すること。
代わりに \fBmknod\fP(2)  を使用する。
.PP
ファイルが新しく作成されると、 ファイルの \fIst_atime\fP, \fIst_ctime\fP, \fIst_mtime\fP フィールド
(それぞれ最終アクセス時刻、最終状態変更時刻、最終修正時刻である。 \fBstat\fP(2)  参照) が現在時刻に設定される。 さらに親ディレクトリの
\fIst_ctime\fP と \fIst_mtime\fP も現在時刻に設定される。 それ以外の場合で、O_TRUNC フラグでファイルが修正されたときは、
ファイルの \fIst_ctime\fP と \fIst_mtime\fP フィールドが現在時刻に設定される。
.PP
The files in the \fI/proc/[pid]/fd\fP directory show the open file descriptors
of the process with the PID \fIpid\fP.  The files in the \fI/proc/[pid]/fdinfo\fP
directory show even more information about these file descriptors.  See
\fBproc\fP(5)  for further details of both of these directories.
.PP
.\"
.\"
The Linux header file \fB<asm/fcntl.h>\fP doesn't define \fBO_ASYNC\fP;
the (BSD\-derived)  \fBFASYNC\fP synonym is defined instead.
.SS オープンファイル記述
オープンファイル記述という用語は POSIX
で使用されている用語で、オープンされているファイルのシステム共通のテーブルのエントリーを参照するものである。
別の文脈では、このオブジェクトはいろいろな呼び方があり、
「オープンファイルオブジェクト」、「ファイルハンドル」、「オープンファイルテーブルエントリー」、 カーネル開発者の用語では \fIstruct file\fP
などと呼ばれる。
.PP
ファイルディスクリプターが (\fBdup\fP(2) や同様のシステムコールを使って) 複製される際に、
複製されたファイルディスクリプターは元のファイルディスクリプターと同じオープンファイル記述を参照する。 結果として 2
つのファイルディスクリプターはファイルオフセットとファイル状態フラグを共有する。 このような共有はプロセス間でも起こり得る。 \fBfork\fP(2)
で作成された子プロセスは親プロセスのファイルディスクリプターの複製を継承し、これらの複製は同じオープンファイル記述を参照する。
.PP
1 つのファイルに対して \fBopen\fP() を行う毎に、新しいオープンファイル記述が作成される。 したがって、 1 つのファイル inode
に対して複数のオープンファイル記述が存在することがありえる。
.PP
.\"
.\"
On Linux, one can use the \fBkcmp\fP(2)  \fBKCMP_FILE\fP operation to test whether
two file descriptors (in the same process or in two different processes)
refer to the same open file description.
.SS "同期 I/O"
POSIX.1\-2008 の「同期 I/O」の選択肢として複数種類が規定されており、 動作を制御するために \fBopen\fP() フラグとして
\fBO_SYNC\fP, \fBO_DSYNC\fP, \fBO_RSYNC\fP が規定されている。 この選択肢を実装がサポートしているかに関わらず、
各実装では少なくとも通常のファイルに対して \fBO_SYNC\fP が利用できなければならない。
.PP
Linux implements \fBO_SYNC\fP and \fBO_DSYNC\fP, but not \fBO_RSYNC\fP.  Somewhat
incorrectly, glibc defines \fBO_RSYNC\fP to have the same value as \fBO_SYNC\fP.
(\fBO_RSYNC\fP is defined in the Linux header file \fI<asm/fcntl.h>\fP on
HP PA\-RISC, but it is not used.)
.PP
\fBO_SYNC\fP は、 同期 I/O での\fIファイル\fP完全性完了を提供する。 つまり、
書き込み操作はデータとすべての関連メタデータを裏で利用されているハードウェアにフラッシュすることを意味する。 \fBO_DSYNC\fP は、 同期 I/O
での\fIデータ\fP完全性完了を提供する。 つまり、 書き込み操作はデータを裏で利用されているハードウェアにフラッシュするが、
それ以降の読み出し操作が正常に完了するのに必要なメタデータの更新のみをフラッシュする。 データ完全性完了は、
ファイル完全性完了を必要としないアプリケーションで、 ディスク操作の数を減らすことができる。
.PP
2 種類の完了の違いを理解するために、 ファイルメタデータの 2 つの要素、 ファイルの最終修正時刻 (\fIst_mtime\fP)
とファイル長、を考える。 すべての書き込み操作は最終修正時刻を更新するが、 ファイルの末尾にデータを追加する書き込み操作のみがファイル長を変更する。
最終修正時刻は、 読み出しが正常に完了するのに必要ではないが、 ファイル長は必要である。 したがって、 \fBO_DSYNC\fP
はファイル長のメタデータの更新がフラッシュされることだけを保証する (これに対して \fBO_SYNC\fP
では最終修正時刻のメタデータも常にフラッシュされる)。
.PP
Linux 2.6.33 より前では、 Linux は \fBopen\fP() では \fBO_SYNC\fP フラグのみを実装していた。 しかしながら、
このフラグが指定された場合、 ほとんどのファイルシステムで提供されていたのは実際には同期 I/O での\fIデータ\fP完全性完了と等価なものであった
(つまり、 \fBO_SYNC\fP は実際には \fBO_DSYNC\fP と等価なものとして実装されていた)。
.PP
.\"
Linux 2.6.33 以降では、 正しい \fBO_SYNC\fP のサポートが提供されている。しかしながら、バイナリレベルの後方互換性を保証するため、
\fBO_DSYNC\fP は以前の \fBO_SYNC\fP と同じ値で定義されており、 \fBO_SYNC\fP は \fBO_DSYNC\fP フラグの値を含む新しい
(2 ビットの) フラグ値として定義されている。これにより、新しいヘッダーを使ってコンパイルされたアプリケーションで、 2.6.33
より前のカーネルで少なくとも \fBO_DSYNC\fP の動作は同じになることが保証される。
.SS "C ライブラリとカーネルの違い"
.\"
Since version 2.26, the glibc wrapper function for \fBopen\fP()  employs the
\fBopenat\fP()  system call, rather than the kernel's \fBopen\fP()  system call.
For certain architectures, this is also true in glibc versions before 2.26.
.SS NFS
NFS を実現しているプロトコルには多くの不備があり、特に \fBO_SYNC\fP と \fBO_NDELAY\fP に影響する。
.PP
.\"
.\"
UID マッピングを使用している NFS ファイルシステムでは、 \fBopen\fP()  がファイルディスクリプターを返した場合でも \fBread\fP(2)
が \fBEACCES\fP で拒否される場合がある。 これはクライアントがアクセス許可のチェックを行って \fBopen\fP()
を実行するが、読み込みや書き込みの際には サーバーで UID マッピングが行われるためである。
.SS FIFOs
.\"
.\"
Opening the read or write end of a FIFO blocks until the other end is also
opened (by another process or thread).  See \fBfifo\fP(7)  for further details.
.SS ファイルアクセスモード
「アクセスモード」の値 \fBO_RDONLY\fP, \fBO_WRONLY\fP, \fBO_RDWR\fP は、 \fIflags\fP
に指定できる他の値と違い、個々のビットを指定するものではなく、 これらの値は \fIflags\fP の下位 2 ビットを定義する。 \fBO_RDONLY\fP,
\fBO_WRONLY\fP, \fBO_RDWR\fP はそれぞれ 0, 1, 2 に定義されている。 言い換えると、 \fBO_RDONLY |
O_WRONLY\fP の組み合わせは論理的に間違いであり、確かに \fBO_RDWR\fP と同じ意味ではない。
.PP
.\" See for example util-linux's disk-utils/setfdprm.c
.\" For some background on access mode 3, see
.\" http://thread.gmane.org/gmane.linux.kernel/653123
.\" "[RFC] correct flags to f_mode conversion in __dentry_open"
.\" LKML, 12 Mar 2008
.\"
.\"
Linux では、特別な、非標準なアクセスモードとして 3 (バイナリでは 11) が 予約されており \fIflags\fP に指定できる。
このアクセスモードを指定すると、ファイルの読み出し/書き込み許可をチェックし、 読み出しにも書き込みにも使用できないファイルディスクリプターを返す。
この非標準のアクセスモードはいくつかの Linux ドライバで、デバイス固有の \fBioctl\fP(2)
操作にのみ使用されるファイルディスクリプターを返すために使われている。
.SS "openat() や他のディレクトリファイルディスクリプター API の基本原理"
\fBopenat\fP()  and the other system calls and library functions that take a
directory file descriptor argument (i.e., \fBexecveat\fP(2), \fBfaccessat\fP(2),
\fBfanotify_mark\fP(2), \fBfchmodat\fP(2), \fBfchownat\fP(2), \fBfspick\fP(2),
\fBfstatat\fP(2), \fBfutimesat\fP(2), \fBlinkat\fP(2), \fBmkdirat\fP(2),
\fBmove_mount\fP(2), \fBmknodat\fP(2), \fBname_to_handle_at\fP(2), \fBopen_tree\fP(2),
\fBopenat2\fP(2), \fBreadlinkat\fP(2), \fBrenameat\fP(2), \fBstatx\fP(2),
\fBsymlinkat\fP(2), \fBunlinkat\fP(2), \fButimensat\fP(2), \fBmkfifoat\fP(3), and
\fBscandirat\fP(3))  address two problems with the older interfaces that
preceded them.  Here, the explanation is in terms of the \fBopenat\fP()  call,
but the rationale is analogous for the other interfaces.
.PP
First, \fBopenat\fP()  allows an application to avoid race conditions that
could occur when using \fBopen\fP()  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 \fBopen\fP()  could be
changed in parallel with the call to \fBopen\fP().  Suppose, for example, that
we wish to create the file \fIdir1/dir2/xxx.dep\fP if the file \fIdir1/dir2/xxx\fP
exists.  The problem is that between the existence check and the
file\-creation step, \fIdir1\fP or \fIdir2\fP (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 \fIdirfd\fP argument of (say)
\fBfstatat\fP(2)  and \fBopenat\fP().  The use of the \fIdirfd\fP file descriptor
also has other benefits:
.IP * 3
the file descriptor is a stable reference to the directory, even if the
directory is renamed; and
.IP *
the open file descriptor prevents the underlying filesystem from being
dismounted, just as when a process has a current working directory on a
filesystem.
.PP
二つ目として、 \fBopenat\fP() を使うと、アプリケーションが管理するファイルディスクリプターにより、
スレッド単位の「カレントワーキングディレクトリ」を実装することができる (この機能は、 \fI/proc/self/fd/dirfd\fP
を使った方法でも実現することができるが、 効率の面で落とる)。
.PP
The \fIdirfd\fP argument for these APIs can be obtained by using \fBopen\fP()  or
\fBopenat\fP()  to open a directory (with either the \fBO_RDONLY\fP or the
\fBO_PATH\fP flag).  Alternatively, such a file descriptor can be obtained by
applying \fBdirfd\fP(3)  to a directory stream created using \fBopendir\fP(3).
.PP
.\"
.\"
When these APIs are given a \fIdirfd\fP argument of \fBAT_FDCWD\fP 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 \fIflags\fP argument that provides access to
functionality that is not available with the corresponding conventional
APIs.
.SS O_DIRECT
\fBO_DIRECT\fP フラグを使用する場合、ユーザー空間バッファーの長さやアドレス、 I/O
のファイルオフセットに関してアラインメントの制限が課されることがある。 Linux では、アラインメントの制限はファイルシステムやカーネルのバージョンに
よって異なり、全く制限が存在しない場合もある。 しかしながら、現在のところ、指定されたファイルやファイルシステムに対して
こうした制限があるかを見つけるための、アプリケーション向けのインターフェースで ファイルシステム非依存のものは存在しない。
いくつかのファイルシステムでは、制限を確認するための独自のインターフェースが 提供されている。例えば、 \fBxfsctl\fP(3)  の
\fBXFS_IOC_DIOINFO\fP 命令である。
.PP
Linux 2.4 では、転送サイズ、 ユーザーバッファーのアライメント、ファイルオフセットは、
ファイルシステムの論理ブロックサイズの倍数でなければならない。 Linux 2.6.0 以降では、
内部で使われるストレージの論理ブロックサイズのアライメント (通常は 512 バイト) で十分である。 論理ブロックサイズは \fBioctl\fP(2)
\fBBLKSSZGET\fP 操作や以下のシェルコマンドから知ることができる。
.PP
.in +4n
.EX
blockdev \-\-getss
.EE
.in
.PP
メモリーバッファーがプライベートマッピング (\fBmmap\fP(2) の \fBMAP_PRIVATE\fP
フラグで作成されたマッピング) の場合には、\fBO_DIRECT\fP I/O は
\fBfork\fP(2) システムコールと同時に決して実行すべきではない
(プライベートマッピングには、ヒープ領域に割り当てられたメモリーや静的に
割り当てたバッファーも含まれる)。非同期 I/O インターフェース (AIO) 経由
やプロセス内の他のスレッドから発行された、このような I/O は、
\fBfork\fP(2) が呼び出される前に完了されるべきである。
そうしなかった場合、データ破壊や、親プロセスや子プロセスでの予期しない
動作が起こる可能性がある。
\fBO_DIRECT\fP I/O 用のメモリーバッファーが \fBshmat\fP(2) や\fBMAP_SHARED\fP フラグ
付きの \fBmmap\fP(2) で作成された場合には、この制限はあてはまらない。
\fBmadvise\fP(2) でメモリーバッファーにアドバイス \fBMADV_DONTFORK\fP が設定され
ている場合にも、この制限はあてはまらない(\fBMADV_DONTFORK\fP はそのメモリー
バッファーが \fBfork\fP(2) 後に子プロセスからは利用できないことを保証するも
のである)。
.PP
\fBO_DIRECT\fP フラグは SGI IRIX で導入された。SGI IRIX にも Linux 2.4 と同様の (ユーザーバッファーの)
アラインメントの制限がある。 また、IRIX には適切な配置とサイズを取得するための \fBfcntl\fP(2)  コールがある。 FreeBSD 4.x
も同じ名前のフラグを導入したが、アラインメントの制限はない。
.PP
\fBO_DIRECT\fP 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 \fBopen\fP()  fails with the error \fBEINVAL\fP if it is
used.
.PP
アプリケーションは、同じファイル、 特に同じファイルの重複するバイト領域に対して、 \fBO_DIRECT\fP と通常の I/O
を混ぜて使うのは避けるべきである。 ファイルシステムがこのような状況において一貫性の問題を正しく 扱うことができる場合であっても、全体の I/O
スループットは どちらか一方を使用するときと比べて低速になるであろう。 同様に、アプリケーションは、同じファイルに対して \fBmmap\fP(2)  と直接
I/O (\fBO_DIRECT\fP)  を混ぜて使うのも避けるべきである。
.PP
NFS で \fBO_DIRECT\fP を使った場合の動作はローカルのファイルシステムの場合と違う。
古いカーネルや、ある種の設定でコンパイルされたカーネルは、 \fBO_DIRECT\fP と NFS の組み合わせをサポートしていないかもしれない。 NFS
プロトコル自体はサーバにフラグを渡す機能は持っていないので、 \fBO_DIRECT\fP I/O
はクライアント上のページキャッシュをバイパスするだけになり、 サーバは I/O をキャッシュしているかもしれない。 クライアントは、
\fBO_DIRECT\fP の同期機構を保持するため、サーバに対して I/O を同期して行うように依頼する。 サーバによっては、こうした状況下、特に I/O
サイズが小さい場合に 性能が大きく劣化する。 また、サーバによっては、I/O が安定したストレージにまで行われたと、
クライアントに対して嘘をつくものもある。 これは、サーバの電源故障が起こった際にデータの完全性が保たれない
危険は少しあるが、性能面での不利な条件を回避するために行われている。 Linux の NFS クライアントでは \fBO_DIRECT\fP I/O
でのアラインメントの制限はない。
.PP
まとめると、 \fBO_DIRECT\fP は、注意して使うべきであるが、強力なツールとなる可能性を持っている。 アプリケーションは \fBO_DIRECT\fP
をデフォルトでは無効になっている性能向上のためのオプションと 考えておくのがよいであろう。
.SH バグ
.\" FIXME . Check bugzilla report on open(O_ASYNC)
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
現在のところ、 \fBopen\fP()  の呼び出し時に \fBO_ASYNC\fP を指定してシグナル駆動 I/O を有効にすることはできない。
このフラグを有効にするには \fBfcntl\fP(2)  を使用すること。
.PP
カーネルが \fBO_TMPFILE\fP 機能をサポートしているかを判定する際に、 \fBEISDIR\fP と \fBENOENT\fP の 2
つのエラーコードをチェックしなければならない。
.PP
When both \fBO_CREAT\fP and \fBO_DIRECTORY\fP are specified in \fIflags\fP and the
file specified by \fIpathname\fP does not exist, \fBopen\fP()  will create a
regular file (i.e., \fBO_DIRECTORY\fP is ignored).
.SH 関連項目
\fBchmod\fP(2), \fBchown\fP(2), \fBclose\fP(2), \fBdup\fP(2), \fBfcntl\fP(2), \fBlink\fP(2),
\fBlseek\fP(2), \fBmknod\fP(2), \fBmmap\fP(2), \fBmount\fP(2), \fBopen_by_handle_at\fP(2),
\fBopenat2\fP(2), \fBread\fP(2), \fBsocket\fP(2), \fBstat\fP(2), \fBumask\fP(2),
\fBunlink\fP(2), \fBwrite\fP(2), \fBfopen\fP(3), \fBacl\fP(5), \fBfifo\fP(7), \fBinode\fP(7),
\fBpath_resolution\fP(7), \fBsymlink\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。