2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
|
|
|
|
.\" 1993 Michael Haardt, Ian Jackson.
|
2008-02-11 10:38:24 +00:00
|
|
|
.\" 2008 Greg Banks
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" 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
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" 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 16:41:10 +00:00
|
|
|
.\" 2004-12-08, mtk, reordered flags list alphabetically
|
|
|
|
.\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
|
2007-09-10 04:34:20 +00:00
|
|
|
.\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
|
2008-01-03 16:06:22 +00:00
|
|
|
.\" 2008-01-03, mtk, with input from Trond Myklebust
|
2008-01-03 08:12:02 +00:00
|
|
|
.\" <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
|
|
|
|
.\" Rewrite description of O_EXCL.
|
2008-02-11 10:38:24 +00:00
|
|
|
.\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
|
|
|
|
.\" on O_DIRECT.
|
2008-05-12 14:38:18 +00:00
|
|
|
.\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2008-05-12 14:30:24 +00:00
|
|
|
.\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
|
2008-04-08 11:28:12 +00:00
|
|
|
.\" O_TTYINIT. Eventually these may need to be documented. --mtk
|
|
|
|
.\"
|
2009-09-20 05:41:16 +00:00
|
|
|
.TH OPEN 2 2009-09-20 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
open, creat \- open and possibly create a file or device
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <sys/types.h>
|
|
|
|
.B #include <sys/stat.h>
|
|
|
|
.B #include <fcntl.h>
|
|
|
|
.sp
|
|
|
|
.BI "int open(const char *" pathname ", int " flags );
|
|
|
|
.BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
|
2007-12-23 13:45:24 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
.BI "int creat(const char *" pathname ", mode_t " mode );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
2005-06-22 09:52:33 +00:00
|
|
|
Given a
|
2007-09-20 16:26:31 +00:00
|
|
|
.I pathname
|
2005-06-22 09:52:33 +00:00
|
|
|
for a file,
|
2005-06-21 10:04:56 +00:00
|
|
|
.BR open ()
|
2007-04-12 22:42:49 +00:00
|
|
|
returns a file descriptor, a small, non-negative integer
|
2005-06-22 09:52:33 +00:00
|
|
|
for use in subsequent system calls
|
|
|
|
.RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)."
|
|
|
|
The file descriptor returned by a successful call will be
|
2005-06-27 15:35:32 +00:00
|
|
|
the lowest-numbered file descriptor not currently open for the process.
|
2005-06-22 09:52:33 +00:00
|
|
|
.PP
|
2007-09-10 04:34:20 +00:00
|
|
|
By default, the new file descriptor is set to remain open across an
|
2005-06-22 09:52:33 +00:00
|
|
|
.BR execve (2)
|
2005-06-21 10:04:56 +00:00
|
|
|
(i.e., the
|
|
|
|
.B FD_CLOEXEC
|
|
|
|
file descriptor flag described in
|
|
|
|
.BR fcntl (2)
|
2007-09-10 04:34:20 +00:00
|
|
|
is initially disabled; the Linux-specific
|
|
|
|
.B O_CLOEXEC
|
|
|
|
flag, described below, can be used to change this default).
|
2005-06-21 10:04:56 +00:00
|
|
|
The file offset is set to the beginning of the file (see
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR lseek (2)).
|
2005-06-22 09:52:33 +00:00
|
|
|
.PP
|
|
|
|
A call to
|
|
|
|
.BR open ()
|
|
|
|
creates a new
|
|
|
|
.IR "open file description" ,
|
|
|
|
an entry in the system-wide table of open files.
|
|
|
|
This entry records the file offset and the file status flags
|
|
|
|
(modifiable via the
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR fcntl (2)
|
2005-06-22 09:52:33 +00:00
|
|
|
.B F_SETFL
|
|
|
|
operation).
|
2005-06-27 15:35:32 +00:00
|
|
|
A file descriptor is a reference to one of these entries;
|
|
|
|
this reference is unaffected if
|
|
|
|
.I pathname
|
|
|
|
is subsequently removed or modified to refer to a different file.
|
2005-06-22 09:52:33 +00:00
|
|
|
The new open file description is initially not shared
|
2005-06-27 15:35:32 +00:00
|
|
|
with any other process,
|
|
|
|
but sharing may arise via
|
|
|
|
.BR fork (2).
|
2005-06-22 09:52:33 +00:00
|
|
|
.PP
|
2008-07-10 20:53:08 +00:00
|
|
|
The argument
|
2004-11-03 13:51:07 +00:00
|
|
|
.I flags
|
2005-06-22 09:52:33 +00:00
|
|
|
must include one of the following
|
|
|
|
.IR "access modes" :
|
2007-12-05 13:47:50 +00:00
|
|
|
.BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
|
2005-06-22 09:52:33 +00:00
|
|
|
These request opening the file read-only, write-only, or read/write,
|
|
|
|
respectively.
|
2006-02-02 03:25:41 +00:00
|
|
|
|
|
|
|
In addition, zero or more file creation flags and file status flags
|
2007-04-12 22:42:49 +00:00
|
|
|
can be
|
2004-11-03 13:51:07 +00:00
|
|
|
.RI bitwise- or 'd
|
2005-06-22 09:52:33 +00:00
|
|
|
in
|
2006-02-02 03:25:41 +00:00
|
|
|
.IR flags .
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
|
|
|
.I file creation flags
|
|
|
|
are
|
2006-02-02 03:25:41 +00:00
|
|
|
.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC .
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
|
|
|
.I file status flags
|
2006-02-02 03:25:41 +00:00
|
|
|
are all of the remaining flags listed below.
|
2008-10-10 13:42:34 +00:00
|
|
|
.\" FIXME . Actually is it true that the "file status flags" are all of the
|
|
|
|
.\" remaining flags listed below? 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
|
2008-10-10 13:53:38 +00:00
|
|
|
.\" "File creation" flags is. (I've raised an Aardvark to see if this
|
2008-10-10 13:42:34 +00:00
|
|
|
.\" can be clarified in SUSv4; 10 Oct 2008.)
|
2006-02-02 03:25:41 +00:00
|
|
|
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).
|
|
|
|
The full list of file creation flags and file status flags is as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2004-12-08 16:41:10 +00:00
|
|
|
.B O_APPEND
|
2007-04-12 22:42:49 +00:00
|
|
|
The file is opened in append mode.
|
|
|
|
Before each
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR write (2),
|
2005-07-18 17:10:25 +00:00
|
|
|
the file offset is positioned at the end of the file,
|
2004-12-08 16:41:10 +00:00
|
|
|
as if with
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR lseek (2).
|
2004-12-08 16:41:10 +00:00
|
|
|
.B O_APPEND
|
|
|
|
may lead to corrupted files on NFS file systems if more than one process
|
2007-04-12 22:42:49 +00:00
|
|
|
appends data to a file at once.
|
2008-10-29 16:31:22 +00:00
|
|
|
.\" For more background, see
|
|
|
|
.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
|
|
|
|
.\" http://nfs.sourceforge.net/
|
2007-04-12 22:42:49 +00:00
|
|
|
This is because NFS does not support
|
2004-12-08 16:41:10 +00:00
|
|
|
appending to a file, so the client kernel has to simulate it, which
|
|
|
|
can't be done without a race condition.
|
|
|
|
.TP
|
|
|
|
.B O_ASYNC
|
2006-01-15 04:39:23 +00:00
|
|
|
Enable signal-driven I/O:
|
2007-06-21 05:38:48 +00:00
|
|
|
generate a signal
|
|
|
|
.RB ( SIGIO
|
|
|
|
by default, but this can be changed via
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR fcntl (2))
|
|
|
|
when input or output becomes possible on this file descriptor.
|
2007-04-12 22:42:49 +00:00
|
|
|
This feature is only available for terminals, pseudo-terminals,
|
2005-06-21 10:04:56 +00:00
|
|
|
sockets, and (since Linux 2.6) pipes and FIFOs.
|
|
|
|
See
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR fcntl (2)
|
|
|
|
for further details.
|
2007-09-10 04:34:20 +00:00
|
|
|
.TP
|
|
|
|
.BR O_CLOEXEC " (Since Linux 2.6.23)"
|
|
|
|
Enable the close-on-exec flag for the new file descriptor.
|
2008-10-10 12:01:50 +00:00
|
|
|
Specifying this flag permits a program to avoid additional
|
2007-09-10 04:34:20 +00:00
|
|
|
.BR fcntl (2)
|
|
|
|
.B F_SETFD
|
2008-10-10 12:01:50 +00:00
|
|
|
operations to set the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B FD_CLOEXEC
|
2007-09-10 04:34:20 +00:00
|
|
|
flag.
|
|
|
|
Additionally,
|
|
|
|
use of this flag is essential in some multithreaded programs
|
|
|
|
since using a separate
|
|
|
|
.BR fcntl (2)
|
|
|
|
.B F_SETFD
|
|
|
|
operation to set the
|
2007-09-20 16:26:31 +00:00
|
|
|
.B FD_CLOEXEC
|
2007-09-10 04:34:20 +00:00
|
|
|
flag does not suffice to avoid race conditions
|
|
|
|
where one thread opens a file descriptor at the same
|
|
|
|
time as another thread does a
|
|
|
|
.BR fork (2)
|
|
|
|
plus
|
|
|
|
.BR execve (2).
|
|
|
|
.\" This flag fixes only one form of the race condition;
|
|
|
|
.\" The race can also occur with, for example, descriptors
|
|
|
|
.\" returned by accept(), pipe(), etc.
|
2004-12-08 16:41:10 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B O_CREAT
|
|
|
|
If the file does not exist it will be created.
|
|
|
|
The owner (user ID) of the file is set to the effective user ID
|
2007-04-12 22:42:49 +00:00
|
|
|
of the process.
|
|
|
|
The group ownership (group ID) is set either to
|
2004-11-03 13:51:07 +00:00
|
|
|
the effective group ID of the process or to the group ID of the
|
2008-03-19 07:26:08 +00:00
|
|
|
parent directory (depending on file system type and mount options,
|
2008-05-13 10:54:22 +00:00
|
|
|
and the mode of the parent directory, see the mount options
|
2004-11-03 13:51:07 +00:00
|
|
|
.I bsdgroups
|
|
|
|
and
|
|
|
|
.I sysvgroups
|
2008-05-13 10:54:22 +00:00
|
|
|
described in
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR mount (8)).
|
2008-05-13 10:54:22 +00:00
|
|
|
.\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
|
|
|
|
.\" XFS (since 2.6.14).
|
2008-02-28 14:47:54 +00:00
|
|
|
.RS
|
|
|
|
.PP
|
|
|
|
.I mode
|
|
|
|
specifies the permissions to use in case a new file is created.
|
|
|
|
This argument must be supplied when
|
|
|
|
.B O_CREAT
|
|
|
|
is specified in
|
|
|
|
.IR flags ;
|
|
|
|
if
|
|
|
|
.B O_CREAT
|
|
|
|
is not specified, then
|
|
|
|
.I mode
|
|
|
|
is ignored.
|
|
|
|
The effective permissions are modified by
|
|
|
|
the process's
|
|
|
|
.I umask
|
|
|
|
in the usual way: The permissions of the created file are
|
2008-04-24 09:36:45 +00:00
|
|
|
.IR "(mode\ &\ ~umask)" .
|
2008-02-28 14:47:54 +00:00
|
|
|
Note that this mode only applies to future accesses of the
|
|
|
|
newly created file; the
|
|
|
|
.BR open ()
|
|
|
|
call that creates a read-only file may well return a read/write
|
|
|
|
file descriptor.
|
|
|
|
.PP
|
|
|
|
The following symbolic constants are provided for
|
|
|
|
.IR mode :
|
|
|
|
.TP 9
|
|
|
|
.B S_IRWXU
|
|
|
|
00700 user (file owner) has read, write and execute permission
|
|
|
|
.TP
|
|
|
|
.B S_IRUSR
|
|
|
|
00400 user has read permission
|
|
|
|
.TP
|
|
|
|
.B S_IWUSR
|
|
|
|
00200 user has write permission
|
|
|
|
.TP
|
|
|
|
.B S_IXUSR
|
|
|
|
00100 user has execute permission
|
|
|
|
.TP
|
|
|
|
.B S_IRWXG
|
|
|
|
00070 group has read, write and execute permission
|
|
|
|
.TP
|
|
|
|
.B S_IRGRP
|
|
|
|
00040 group has read permission
|
|
|
|
.TP
|
|
|
|
.B S_IWGRP
|
|
|
|
00020 group has write permission
|
|
|
|
.TP
|
|
|
|
.B S_IXGRP
|
|
|
|
00010 group has execute permission
|
|
|
|
.TP
|
|
|
|
.B S_IRWXO
|
|
|
|
00007 others have read, write and execute permission
|
|
|
|
.TP
|
|
|
|
.B S_IROTH
|
|
|
|
00004 others have read permission
|
|
|
|
.TP
|
|
|
|
.B S_IWOTH
|
|
|
|
00002 others have write permission
|
|
|
|
.TP
|
|
|
|
.B S_IXOTH
|
|
|
|
00001 others have execute permission
|
|
|
|
.RE
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2008-02-11 10:38:24 +00:00
|
|
|
.BR O_DIRECT " (Since Linux 2.4.10)"
|
2004-12-08 16:41:10 +00:00
|
|
|
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.
|
2009-09-20 05:41:16 +00:00
|
|
|
The
|
|
|
|
.B O_DIRECT
|
|
|
|
flag on its own makes at an effort to transfer data synchronously,
|
|
|
|
but does not give the guarantees of the
|
|
|
|
.B O_SYNC
|
|
|
|
that data and necessary metadata are transferred.
|
|
|
|
To guarantee synchronous I/O the
|
|
|
|
.B O_SYNC
|
|
|
|
must be used in addition to
|
|
|
|
.BR O_DIRECT .
|
2008-06-11 22:04:37 +00:00
|
|
|
See
|
2008-02-11 10:38:24 +00:00
|
|
|
.B NOTES
|
|
|
|
below for further discussion.
|
2006-03-12 21:18:47 +00:00
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
A semantically similar (but deprecated) interface for block devices
|
2006-03-12 21:18:47 +00:00
|
|
|
is described in
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR raw (8).
|
|
|
|
.TP
|
|
|
|
.B O_DIRECTORY
|
2007-07-18 20:24:30 +00:00
|
|
|
If \fIpathname\fP is not a directory, cause the open to fail.
|
2005-10-12 10:35:09 +00:00
|
|
|
.\" 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.
|
2007-12-25 21:28:09 +00:00
|
|
|
This flag is Linux-specific, and was added in kernel version 2.1.126, to
|
2007-05-12 09:06:04 +00:00
|
|
|
avoid denial-of-service problems if
|
|
|
|
.BR opendir (3)
|
|
|
|
is called on a
|
2004-12-08 16:41:10 +00:00
|
|
|
FIFO or tape device, but should not be used outside of the
|
2007-05-12 13:20:42 +00:00
|
|
|
implementation of
|
|
|
|
.BR opendir (3).
|
2004-12-08 16:41:10 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B O_EXCL
|
2008-01-03 08:12:02 +00:00
|
|
|
Ensure that this call creates the file:
|
|
|
|
if this flag is specified in conjunction with
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR O_CREAT ,
|
2008-01-03 08:12:02 +00:00
|
|
|
and
|
|
|
|
.I pathname
|
|
|
|
already exists, then
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR open ()
|
2007-04-12 22:42:49 +00:00
|
|
|
will fail.
|
2008-01-03 08:12:02 +00:00
|
|
|
The behavior of
|
|
|
|
.B O_EXCL
|
|
|
|
is undefined if
|
|
|
|
.B O_CREAT
|
|
|
|
is not specified.
|
|
|
|
|
|
|
|
When these two flags are specified, symbolic links are not followed:
|
|
|
|
.\" POSIX.1-2001 explicitly requires this behavior.
|
|
|
|
if
|
|
|
|
.I pathname
|
|
|
|
is a symbolic link, then
|
|
|
|
.BR open ()
|
|
|
|
fails regardless of where the symbolic link points to.
|
|
|
|
|
|
|
|
.B O_EXCL
|
2008-07-22 05:48:27 +00:00
|
|
|
is only supported on NFS when using NFSv3 or later on kernel 2.6 or later.
|
2008-01-03 08:12:02 +00:00
|
|
|
In environments where NFS
|
2004-11-03 13:51:07 +00:00
|
|
|
.B O_EXCL
|
2008-01-03 08:12:02 +00:00
|
|
|
support is not provided, programs that rely on it
|
|
|
|
for performing locking tasks will contain a race condition.
|
|
|
|
Portable programs that want to perform atomic file locking using a lockfile,
|
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR link (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
to make a link to the lockfile.
|
2007-05-12 09:06:04 +00:00
|
|
|
If
|
|
|
|
.BR link (2)
|
2008-01-03 08:12:02 +00:00
|
|
|
returns 0, the lock is successful.
|
2007-04-12 22:42:49 +00:00
|
|
|
Otherwise, use
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR stat (2)
|
|
|
|
on the unique file to check if its link count has increased to 2,
|
|
|
|
in which case the lock is also successful.
|
|
|
|
.TP
|
2004-12-08 16:41:10 +00:00
|
|
|
.B O_LARGEFILE
|
|
|
|
(LFS)
|
|
|
|
Allow files whose sizes cannot be represented in an
|
2005-11-02 13:55:25 +00:00
|
|
|
.I off_t
|
2004-12-08 16:41:10 +00:00
|
|
|
(but can be represented in an
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR off64_t )
|
2004-12-08 16:41:10 +00:00
|
|
|
to be opened.
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
2006-11-25 01:00:24 +00:00
|
|
|
.B _LARGEFILE64_SOURCE
|
|
|
|
macro must be defined in order to obtain this definition.
|
2007-04-12 22:42:49 +00:00
|
|
|
Setting the
|
2006-11-25 01:00:24 +00:00
|
|
|
.B _FILE_OFFSET_BITS
|
2006-11-25 18:35:39 +00:00
|
|
|
feature test macro to 64 (rather than using
|
|
|
|
.BR O_LARGEFILE )
|
|
|
|
is the preferred method of obtaining
|
|
|
|
method of accessing large files on 32-bit systems (see
|
2006-11-25 18:22:22 +00:00
|
|
|
.BR feature_test_macros (7)).
|
2004-12-08 16:41:10 +00:00
|
|
|
.TP
|
2007-09-10 04:34:20 +00:00
|
|
|
.BR O_NOATIME " (Since Linux 2.6.8)"
|
2005-07-19 07:15:17 +00:00
|
|
|
Do not update the file last access time (st_atime in the inode)
|
|
|
|
when the file is
|
2004-12-08 16:41:10 +00:00
|
|
|
.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.
|
2008-03-19 07:26:08 +00:00
|
|
|
This flag may not be effective on all file systems.
|
2004-12-08 16:41:10 +00:00
|
|
|
One example is NFS, where the server maintains the access time.
|
2007-06-13 21:48:16 +00:00
|
|
|
.\" The O_NOATIME flag also affects the treatment of st_atime
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" by mmap() and readdir(2), MTK, Dec 04.
|
2004-12-08 16:41:10 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B O_NOCTTY
|
|
|
|
If
|
|
|
|
.I pathname
|
|
|
|
refers to a terminal device \(em see
|
|
|
|
.BR tty (4)
|
|
|
|
\(em it will not become the process's controlling terminal even if the
|
|
|
|
process does not have one.
|
|
|
|
.TP
|
2004-12-08 16:41:10 +00:00
|
|
|
.B O_NOFOLLOW
|
2007-07-18 20:24:30 +00:00
|
|
|
If \fIpathname\fP is a symbolic link, then the open fails.
|
2007-04-12 22:42:49 +00:00
|
|
|
This is a FreeBSD extension, which was added to Linux in version 2.1.126.
|
2004-12-08 16:41:10 +00:00
|
|
|
Symbolic links in earlier components of the pathname will still be
|
2005-06-22 09:52:33 +00:00
|
|
|
followed.
|
|
|
|
.\" The headers from glibc 2.0.100 and later include a
|
|
|
|
.\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
|
2007-07-18 20:24:30 +00:00
|
|
|
.\" used\fP.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.BR O_NONBLOCK " or " O_NDELAY
|
2007-04-12 22:42:49 +00:00
|
|
|
When possible, the file is opened in non-blocking mode.
|
|
|
|
Neither the
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR open ()
|
2004-11-03 13:51:07 +00:00
|
|
|
nor any subsequent operations on the file descriptor which is
|
|
|
|
returned will cause the calling process to wait.
|
|
|
|
For the handling of FIFOs (named pipes), see also
|
2006-04-21 01:46:04 +00:00
|
|
|
.BR fifo (7).
|
2006-03-31 21:12:45 +00:00
|
|
|
For a discussion of the effect of
|
2007-09-20 16:26:31 +00:00
|
|
|
.B O_NONBLOCK
|
2006-03-31 21:12:45 +00:00
|
|
|
in conjunction with mandatory file locks and with file leases, see
|
|
|
|
.BR fcntl (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B O_SYNC
|
2007-04-12 22:42:49 +00:00
|
|
|
The file is opened for synchronous I/O.
|
|
|
|
Any
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR write (2)s
|
2004-11-03 13:51:07 +00:00
|
|
|
on the resulting file descriptor will block the calling process until
|
|
|
|
the data has been physically written to the underlying hardware.
|
2007-05-16 05:33:35 +00:00
|
|
|
.IR "But see NOTES below" .
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2004-12-08 16:41:10 +00:00
|
|
|
.B O_TRUNC
|
|
|
|
If the file already exists and is a regular file and the open mode allows
|
2007-06-22 17:16:20 +00:00
|
|
|
writing (i.e., is
|
|
|
|
.B O_RDWR
|
|
|
|
or
|
|
|
|
.BR O_WRONLY )
|
|
|
|
it will be truncated to length 0.
|
|
|
|
If the file is a FIFO or terminal device file, the
|
|
|
|
.B O_TRUNC
|
2007-04-12 22:42:49 +00:00
|
|
|
flag is ignored.
|
2007-06-22 17:16:20 +00:00
|
|
|
Otherwise the effect of
|
|
|
|
.B O_TRUNC
|
|
|
|
is unspecified.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Some of these optional flags can be altered using
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR fcntl (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
after the file has been opened.
|
|
|
|
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR creat ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is equivalent to
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR open ()
|
2004-11-03 13:51:07 +00:00
|
|
|
with
|
|
|
|
.I flags
|
|
|
|
equal to
|
|
|
|
.BR O_CREAT|O_WRONLY|O_TRUNC .
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR open ()
|
|
|
|
and
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR creat ()
|
2004-12-08 16:41:10 +00:00
|
|
|
return the new file descriptor, or \-1 if an error occurred
|
|
|
|
(in which case,
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately).
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EACCES
|
|
|
|
The requested access to the file is not allowed, or search permission
|
|
|
|
is denied for one of the directories in the path prefix of
|
|
|
|
.IR pathname ,
|
|
|
|
or the file did not exist yet and write access to the parent directory
|
|
|
|
is not allowed.
|
|
|
|
(See also
|
2007-05-26 12:41:39 +00:00
|
|
|
.BR path_resolution (7).)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EEXIST
|
|
|
|
.I pathname
|
|
|
|
already exists and
|
|
|
|
.BR O_CREAT " and " O_EXCL
|
|
|
|
were used.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
2007-09-20 16:26:31 +00:00
|
|
|
.I pathname
|
2005-10-19 07:29:28 +00:00
|
|
|
points outside your accessible address space.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2007-01-06 23:31:16 +00:00
|
|
|
.B EFBIG
|
2008-12-04 17:25:19 +00:00
|
|
|
See
|
|
|
|
.BR EOVERFLOW .
|
2007-01-06 23:31:16 +00:00
|
|
|
.TP
|
2008-07-04 15:44:19 +00:00
|
|
|
.B EINTR
|
|
|
|
While blocked waiting to complete an open of a slow device
|
|
|
|
(e.g., a FIFO; see
|
|
|
|
.BR fifo (7)),
|
|
|
|
the call was interrupted by a signal handler; see
|
|
|
|
.BR signal (7).
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EISDIR
|
|
|
|
.I pathname
|
|
|
|
refers to a directory and the access requested involved writing
|
|
|
|
(that is,
|
|
|
|
.B O_WRONLY
|
|
|
|
or
|
|
|
|
.B O_RDWR
|
|
|
|
is set).
|
|
|
|
.TP
|
|
|
|
.B ELOOP
|
|
|
|
Too many symbolic links were encountered in resolving
|
|
|
|
.IR pathname ,
|
2007-07-18 20:24:30 +00:00
|
|
|
or \fBO_NOFOLLOW\fP was specified but
|
2004-11-03 13:51:07 +00:00
|
|
|
.I pathname
|
|
|
|
was a symbolic link.
|
|
|
|
.TP
|
|
|
|
.B EMFILE
|
|
|
|
The process already has the maximum number of files open.
|
|
|
|
.TP
|
|
|
|
.B ENAMETOOLONG
|
2007-09-20 16:26:31 +00:00
|
|
|
.I pathname
|
2005-10-19 07:29:28 +00:00
|
|
|
was too long.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENFILE
|
|
|
|
The system limit on the total number of open files has been reached.
|
|
|
|
.TP
|
|
|
|
.B ENODEV
|
|
|
|
.I pathname
|
|
|
|
refers to a device special file and no corresponding device exists.
|
2007-06-22 17:16:20 +00:00
|
|
|
(This is a Linux kernel bug; in this situation
|
|
|
|
.B ENXIO
|
|
|
|
must be returned.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENOENT
|
2007-06-22 17:16:20 +00:00
|
|
|
.B O_CREAT
|
|
|
|
is not set and the named file does not exist.
|
2004-11-03 13:51:07 +00:00
|
|
|
Or, a directory component in
|
|
|
|
.I pathname
|
|
|
|
does not exist or is a dangling symbolic link.
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Insufficient kernel memory was available.
|
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
.I pathname
|
|
|
|
was to be created but the device containing
|
|
|
|
.I pathname
|
|
|
|
has no room for the new file.
|
|
|
|
.TP
|
|
|
|
.B ENOTDIR
|
|
|
|
A component used as a directory in
|
|
|
|
.I pathname
|
2007-07-18 20:24:30 +00:00
|
|
|
is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I pathname
|
|
|
|
was not a directory.
|
|
|
|
.TP
|
|
|
|
.B ENXIO
|
2007-06-22 17:16:20 +00:00
|
|
|
.BR O_NONBLOCK " | " O_WRONLY
|
|
|
|
is set, the named file is a FIFO and
|
2004-11-03 13:51:07 +00:00
|
|
|
no process has the file open for reading.
|
|
|
|
Or, the file is a device special file and no corresponding device exists.
|
|
|
|
.TP
|
2008-12-04 17:25:19 +00:00
|
|
|
.B EOVERFLOW
|
|
|
|
.I pathname
|
|
|
|
refers to a regular file that is too large to be opened.
|
|
|
|
The usual scenario here is that an application compiled
|
|
|
|
on a 32-bit platform without
|
2008-12-04 20:46:28 +00:00
|
|
|
.I -D_FILE_OFFSET_BITS=64
|
2008-12-04 17:25:19 +00:00
|
|
|
tried to open a file whose size exceeds
|
|
|
|
.I (2<<31)-1
|
|
|
|
bits;
|
|
|
|
see also
|
|
|
|
.B O_LARGEFILE
|
|
|
|
above.
|
|
|
|
This is the error specified by POSIX.1-2001;
|
|
|
|
in kernels before 2.6.24, Linux gave the error
|
|
|
|
.B EFBIG
|
|
|
|
for this case.
|
|
|
|
.\" 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
|
|
|
|
.TP
|
2004-12-08 16:41:10 +00:00
|
|
|
.B EPERM
|
|
|
|
The
|
|
|
|
.B O_NOATIME
|
|
|
|
flag was specified, but the effective user ID of the caller
|
|
|
|
.\" Strictly speaking, it's the file system UID... (MTK)
|
|
|
|
did not match the owner of the file and the caller was not privileged
|
|
|
|
.RB ( CAP_FOWNER ).
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EROFS
|
|
|
|
.I pathname
|
2008-03-19 07:26:08 +00:00
|
|
|
refers to a file on a read-only file system and write access was
|
2004-11-03 13:51:07 +00:00
|
|
|
requested.
|
|
|
|
.TP
|
|
|
|
.B ETXTBSY
|
|
|
|
.I pathname
|
|
|
|
refers to an executable image which is currently being executed and
|
|
|
|
write access was requested.
|
2005-11-17 14:55:31 +00:00
|
|
|
.TP
|
|
|
|
.B EWOULDBLOCK
|
|
|
|
The
|
|
|
|
.B O_NONBLOCK
|
|
|
|
flag was specified, and an incompatible lease was held on the file
|
|
|
|
(see
|
|
|
|
.BR fcntl (2)).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:17 +00:00
|
|
|
SVr4, 4.3BSD, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
2007-09-10 04:34:20 +00:00
|
|
|
.BR O_DIRECTORY ,
|
2004-12-08 16:41:10 +00:00
|
|
|
.BR O_NOATIME ,
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2007-09-20 16:26:31 +00:00
|
|
|
.B O_NOFOLLOW
|
2008-04-08 11:28:12 +00:00
|
|
|
flags are Linux-specific, and one may need to define
|
2008-05-12 14:30:24 +00:00
|
|
|
.B _GNU_SOURCE
|
|
|
|
to obtain their definitions.
|
2008-04-08 11:28:12 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.BR O_CLOEXEC
|
|
|
|
flag is not specified in POSIX.1-2001,
|
2008-11-04 13:51:26 +00:00
|
|
|
but is specified in POSIX.1-2008.
|
2008-04-08 11:28:12 +00:00
|
|
|
|
2007-09-20 16:26:31 +00:00
|
|
|
.B O_DIRECT
|
2007-09-19 21:42:14 +00:00
|
|
|
is not specified in POSIX; one has to define
|
2007-09-10 04:34:20 +00:00
|
|
|
.B _GNU_SOURCE
|
|
|
|
to get its definition.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH NOTES
|
2007-06-21 22:55:04 +00:00
|
|
|
Under Linux, the
|
2007-05-18 16:06:42 +00:00
|
|
|
.B O_NONBLOCK
|
|
|
|
flag indicates that one wants to open
|
|
|
|
but does not necessarily have the intention to read or write.
|
|
|
|
This is typically used to open devices in order to get a file descriptor
|
|
|
|
for use with
|
|
|
|
.BR ioctl (2).
|
2008-06-11 22:04:37 +00:00
|
|
|
|
|
|
|
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, non-standard 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 non-standard 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
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
The (undefined) effect of
|
|
|
|
.B O_RDONLY | O_TRUNC
|
2007-04-12 22:42:49 +00:00
|
|
|
varies among implementations.
|
2006-11-25 01:00:24 +00:00
|
|
|
On many systems the file is actually truncated.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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
|
2007-05-18 16:06:42 +00:00
|
|
|
.PP
|
|
|
|
There are many infelicities in the protocol underlying NFS, affecting
|
|
|
|
amongst others
|
|
|
|
.BR O_SYNC " and " O_NDELAY .
|
|
|
|
|
2007-06-08 09:56:56 +00:00
|
|
|
POSIX provides for three different variants of synchronized I/O,
|
2009-09-20 05:41:16 +00:00
|
|
|
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 filesystems 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.
|
2007-05-18 16:06:42 +00:00
|
|
|
|
|
|
|
Note that
|
|
|
|
.BR open ()
|
|
|
|
can open device special files, but
|
|
|
|
.BR creat ()
|
|
|
|
cannot create them; use
|
|
|
|
.BR mknod (2)
|
|
|
|
instead.
|
|
|
|
.LP
|
|
|
|
On NFS file systems with UID mapping enabled,
|
|
|
|
.BR open ()
|
|
|
|
may
|
2007-06-08 11:56:22 +00:00
|
|
|
return a file descriptor but, for example,
|
2007-05-18 16:06:42 +00:00
|
|
|
.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
|
2007-06-21 22:55:04 +00:00
|
|
|
.IR st_atime ,
|
2007-05-18 16:06:42 +00:00
|
|
|
.IR st_ctime ,
|
|
|
|
.I st_mtime
|
|
|
|
fields
|
|
|
|
(respectively, time of last access, time of last status change, and
|
|
|
|
time of last modification; see
|
|
|
|
.BR stat (2))
|
|
|
|
are set
|
|
|
|
to the current time, and so are the
|
|
|
|
.I st_ctime
|
2007-06-21 22:55:04 +00:00
|
|
|
and
|
2007-05-18 16:06:42 +00:00
|
|
|
.I st_mtime
|
|
|
|
fields of the
|
|
|
|
parent directory.
|
2007-06-21 22:55:04 +00:00
|
|
|
Otherwise, if the file is modified because of the
|
2007-05-18 16:06:42 +00:00
|
|
|
.B O_TRUNC
|
|
|
|
flag, its st_ctime and st_mtime fields are set to the current time.
|
2008-02-11 10:38:24 +00:00
|
|
|
.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.
|
|
|
|
In Linux alignment
|
2008-03-19 07:26:08 +00:00
|
|
|
restrictions vary by file system and kernel version and might be
|
2008-02-11 10:38:24 +00:00
|
|
|
absent entirely.
|
2008-03-19 07:26:08 +00:00
|
|
|
However there is currently no file system\-independent
|
2008-02-11 10:38:24 +00:00
|
|
|
interface for an application to discover these restrictions for a given
|
2008-03-19 07:26:08 +00:00
|
|
|
file or file system.
|
|
|
|
Some file systems provide their own interfaces
|
2008-02-11 10:38:24 +00:00
|
|
|
for doing so, for example the
|
|
|
|
.B XFS_IOC_DIOINFO
|
|
|
|
operation in
|
|
|
|
.BR xfsctl (3).
|
|
|
|
.LP
|
2008-11-14 18:58:09 +00:00
|
|
|
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
|
2008-02-11 10:38:24 +00:00
|
|
|
of the file system.
|
|
|
|
Under Linux 2.6, alignment to 512-byte boundaries
|
|
|
|
suffices.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
.B O_DIRECT
|
|
|
|
flag was introduced in SGI IRIX, where it has alignment
|
|
|
|
restrictions similar to those of Linux 2.4.
|
|
|
|
IRIX has also a
|
|
|
|
.BR fcntl (2)
|
|
|
|
call to query appropriate alignments, and sizes.
|
|
|
|
FreeBSD 4.x introduced
|
|
|
|
a flag of the same name, but without alignment restrictions.
|
|
|
|
.LP
|
|
|
|
.B O_DIRECT
|
|
|
|
support was added under Linux in kernel version 2.4.10.
|
|
|
|
Older Linux kernels simply ignore this flag.
|
2008-03-19 07:26:08 +00:00
|
|
|
Some file systems may not implement the flag and
|
2008-02-11 10:38:24 +00:00
|
|
|
.BR open ()
|
|
|
|
will fail with
|
|
|
|
.B EINVAL
|
|
|
|
if it is used.
|
|
|
|
.LP
|
|
|
|
Applications should avoid mixing
|
|
|
|
.B O_DIRECT
|
|
|
|
and normal I/O to the same file,
|
|
|
|
and especially to overlapping byte regions in the same file.
|
2008-03-19 07:26:08 +00:00
|
|
|
Even when the file system correctly handles the coherency issues in
|
2008-02-11 10:38:24 +00:00
|
|
|
this situation, overall I/O throughput is likely to be slower than
|
|
|
|
using either mode alone.
|
|
|
|
Likewise, applications should avoid mixing
|
|
|
|
.BR mmap (2)
|
|
|
|
of files with direct I/O to the same files.
|
|
|
|
.LP
|
|
|
|
The behaviour of
|
|
|
|
.B O_DIRECT
|
2008-03-19 07:26:08 +00:00
|
|
|
with NFS will differ from local file systems.
|
2008-02-11 10:38:24 +00:00
|
|
|
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
|
|
|
|
still cache the I/O.
|
|
|
|
The client asks the server to make the I/O
|
|
|
|
synchronous to preserve the synchronous semantics of
|
|
|
|
.BR O_DIRECT .
|
|
|
|
Some servers will perform poorly under these circumstances, especially
|
|
|
|
if the I/O size is small.
|
|
|
|
Some servers may also be configured to
|
|
|
|
lie to clients about the I/O having reached stable storage; this
|
|
|
|
will avoid the performance penalty at some risk to data integrity
|
|
|
|
in the event of server power failure.
|
|
|
|
The Linux NFS client places no alignment restrictions on
|
|
|
|
.B O_DIRECT
|
|
|
|
I/O.
|
|
|
|
.PP
|
|
|
|
In summary,
|
|
|
|
.B O_DIRECT
|
|
|
|
is a potentially powerful tool that should be used with caution.
|
|
|
|
It is recommended that applications treat use of
|
|
|
|
.B O_DIRECT
|
|
|
|
as a performance option which is disabled by default.
|
|
|
|
.PP
|
|
|
|
.RS
|
2004-11-03 13:51:07 +00:00
|
|
|
"The thing that has always disturbed me about O_DIRECT is that the whole
|
|
|
|
interface is just stupid, and was probably designed by a deranged monkey
|
2005-07-06 06:54:27 +00:00
|
|
|
on some serious mind-controlling substances." \(em Linus
|
2008-02-11 10:38:24 +00:00
|
|
|
.RE
|
|
|
|
.SH BUGS
|
2006-01-15 04:39:23 +00:00
|
|
|
Currently, it is not possible to enable signal-driven
|
|
|
|
I/O by specifying
|
|
|
|
.B O_ASYNC
|
2007-04-12 22:42:49 +00:00
|
|
|
when calling
|
2006-01-15 04:39:23 +00:00
|
|
|
.BR open ();
|
|
|
|
use
|
|
|
|
.BR fcntl (2)
|
|
|
|
to enable this flag.
|
2007-06-13 21:48:16 +00:00
|
|
|
.\" FIXME . Check bugzilla report on open(O_ASYNC)
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2008-05-13 11:29:39 +00:00
|
|
|
.BR chmod (2),
|
|
|
|
.BR chown (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR close (2),
|
2005-06-22 09:52:33 +00:00
|
|
|
.BR dup (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR fcntl (2),
|
|
|
|
.BR link (2),
|
2005-06-21 10:04:56 +00:00
|
|
|
.BR lseek (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR mknod (2),
|
2005-06-22 09:52:33 +00:00
|
|
|
.BR mmap (2),
|
2008-07-14 15:52:21 +00:00
|
|
|
.BR mount (2),
|
2006-03-06 04:36:33 +00:00
|
|
|
.BR openat (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR read (2),
|
|
|
|
.BR socket (2),
|
|
|
|
.BR stat (2),
|
|
|
|
.BR umask (2),
|
|
|
|
.BR unlink (2),
|
|
|
|
.BR write (2),
|
|
|
|
.BR fopen (3),
|
2007-05-26 12:41:39 +00:00
|
|
|
.BR feature_test_macros (7),
|
2008-07-14 15:52:21 +00:00
|
|
|
.BR fifo (7),
|
2008-06-11 21:50:53 +00:00
|
|
|
.BR path_resolution (7),
|
|
|
|
.BR symlink (7)
|