-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
-.\" 1993 Michael Haardt, Ian Jackson.
-.\" 2008 Greg Banks
+.\" 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.
.\"
.\" 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
.\"
.\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
.\" O_TTYINIT. Eventually these may need to be documented. --mtk
-.\" FIXME Linux 2.6.33 has O_DSYNC, and a hidden __O_SYNC.
-.\" FIXME: Linux 2.6.39 added O_PATH
.\"
-.TH OPEN 2 2012-05-01 "Linux" "Linux Programmer's Manual"
+.TH OPEN 2 2014-04-20 "Linux" "Linux Programmer's Manual"
.SH NAME
-open, creat \- open and possibly create a file or device
+open, openat, creat \- open and possibly create a file
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
.BI "int creat(const char *" pathname ", mode_t " mode );
+.sp
+.BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
+.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
+", mode_t " mode );
.fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR openat ():
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.TP
+Before glibc 2.10:
+_ATFILE_SOURCE
+.RE
+.ad
+.PD
.SH DESCRIPTION
Given a
.I pathname
The
.I file creation flags
are
-.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC .
+.BR O_CLOEXEC ,
+.BR O_CREAT ,
+.BR O_DIRECTORY ,
+.BR O_EXCL ,
+.BR O_NOCTTY ,
+.BR O_NOFOLLOW ,
+.BR O_TMPFILE ,
+.BR O_TRUNC ,
+and
+.BR O_TTY_INIT .
The
.I file status flags
are all of the remaining flags listed below.
-.\" FIXME . Actually is it true that the "file status flags" are all of the
-.\" remaining flags listed below? SUSv4 divides the flags into:
+.\" 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've raised an Aardvark to see if this
-.\" can be clarified in SUSv4; 10 Oct 2008.)
+.\" "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.
+.\"
The distinction between these two groups of flags is that
the file status flags can be retrieved and (in some cases)
-modified using
-.BR fcntl (2).
+modified; see
+.BR fcntl (2)
+for details.
+
The full list of file creation flags and file status flags is as follows:
.TP
.B O_APPEND
as if with
.BR lseek (2).
.B O_APPEND
-may lead to corrupted files on NFS file systems if more than one process
+may lead to corrupted files on NFS filesystems if more than one process
appends data to a file at once.
.\" For more background, see
.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
by default, but this can be changed via
.BR fcntl (2))
when input or output becomes possible on this file descriptor.
-This feature is only available for terminals, pseudoterminals,
+This feature is available only for terminals, pseudoterminals,
sockets, and (since Linux 2.6) pipes and FIFOs.
See
.BR fcntl (2)
for further details.
+See also BUGS, below.
.TP
-.BR O_CLOEXEC " (Since Linux 2.6.23)"
+.BR O_CLOEXEC " (since Linux 2.6.23)"
+.\" NOTE! several otehr man pages refer to this text
Enable the close-on-exec flag for the new file descriptor.
Specifying this flag permits a program to avoid additional
.BR fcntl (2)
operations to set the
.B FD_CLOEXEC
flag.
-Additionally,
-use of this flag is essential in some multithreaded programs
-since using a separate
+
+Note that the use of this flag is essential in some multithreaded programs,
+because using a separate
.BR fcntl (2)
.B F_SETFD
operation to set the
.B FD_CLOEXEC
flag does not suffice to avoid race conditions
-where one thread opens a file descriptor at the same
-time as another thread does a
+where one thread opens a file descriptor and
+attempts to set its close-on-exec flag using
+.BR fcntl (2)
+at the same time as another thread does a
.BR fork (2)
plus
.BR execve (2).
+Depending on the order of execution,
+the race may lead to the file desriptor returned by
+.BR open ()
+being unintentionally leaked to the program executed by the child process
+created by
+.BR fork (2).
+(This kind of race is in principle possible for any system call
+that creates a file descriptor whose close-on-exec flag should be set,
+and various other Linux system calls provide an equivalent of the
+.BR O_CLOEXEC
+flag to deal with this problem.)
.\" This flag fixes only one form of the race condition;
.\" The race can also occur with, for example, descriptors
.\" returned by accept(), pipe(), etc.
.TP
.B O_CREAT
-If the file does not exist it will be created.
+If the file does not exist, it will be created.
The owner (user ID) of the file is set to the effective user ID
of the process.
The group ownership (group ID) is set either to
the effective group ID of the process or to the group ID of the
-parent directory (depending on file system type and mount options,
-and the mode of the parent directory, see the mount options
+parent directory (depending on filesystem type and mount options,
+and the mode of the parent directory; see the mount options
.I bsdgroups
and
.I sysvgroups
specifies the permissions to use in case a new file is created.
This argument must be supplied when
.B O_CREAT
+or
+.B O_TMPFILE
is specified in
.IR flags ;
-if
+if neither
.B O_CREAT
-is not specified, then
+nor
+.B O_TMPFILE
+is specified, then
.I mode
is ignored.
The effective permissions are modified by
.I umask
in the usual way: The permissions of the created file are
.IR "(mode\ &\ ~umask)" .
-Note that this mode only applies to future accesses of the
+Note that this mode applies only to future accesses of the
newly created file; the
.BR open ()
call that creates a read-only file may well return a read/write
00001 others have execute permission
.RE
.TP
-.BR O_DIRECT " (Since Linux 2.4.10)"
+.BR O_DIRECT " (since Linux 2.4.10)"
Try to minimize cache effects of the I/O to and from this file.
In general this will degrade performance, but it is useful in
special situations, such as when applications do their own caching.
-File I/O is done directly to/from user space buffers.
+File I/O is done directly to/from user-space buffers.
The
.B O_DIRECT
flag on its own makes an effort to transfer data synchronously,
.\" 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.
-This flag is Linux-specific, and was added in kernel version 2.1.126, to
+This flag was added in kernel version 2.1.126, to
avoid denial-of-service problems if
.BR opendir (3)
is called on a
-FIFO or tape device, but should not be used outside of the
-implementation of
-.BR opendir (3).
+FIFO or tape device.
+.TP
+.B O_DSYNC
+Write operations on the file will complete according to the requirements of
+synchronized I/O
+.I data
+integrity completion.
+
+By the time
+.BR write (2)
+(and similar)
+return, the output data
+has been transferred to the underlying hardware,
+along with any file metadata that would be required to retrieve that data
+(i.e., as though each
+.BR write (2)
+was followed by a call to
+.BR fdatasync (2)).
+.IR "See NOTES below" .
.TP
.B O_EXCL
Ensure that this call creates the file:
On NFS,
.B O_EXCL
-is only supported when using NFSv3 or later on kernel 2.6 or later.
+is supported only when using NFSv3 or later on kernel 2.6 or later.
In NFS environments where
.B O_EXCL
support is not provided, programs that rely on it
and need to avoid reliance on NFS support for
.BR O_EXCL ,
can create a unique file on
-the same file system (e.g., incorporating hostname and PID), and use
+the same filesystem (e.g., incorporating hostname and PID), and use
.BR link (2)
to make a link to the lockfile.
If
method of accessing large files on 32-bit systems (see
.BR feature_test_macros (7)).
.TP
-.BR O_NOATIME " (Since Linux 2.6.8)"
-Do not update the file last access time (st_atime in the inode)
+.BR O_NOATIME " (since Linux 2.6.8)"
+Do not update the file last access time
+.RI ( st_atime
+in the inode)
when the file is
.BR read (2).
This flag is intended for use by indexing or backup programs,
where its use can significantly reduce the amount of disk activity.
-This flag may not be effective on all file systems.
+This flag may not be effective on all filesystems.
One example is NFS, where the server maintains the access time.
.\" The O_NOATIME flag also affects the treatment of st_atime
.\" by mmap() and readdir(2), MTK, Dec 04.
If
.I pathname
refers to a terminal device\(emsee
-.BR tty (4)\(em
-it will not become the process's controlling terminal even if the
+.BR tty (4)\(emit
+will not become the process's controlling terminal even if the
process does not have one.
.TP
.B O_NOFOLLOW
This is a FreeBSD extension, which was added to Linux in version 2.1.126.
Symbolic links in earlier components of the pathname will still be
followed.
+See also
+.BR O_PATH
+below.
.\" 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.
in conjunction with mandatory file locks and with file leases, see
.BR fcntl (2).
.TP
+.BR O_PATH " (since 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
+.\"
+Obtain a file descriptor that can be used for two purposes:
+to indicate a location in the filesystem tree and
+to perform operations that act purely at the file descriptor level.
+The file itself is not opened, and other file operations (e.g.,
+.BR read (2),
+.BR write (2),
+.BR fchmod (2),
+.BR fchown (2),
+.BR fgetxattr (2),
+.BR mmap (2))
+fail with the error
+.BR EBADF .
+
+The following operations
+.I can
+be performed on the resulting file descriptor:
+.RS
+.IP * 3
+.BR close (2);
+.BR fchdir (2)
+(since Linux 3.5);
+.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
+.BR fstat (2)
+(since Linux 3.6).
+.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
+.IP *
+Duplicating the file descriptor
+.RB ( dup (2),
+.BR fcntl (2)
+.BR F_DUPFD ,
+etc.).
+.IP *
+Getting and setting file descriptor flags
+.RB ( fcntl (2)
+.BR F_GETFD
+and
+.BR F_SETFD ).
+.IP *
+Retrieving open file status flags using the
+.BR fcntl (2)
+.BR F_GETFL
+operation: the returned flags will include the bit
+.BR O_PATH .
+
+.IP *
+Passing the file descriptor as the
+.IR dirfd
+argument of
+.BR openat (2)
+and the other "*at()" system calls.
+.IP *
+Passing the file descriptor to another process via a UNIX domain socket
+(see
+.BR SCM_RIGHTS
+in
+.BR unix (7)).
+.RE
+.IP
+When
+.B O_PATH
+is specified in
+.IR flags ,
+flag bits other than
+.BR O_DIRECTORY
+and
+.BR O_NOFOLLOW
+are ignored.
+
+If
+.I pathname
+is a symbolic link and the
+.BR O_NOFOLLOW
+flag is also specified,
+then the call returns a file descriptor referring to the symbolic link.
+This file descriptor can be used as the
+.I dirfd
+argument in calls to
+.BR fchownat (2),
+.BR fstatat (2),
+.BR linkat (2),
+and
+.BR readlinkat (2)
+with an empty pathname to have the calls operate on the symbolic link.
+.TP
.B O_SYNC
-The file is opened for synchronous I/O.
-Any
-.BR write (2)s
-on the resulting file descriptor will block the calling process until
-the data has been physically written to the underlying hardware.
-.IR "But see NOTES below" .
+Write operations on the file will complete according to the requirements of
+synchronized I/O
+.I file
+integrity completion
+(by contrast with contrast with the
+synchronized I/O
+.I data
+integrity completion
+provided by
+.BR O_DSYNC .)
+
+By the time
+.BR write (2)
+(and similar)
+return, the output data and associated file metadata
+have been transferred to the underlying hardware
+(i.e., as though each
+.BR write (2)
+was followed by a call to
+.BR fsync (2)).
+.IR "See NOTES below" .
+.TP
+.BR O_TMPFILE " (since Linux 3.11)"
+.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
+.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
+.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
+Create an unnamed temporary file.
+The
+.I pathname
+argument specifies a directory;
+an unnamed inode will be created in that directory's filesystem.
+Anything written to the resulting file will be lost when
+the last file descriptor is closed, unless the file is given a name.
+
+.B O_TMPFILE
+must be specified with one of
+.B O_RDWR
+or
+.B O_WRONLY
+and, optionally,
+.BR O_EXCL .
+If
+.B O_EXCL
+is not specified, then
+.BR linkat (2)
+can be used to link the temporary file into the filesystem, making it
+permanent, using code like the following:
+
+.in +4n
+.nf
+char path[PATH_MAX];
+fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
+ S_IRUSR | S_IWUSR);
+
+/* File I/O on 'fd'... */
+
+snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
+linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
+ AT_SYMLINK_FOLLOW);
+.fi
+.in
+
+In this case,
+the
+.BR open ()
+.I mode
+argument determines the file permission mode, as with
+.BR O_CREAT .
+
+Specifying
+.B O_EXCL
+in conjunction with
+.B O_TMPFILE
+prevents a temporary file from being linked into the filesystem
+in the above manner.
+(Note that the meaning of
+.B O_EXCL
+in this case is different from the meaning of
+.B O_EXCL
+otherwise.)
+
+
+There are two main use cases for
+.\" Inspired by http://lwn.net/Articles/559147/
+.BR O_TMPFILE :
+.RS
+.IP * 3
+Improved
+.BR tmpfile (3)
+functionality: race-free creation of temporary files that
+(1) are automatically deleted when closed;
+(2) can never be reached via any pathname;
+(3) are not subject to symlink attacks; and
+(4) do not require the caller to devise unique names.
+.IP *
+Creating a file that is initially invisible, which is then populated
+with data and adjusted to have appropriate filesystem attributes
+.RB ( chown (2),
+.BR chmod (2),
+.BR fsetxattr (2),
+etc.)
+before being atomically linked into the filesystem
+in a fully formed state (using
+.BR linkat (2)
+as described above).
+.RE
+.IP
+.B 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 ex2, ext3, ext4, UDF, Minix, and shmem filesystems.
+XFS support was added
+.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
+.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
+in Linux 3.15.
.TP
.B O_TRUNC
-If the file already exists and is a regular file and the open mode allows
+If the file already exists and is a regular file and the access mode allows
writing (i.e., is
.B O_RDWR
or
Otherwise the effect of
.B O_TRUNC
is unspecified.
-.PP
-Some of these optional flags can be altered using
-.BR fcntl (2)
-after the file has been opened.
-
+.SS creat()
.BR creat ()
is equivalent to
.BR open ()
.I flags
equal to
.BR O_CREAT|O_WRONLY|O_TRUNC .
-.SH "RETURN VALUE"
+.SS openat()
+The
+.BR openat ()
+system call operates in exactly the same way as
+.BR open (),
+except for the differences described here.
+
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+relative to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
.BR open ()
+for a relative pathname).
+
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR open ()).
+
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.SH RETURN VALUE
+.BR open (),
+.BR openat (),
and
.BR creat ()
return the new file descriptor, or \-1 if an error occurred
.I errno
is set appropriately).
.SH ERRORS
+.BR open (),
+.BR openat (),
+and
+.BR creat ()
+can fail with the following errors:
.TP
.B EACCES
The requested access to the file is not allowed, or search permission
(See also
.BR path_resolution (7).)
.TP
+.B EDQUOT
+Where
+.B O_CREAT
+is specified, the file does not exist, and the user's quota of disk
+blocks or inodes on the filesystem has been exhausted.
+.TP
.B EEXIST
.I pathname
already exists and
the call was interrupted by a signal handler; see
.BR signal (7).
.TP
+.B EINVAL
+The filesystem does not support the
+.BR O_DIRECT
+flag.
+See
+.BR NOTES
+for more information.
+.TP
+.B EINVAL
+Invalid value in
+.\" In particular, __O_TMPFILE instead of O_TMPFILE
+.IR flags .
+.TP
+.B EINVAL
+.B O_TMPFILE
+was specified in
+.IR flags ,
+but neither
+.B O_WRONLY
+nor
+.B O_RDWR
+was specified.
+.TP
.B EISDIR
.I pathname
refers to a directory and the access requested involved writing
.B O_RDWR
is set).
.TP
+.B EISDIR
+.I pathname
+refers to an existing directory,
+.B O_TMPFILE
+and one of
+.B O_WRONLY
+or
+.B O_RDWR
+were specified in
+.IR flags ,
+but this kernel version does not provide the
+.B O_TMPFILE
+functionality.
+.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname ,
-or \fBO_NOFOLLOW\fP was specified but
+.IR pathname .
+.TP
+.B ELOOP
.I pathname
-was a symbolic link.
+was a symbolic link, and
+.I flags
+specified
+.BR O_NOFOLLOW
+but not
+.BR O_PATH .
.TP
.B EMFILE
The process already has the maximum number of files open.
.I pathname
does not exist or is a dangling symbolic link.
.TP
+.B ENOENT
+.I pathname
+refers to a nonexistent directory,
+.B O_TMPFILE
+and one of
+.B O_WRONLY
+or
+.B O_RDWR
+were specified in
+.IR flags ,
+but this kernel version does not provide the
+.B O_TMPFILE
+functionality.
+.TP
.B ENOMEM
Insufficient kernel memory was available.
.TP
no process has the file open for reading.
Or, the file is a device special file and no corresponding device exists.
.TP
+.BR EOPNOTSUPP
+The filesystem containing
+.I pathname
+does not support
+.BR O_TMPFILE .
+.TP
.B EOVERFLOW
.I pathname
refers to a regular file that is too large to be opened.
The
.B O_NOATIME
flag was specified, but the effective user ID of the caller
-.\" Strictly speaking, it's the file system UID... (MTK)
+.\" Strictly speaking, it's the filesystem UID... (MTK)
did not match the owner of the file and the caller was not privileged
.RB ( CAP_FOWNER ).
.TP
.B EROFS
.I pathname
-refers to a file on a read-only file system and write access was
+refers to a file on a read-only filesystem and write access was
requested.
.TP
.B ETXTBSY
flag was specified, and an incompatible lease was held on the file
(see
.BR fcntl (2)).
-.SH "CONFORMING TO"
-SVr4, 4.3BSD, POSIX.1-2001.
+.PP
+The following additional errors can occur for
+.BR openat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B ENOTDIR
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH VERSIONS
+.BR openat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
+.SH CONFORMING TO
+.BR open (),
+.BR creat ()
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
+
+.BR openat ():
+POSIX.1-2008.
+
The
-.BR O_DIRECTORY ,
+.BR O_DIRECT ,
.BR O_NOATIME ,
+.BR O_PATH ,
and
-.B O_NOFOLLOW
-flags are Linux-specific, and one may need to define
+.BR O_TMPFILE
+flags are Linux-specific.
+One must define
.B _GNU_SOURCE
-(before including
-.I any
-header files)
to obtain their definitions.
The
-.BR O_CLOEXEC
-flag is not specified in POSIX.1-2001,
-but is specified in POSIX.1-2008.
+.BR O_CLOEXEC ,
+.BR O_DIRECTORY ,
+and
+.BR O_NOFOLLOW
+flags are not specified in POSIX.1-2001,
+but are specified in POSIX.1-2008.
+Since glibc 2.12, one can obtain their definitions by defining either
+.B _POSIX_C_SOURCE
+with a value greater than or equal to 200809L or
+.BR _XOPEN_SOURCE
+with a value greater than or equal to 700.
+In glibc 2.11 and earlier, one obtains the definitions by defining
+.BR _GNU_SOURCE .
-.B O_DIRECT
-is not specified in POSIX; one has to define
+As noted in
+.BR feature_test_macros (7),
+feature test macros such as
+.BR _POSIX_C_SOURCE ,
+.BR _XOPEN_SOURCE ,
+and
.B _GNU_SOURCE
-(before including
+must be defined before including
.I any
-header files)
-to get its definition.
+header files.
.SH NOTES
Under Linux, the
.B O_NONBLOCK
for use with
.BR ioctl (2).
-Unlike the other values that can be specified in
-.IR flags ,
-the
-.I "access mode"
-values
-.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR ,
-do not specify individual bits.
-Rather, they define the low order two bits of
-.IR flags ,
-and are defined respectively as 0, 1, and 2.
-In other words, the combination
-.B "O_RDONLY | O_WRONLY"
-is a logical error, and certainly does not have the same meaning as
-.BR O_RDWR .
-Linux reserves the special, nonstandard access mode 3 (binary 11) in
-.I flags
-to mean:
-check for read and write permission on the file and return a descriptor
-that can't be used for reading or writing.
-This nonstandard access mode is used by some Linux drivers to return a
-descriptor that is only to be used for device-specific
-.BR ioctl (2)
-operations.
-.\" 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
.LP
The (undefined) effect of
.B O_RDONLY | O_TRUNC
.\" Tru64 5.1B: truncate
.\" HP-UX 11.22: truncate
.\" FreeBSD 4.7: truncate
-.PP
-There are many infelicities in the protocol underlying NFS, affecting
-amongst others
-.BR O_SYNC " and " O_NDELAY .
-
-POSIX provides for three different variants of synchronized I/O,
-corresponding to the flags
-.BR O_SYNC ,
-.BR O_DSYNC ,
-and
-.BR O_RSYNC .
-Currently (2.6.31), Linux only implements
-.BR O_SYNC ,
-but glibc maps
-.B O_DSYNC
-and
-.B O_RSYNC
-to the same numerical value as
-.BR O_SYNC .
-Most Linux file systems don't actually implement the POSIX
-.B O_SYNC
-semantics, which require all metadata updates of a write
-to be on disk on returning to userspace, but only the
-.B O_DSYNC
-semantics, which require only actual file data and metadata necessary
-to retrieve it to be on disk by the time the system call returns.
Note that
.BR open ()
cannot create them; use
.BR mknod (2)
instead.
-.LP
-On NFS file systems with UID mapping enabled,
-.BR open ()
-may
-return a file descriptor but, for example,
-.BR read (2)
-requests are denied
-with \fBEACCES\fP.
-This is because the client performs
-.BR open ()
-by checking the
-permissions, but UID mapping is performed by the server upon
-read and write requests.
If the file is newly created, its
.IR st_atime ,
Otherwise, if the file is modified because of the
.B O_TRUNC
flag, its st_ctime and st_mtime fields are set to the current time.
+.\"
+.\"
+.SS Synchronized I/O
+The POSIX.1-2008 "synchronized I/O" option
+specifies different variants of synchronized I/O,
+and specifies the
+.BR open ()
+flags
+.BR O_SYNC ,
+.BR O_DSYNC ,
+and
+.BR O_RSYNC
+for controlling the behavior.
+Regardless of whether an implementation supports this option,
+it must at least support the use of
+.BR O_SYNC
+for regular files.
+
+Linux implements
+.BR O_SYNC
+and
+.BR O_DSYNC ,
+but not
+.BR O_RSYNC .
+(Somewhat incorrectly, glibc defines
+.BR O_RSYNC
+to have the same value as
+.BR O_SYNC .)
+
+.BR O_SYNC
+provides synchronized I/O
+.I file
+integrity completion,
+meaning write operations will flush data and all associated metadata
+to the underlying hardware.
+.BR O_DSYNC
+provides synchronized I/O
+.I data
+integrity completion,
+meaning write operations will flush data
+to the underlying hardware,
+but will only flush metadata updates that are required
+to allow a subsequent read operation to complete successfully.
+Data integrity completion can reduce the number of disk operations
+that are required for applications that don't need the guarantees
+of file integrity completion.
+
+To understand the difference between the the two types of completion,
+consider two pieces of file metadata:
+the file last modification timestamp
+.RI ( st_mtime )
+and the file length.
+All write operations will update the last file modification timestamp,
+but only writes that add data to the end of the
+file will change the file length.
+The last modification timestamp is not needed to ensure that
+a read completes successfully, but the file length is.
+Thus,
+.BR O_DSYNC
+would only guarantee to flush updates to the file length metadata
+(whereas
+.BR O_SYNC
+would also always flush the last modification timestamp metadata).
+
+Before Linux 2.6.33, Linux implemented only the
+.BR O_SYNC
+flag for
+.BR open ().
+However, when that flag was specified,
+most filesystems actually provided the equivalent of synchronized I/O
+.I data
+integrity completion (i.e.,
+.BR O_SYNC
+was actually implemented as the equivalent of
+.BR O_DSYNC ).
+
+Since Linux 2.6.33, proper
+.BR O_SYNC
+support is provided.
+However, to ensure backward binary compatibility,
+.BR O_DSYNC
+was defined with the same value as the historical
+.BR O_SYNC ,
+and
+.BR O_SYNC
+was defined as a new (two-bit) flag value that includes the
+.BR O_DSYNC
+flag value.
+This ensures that applications compiled against
+new headers get at least
+.BR O_DSYNC
+semantics on pre-2.6.33 kernels.
+.\"
+.\"
+.SS NFS
+There are many infelicities in the protocol underlying NFS, affecting
+amongst others
+.BR O_SYNC " and " O_NDELAY .
+
+On NFS filesystems with UID mapping enabled,
+.BR open ()
+may
+return a file descriptor but, for example,
+.BR read (2)
+requests are denied
+with \fBEACCES\fP.
+This is because the client performs
+.BR open ()
+by checking the
+permissions, but UID mapping is performed by the server upon
+read and write requests.
+.\"
+.\"
+.SS File access mode
+Unlike the other values that can be specified in
+.IR flags ,
+the
+.I "access mode"
+values
+.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
+do not specify individual bits.
+Rather, they define the low order two bits of
+.IR flags ,
+and are defined respectively as 0, 1, and 2.
+In other words, the combination
+.B "O_RDONLY | O_WRONLY"
+is a logical error, and certainly does not have the same meaning as
+.BR O_RDWR .
+
+Linux reserves the special, nonstandard access mode 3 (binary 11) in
+.I flags
+to mean:
+check for read and write permission on the file and return a descriptor
+that can't be used for reading or writing.
+This nonstandard access mode is used by some Linux drivers to return a
+descriptor that is to be used only for device-specific
+.BR ioctl (2)
+operations.
+.\" 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
+.\"
+.\"
+.SS Rationale for openat() and other "directory file descriptor" APIs
+.BR openat ()
+and the other system calls and library functions that take
+a directory file descriptor argument
+(i.e.,
+.BR faccessat (2),
+.BR fanotify_mark (2),
+.BR fchmodat (2),
+.BR fchownat (2),
+.BR fstatat (2),
+.BR futimesat (2),
+.BR linkat (2),
+.BR mkdirat (2),
+.BR mknodat (2),
+.BR name_to_handle_at (2),
+.BR readlinkat (2),
+.BR renameat (2),
+.BR symlinkat (2),
+.BR unlinkat (2),
+.BR utimensat (2)
+.BR mkfifoat (3),
+and
+.BR scandirat (3))
+are supported
+for two reasons.
+Here, the explanation is in terms of the
+.BR openat ()
+call, but the rationale is analogous for the other interfaces.
+
+First,
+.BR openat ()
+allows an application to avoid race conditions that could
+occur when using
+.BR 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
+.BR open ()
+could be changed in parallel with the call to
+.BR open ().
+Such races can be avoided by
+opening a file descriptor for the target directory,
+and then specifying that file descriptor as the
+.I dirfd
+argument of
+.BR openat ().
+
+Second,
+.BR openat ()
+allows the implementation of a per-thread "current working
+directory", via file descriptor(s) maintained by the application.
+(This functionality can also be obtained by tricks based
+on the use of
+.IR /proc/self/fd/ dirfd,
+but less efficiently.)
+.\"
+.\"
.SS O_DIRECT
.LP
The
.B O_DIRECT
flag may impose alignment restrictions on the length and address
-of userspace buffers and the file offset of I/Os.
+of user-space buffers and the file offset of I/Os.
In Linux alignment
-restrictions vary by file system and kernel version and might be
+restrictions vary by filesystem and kernel version and might be
absent entirely.
-However there is currently no file system\-independent
+However there is currently no filesystem\-independent
interface for an application to discover these restrictions for a given
-file or file system.
-Some file systems provide their own interfaces
+file or filesystem.
+Some filesystems provide their own interfaces
for doing so, for example the
.B XFS_IOC_DIOINFO
operation in
.LP
Under Linux 2.4, transfer sizes, and the alignment of the user buffer
and the file offset must all be multiples of the logical block size
-of the file system.
+of the filesystem.
Under Linux 2.6, alignment to 512-byte boundaries suffices.
.LP
.B O_DIRECT
system call,
if the memory buffer is a private mapping
(i.e., any mapping created with the
-.BR mmap(2)
+.BR mmap (2)
.BR MAP_PRIVATE
flag;
this includes memory allocated on the heap and statically allocated buffers).
Nor does this restriction apply when the memory buffer has been advised as
.B MADV_DONTFORK
with
-.BR madvise(2),
+.BR madvise (2),
ensuring that it will not be available
to the child after
.BR fork (2).
.B O_DIRECT
support was added under Linux in kernel version 2.4.10.
Older Linux kernels simply ignore this flag.
-Some file systems may not implement the flag and
+Some filesystems may not implement the flag and
.BR open ()
will fail with
.B EINVAL
.B O_DIRECT
and normal I/O to the same file,
and especially to overlapping byte regions in the same file.
-Even when the file system correctly handles the coherency issues in
+Even when the filesystem correctly handles the coherency issues in
this situation, overall I/O throughput is likely to be slower than
using either mode alone.
Likewise, applications should avoid mixing
.LP
The behaviour of
.B O_DIRECT
-with NFS will differ from local file systems.
+with NFS will differ from local filesystems.
Older kernels, or
kernels configured in certain ways, may not support this combination.
The NFS protocol does not support passing the flag to the server, so
.B O_DIRECT
-I/O will only bypass the page cache on the client; the server may
+I/O will bypass the page cache only on the client; the server may
still cache the I/O.
The client asks the server to make the I/O
synchronous to preserve the synchronous semantics of
to enable this flag.
.\" FIXME . Check bugzilla report on open(O_ASYNC)
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
-.SH "SEE ALSO"
+
+One must check for two different error codes,
+.B EISDIR
+and
+.BR ENOENT ,
+when trying to determine whether the kernel supports
+.B O_TMPFILE
+functionality.
+.SH SEE ALSO
.BR chmod (2),
.BR chown (2),
.BR close (2),
.BR mknod (2),
.BR mmap (2),
.BR mount (2),
-.BR openat (2),
+.BR open_by_name_at (2),
.BR read (2),
.BR socket (2),
.BR stat (2),
.BR fifo (7),
.BR path_resolution (7),
.BR symlink (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
