OPEN(2) Linux Programmer's Manual OPEN(2) NNAAMMEE open, openat, creat - open and possibly create a file SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> iinntt ooppeenn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _f_l_a_g_s));; iinntt ooppeenn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _f_l_a_g_s,, mmooddee__tt _m_o_d_e));; iinntt ccrreeaatt((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, mmooddee__tt _m_o_d_e));; iinntt ooppeennaatt((iinntt _d_i_r_f_d,, ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _f_l_a_g_s));; iinntt ooppeennaatt((iinntt _d_i_r_f_d,, ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _f_l_a_g_s,, mmooddee__tt _m_o_d_e));; Feature Test Macro Requirements for glibc (see ffeeaattuurree__tteesstt__mmaaccrrooss(7)): ooppeennaatt(): Since glibc 2.10: _POSIX_C_SOURCE >= 200809L Before glibc 2.10: _ATFILE_SOURCE DDEESSCCRRIIPPTTIIOONN The ooppeenn() system call opens the file specified by _p_a_t_h_n_a_m_e. If the specified file does not exist, it may optionally (if OO__CCRREEAATT is specified in _f_l_a_g_s) be created by ooppeenn(). The return value of ooppeenn() is a file descriptor, a small, nonnegative integer that is used in subsequent system calls (rreeaadd(2), wwrriittee(2), llsseeeekk(2), ffccnnttll(2), etc.) to refer to the open file. The file descriptor returned by a successful call will be the low‐ est-numbered file descriptor not currently open for the process. By default, the new file descriptor is set to remain open across an eexxeeccvvee(2) (i.e., the FFDD__CCLLOOEEXXEECC file descriptor flag described in ffccnnttll(2) is initially disabled); the OO__CCLLOOEEXXEECC flag, described below, can be used to change this default. The file offset is set to the beginning of the file (see llsseeeekk(2)). A call to ooppeenn() creates a new _o_p_e_n _f_i_l_e _d_e_s_c_r_i_p_t_i_o_n, an entry in the system-wide table of open files. The open file description records the file offset and the file status flags (see below). A file descriptor is a reference to an open file description; this reference is unaffected if _p_a_t_h_n_a_m_e is subsequently removed or modified to refer to a different file. For further details on open file descriptions, see NOTES. The argument _f_l_a_g_s must include one of the following _a_c_c_e_s_s _m_o_d_e_s: OO__RRDDOONNLLYY, OO__WWRROONNLLYY, or OO__RRDDWWRR. These request opening the file read-only, write-only, or read/write, respectively. In addition, zero or more file creation flags and file status flags can be bitwise-_o_r'd in _f_l_a_g_s. The _f_i_l_e _c_r_e_a_t_i_o_n _f_l_a_g_s are OO__CCLLOOEEXXEECC, OO__CCRREEAATT, OO__DDIIRREECCTTOORRYY, OO__EEXXCCLL, OO__NNOOCCTTTTYY, OO__NNOOFFOOLLLLOOWW, OO__TTMMPPFFIILLEE, and OO__TTRRUUNNCC. The _f_i_l_e _s_t_a_t_u_s _f_l_a_g_s are all of the re‐ maining flags listed below. The distinction between these two groups of flags is that the file creation flags affect the seman‐ tics 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 ffccnnttll(2) for details. The full list of file creation flags and file status flags is as follows: OO__AAPPPPEENNDD The file is opened in append mode. Before each wwrriittee(2), the file offset is positioned at the end of the file, as if with llsseeeekk(2). The modification of the file offset and the write operation are performed as a single atomic step. OO__AAPPPPEENNDD 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. OO__AASSYYNNCC Enable signal-driven I/O: generate a signal (SSIIGGIIOO by default, but this can be changed via ffccnnttll(2)) when input or output becomes possible on this file descriptor. This feature is available only for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See ffccnnttll(2) for further details. See also BUGS, below. OO__CCLLOOEEXXEECC (since Linux 2.6.23) Enable the close-on-exec flag for the new file descriptor. Specifying this flag permits a program to avoid additional ffcc‐‐ nnttll(2) FF__SSEETTFFDD operations to set the FFDD__CCLLOOEEXXEECC flag. Note that the use of this flag is essential in some multithreaded programs, because using a separate ffccnnttll(2) FF__SSEETTFFDD oper‐ ation to set the FFDD__CCLLOOEEXXEECC flag does not suffice to avoid race conditions where one thread opens a file descriptor and at‐ tempts to set its close-on-exec flag using ffccnnttll(2) at the same time as another thread does a ffoorrkk(2) plus eexxeeccvvee(2). De‐ pending on the order of execution, the race may lead to the file descriptor returned by ooppeenn() being unintentionally leaked to the program executed by the child process created by ffoorrkk(2). (This kind of race is in principle possible for any sys‐ tem call that creates a file descriptor whose close-on-exec flag should be set, and various other Linux system calls pro‐ vide an equivalent of the OO__CCLLOOEEXXEECC flag to deal with this problem.) OO__CCRREEAATT If _p_a_t_h_n_a_m_e does not exist, create it as a regular file. The owner (user ID) of the new file is set to the effective user ID of the process. The group ownership (group ID) of the new file is set either to the effective group ID of the process (System V semantics) or to the group ID of the parent directory (BSD semantics). On Linux, the behavior depends on whether the set-group-ID mode bit is set on the parent directory: if that bit is set, then BSD semantics apply; otherwise, System V semantics apply. For some filesystems, the behavior also depends on the _b_s_d_g_r_o_u_p_s and _s_y_s_v_g_r_o_u_p_s mount options described in mmoouunntt(8)). The _m_o_d_e argument specifies the file mode bits be applied when a new file is created. This argument must be supplied when OO__CCRREEAATT or OO__TTMMPPFFIILLEE is specified in _f_l_a_g_s; if neither OO__CCRREEAATT nor OO__TTMMPPFFIILLEE is specified, then _m_o_d_e is ignored. The ef‐ fective mode is modified by the process's _u_m_a_s_k in the usual way: in the absence of a default ACL, the mode of the created file is _(_m_o_d_e _& _~_u_m_a_s_k_). Note that this mode applies only to future accesses of the newly created file; the ooppeenn() call that creates a read-only file may well return a read/write file descriptor. The following symbolic constants are provided for _m_o_d_e: SS__IIRRWWXXUU 00700 user (file owner) has read, write, and execute permission SS__IIRRUUSSRR 00400 user has read permission SS__IIWWUUSSRR 00200 user has write permission SS__IIXXUUSSRR 00100 user has execute permission SS__IIRRWWXXGG 00070 group has read, write, and execute permission SS__IIRRGGRRPP 00040 group has read permission SS__IIWWGGRRPP 00020 group has write permission SS__IIXXGGRRPP 00010 group has execute permission SS__IIRRWWXXOO 00007 others have read, write, and execute permission SS__IIRROOTTHH 00004 others have read permission SS__IIWWOOTTHH 00002 others have write permission SS__IIXXOOTTHH 00001 others have execute permission According to POSIX, the effect when other bits are set in _m_o_d_e is unspecified. On Linux, the following bits are also hon‐ ored in _m_o_d_e: SS__IISSUUIIDD 0004000 set-user-ID bit SS__IISSGGIIDD 0002000 set-group-ID bit (see iinnooddee(7)). SS__IISSVVTTXX 0001000 sticky bit (see iinnooddee(7)). OO__DDIIRREECCTT (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 buf‐ fers. The OO__DDIIRREECCTT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the OO__SSYYNNCC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, OO__SSYYNNCC must be used in addi‐ tion to OO__DDIIRREECCTT. See NOTES below for further discussion. A semantically similar (but deprecated) interface for block devices is described in rraaww(8). OO__DDIIRREECCTTOORRYY If _p_a_t_h_n_a_m_e is not a directory, cause the open to fail. This flag was added in kernel version 2.1.126, to avoid denial-of- service problems if ooppeennddiirr(3) is called on a FIFO or tape device. OO__DDSSYYNNCC Write operations on the file will complete according to the requirements of synchronized I/O _d_a_t_a integrity completion. By the time wwrriittee(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 wwrriittee(2) was followed by a call to ffddaattaa‐‐ ssyynncc(2)). _S_e_e _N_O_T_E_S _b_e_l_o_w. OO__EEXXCCLL Ensure that this call creates the file: if this flag is specified in conjunction with OO__CCRREEAATT, and _p_a_t_h_n_a_m_e already exists, then ooppeenn() fails with the error EEEEXXIISSTT. When these two flags are specified, symbolic links are not followed: if _p_a_t_h_n_a_m_e is a symbolic link, then ooppeenn() fails re‐ gardless of where the symbolic link points. In general, the behavior of OO__EEXXCCLL is undefined if it is used without OO__CCRREEAATT. There is one exception: on Linux 2.6 and later, OO__EEXXCCLL can be used without OO__CCRREEAATT if _p_a_t_h_n_a_m_e refers to a block device. If the block device is in use by the sys‐ tem (e.g., mounted), ooppeenn() fails with the error EEBBUUSSYY. On NFS, OO__EEXXCCLL is supported only when using NFSv3 or later on kernel 2.6 or later. In NFS environments where OO__EEXXCCLL sup‐ port is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable pro‐ grams that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for OO__EEXXCCLL, can create a unique file on the same filesystem (e.g., incorporating hostname and PID), and use lliinnkk(2) to make a link to the lockfile. If lliinnkk(2) returns 0, the lock is successful. Otherwise, use ssttaatt(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful. OO__LLAARRGGEEFFIILLEE (LFS) Allow files whose sizes cannot be represented in an _o_f_f___t (but can be represented in an _o_f_f_6_4___t) to be opened. The __LLAARRGGEEFFIILLEE6644__SSOOUURRCCEE macro must be defined (before including _a_n_y header files) in order to obtain this definition. Setting the __FFIILLEE__OOFFFFSSEETT__BBIITTSS feature test macro to 64 (rather than using OO__LLAARRGGEEFFIILLEE) is the preferred method of accessing large files on 32-bit systems (see ffeeaattuurree__tteesstt__mmaaccrrooss(7)). OO__NNOOAATTIIMMEE (since Linux 2.6.8) Do not update the file last access time (_s_t___a_t_i_m_e in the inode) when the file is rreeaadd(2). This flag can be employed only if one of the following conditions is true: * The effective UID of the process matches the owner UID of the file. * The calling process has the CCAAPP__FFOOWWNNEERR capability in its user namespace and the owner UID of the file has a mapping in the namespace. This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk ac‐ tivity. This flag may not be effective on all filesystems. One example is NFS, where the server maintains the access time. OO__NNOOCCTTTTYY If _p_a_t_h_n_a_m_e refers to a terminal device—see ttttyy(4)—it will not become the process's controlling terminal even if the process does not have one. OO__NNOOFFOOLLLLOOWW If _p_a_t_h_n_a_m_e is a symbolic link, then the open fails, with the error EELLOOOOPP. Symbolic links in earlier components of the pathname will still be followed. (Note that the EELLOOOOPP error that can occur in this case is indistinguishable from the case where an open fails because there are too many symbolic links found while resolving components in the prefix part of the pathname.) This flag is a FreeBSD extension, which was added to Linux in version 2.1.126, and has subsequently been standardized in POSIX.1-2008. See also OO__PPAATTHH below. OO__NNOONNBBLLOOCCKK or OO__NNDDEELLAAYY When possible, the file is opened in nonblocking mode. Neither the ooppeenn() nor any subsequent operations on the file de‐ scriptor which is returned will cause the calling process to wait. 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 OO__NNOONNBBLLOOCCKK is set. Since OO__NNOONNBBLLOOCCKK semantics might eventually be im‐ plemented, applications should not depend upon blocking behavior when specifying this flag for regular files and block de‐ vices. For the handling of FIFOs (named pipes), see also ffiiffoo(7). For a discussion of the effect of OO__NNOONNBBLLOOCCKK in conjunction with mandatory file locks and with file leases, see ffccnnttll(2). OO__PPAATTHH (since Linux 2.6.39) 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., rreeaadd(2), wwrriittee(2), ffcchhmmoodd(2), ffcchhoowwnn(2), ffggeettxxaattttrr(2), iiooccttll(2), mmmmaapp(2)) fail with the error EEBBAADDFF. The following operations _c_a_n be performed on the resulting file descriptor: * cclloossee(2). * ffcchhddiirr(2), if the file descriptor refers to a directory (since Linux 3.5). * ffssttaatt(2) (since Linux 3.6). * ffssttaattffss(2) (since Linux 3.12). * Duplicating the file descriptor (dduupp(2), ffccnnttll(2) FF__DDUUPPFFDD, etc.). * Getting and setting file descriptor flags (ffccnnttll(2) FF__GGEETTFFDD and FF__SSEETTFFDD). * Retrieving open file status flags using the ffccnnttll(2) FF__GGEETTFFLL operation: the returned flags will include the bit OO__PPAATTHH. * Passing the file descriptor as the _d_i_r_f_d argument of ooppeennaatt() and the other "*at()" system calls. This includes lliinnkkaatt(2) with AATT__EEMMPPTTYY__PPAATTHH (or via procfs using AATT__SSYYMMLLIINNKK__FFOOLLLLOOWW) even if the file is not a directory. * Passing the file descriptor to another process via a UNIX domain socket (see SSCCMM__RRIIGGHHTTSS in uunniixx(7)). When OO__PPAATTHH is specified in _f_l_a_g_s, flag bits other than OO__CCLLOOEEXXEECC, OO__DDIIRREECCTTOORRYY, and OO__NNOOFFOOLLLLOOWW are ignored. Opening a file or directory with the OO__PPAATTHH 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 per‐ missions may be performed (e.g., ffcchhddiirr(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 OO__RRDDOONNLLYY flag requires that the caller have read permission on the object, even when the subsequent operation (e.g., ffcchhddiirr(2), ffssttaatt(2)) does not re‐ quire read permission on the object. If _p_a_t_h_n_a_m_e is a symbolic link and the OO__NNOOFFOOLLLLOOWW flag is also specified, then the call returns a file descriptor referring to the symbolic link. This file descriptor can be used as the _d_i_r_f_d argument in calls to ffcchhoowwnnaatt(2), ffssttaattaatt(2), lliinnkkaatt(2), and rreeaaddlliinnkkaatt(2) with an empty pathname to have the calls operate on the symbolic link. If _p_a_t_h_n_a_m_e 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. ffssttaattffss(2) can then be used to determine if it is, in fact, an untriggered automount point (..ff__ttyyppee ==== AAUUTTOOFFSS__SSUUPPEERR__MMAAGGIICC). One use of OO__PPAATTHH for regular files is to provide the equivalent of POSIX.1's OO__EEXXEECC functionality. This permits us to open a file for which we have execute permission but not read permission, and then execute that file, with steps something like the following: char buf[PATH_MAX]; fd = open("some_prog", O_PATH); snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd); execl(buf, "some_prog", (char *) NULL); An OO__PPAATTHH file descriptor can also be passed as the argument of ffeexxeeccvvee(3). OO__SSYYNNCC Write operations on the file will complete according to the requirements of synchronized I/O _f_i_l_e integrity completion (by contrast with the synchronized I/O _d_a_t_a integrity completion provided by OO__DDSSYYNNCC.) By the time wwrriittee(2) (or similar) returns, the output data and associated file metadata have been transferred to the under‐ lying hardware (i.e., as though each wwrriittee(2) was followed by a call to ffssyynncc(2)). _S_e_e _N_O_T_E_S _b_e_l_o_w. OO__TTMMPPFFIILLEE (since Linux 3.11) Create an unnamed temporary regular file. The _p_a_t_h_n_a_m_e 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. OO__TTMMPPFFIILLEE must be specified with one of OO__RRDDWWRR or OO__WWRROONNLLYY and, optionally, OO__EEXXCCLL. If OO__EEXXCCLL is not specified, then lliinnkkaatt(2) can be used to link the temporary file into the filesystem, making it permanent, using code like the following: 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); In this case, the ooppeenn() _m_o_d_e argument determines the file permission mode, as with OO__CCRREEAATT. Specifying OO__EEXXCCLL in conjunction with OO__TTMMPPFFIILLEE prevents a temporary file from being linked into the filesystem in the above manner. (Note that the meaning of OO__EEXXCCLL in this case is different from the meaning of OO__EEXXCCLL otherwise.) There are two main use cases for OO__TTMMPPFFIILLEE: * Improved ttmmppffiillee(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. * Creating a file that is initially invisible, which is then populated with data and adjusted to have appropriate filesys‐ tem attributes (ffcchhoowwnn(2), ffcchhmmoodd(2), ffsseettxxaattttrr(2), etc.) before being atomically linked into the filesystem in a fully formed state (using lliinnkkaatt(2) as described above). OO__TTMMPPFFIILLEE 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) OO__TTRRUUNNCC If the file already exists and is a regular file and the access mode allows writing (i.e., is OO__RRDDWWRR or OO__WWRROONNLLYY) it will be truncated to length 0. If the file is a FIFO or terminal device file, the OO__TTRRUUNNCC flag is ignored. Otherwise, the ef‐ fect of OO__TTRRUUNNCC is unspecified. ccrreeaatt(()) A call to ccrreeaatt() is equivalent to calling ooppeenn() with _f_l_a_g_s equal to OO__CCRREEAATT||OO__WWRROONNLLYY||OO__TTRRUUNNCC. ooppeennaatt(()) The ooppeennaatt() system call operates in exactly the same way as ooppeenn(), except for the differences described here. If the pathname given in _p_a_t_h_n_a_m_e is relative, then it is interpreted relative to the directory referred to by the file descriptor _d_i_r_f_d (rather than relative to the current working directory of the calling process, as is done by ooppeenn() for a relative path‐ name). If _p_a_t_h_n_a_m_e is relative and _d_i_r_f_d is the special value AATT__FFDDCCWWDD, then _p_a_t_h_n_a_m_e is interpreted relative to the current working di‐ rectory of the calling process (like ooppeenn()). If _p_a_t_h_n_a_m_e is absolute, then _d_i_r_f_d is ignored. RREETTUURRNN VVAALLUUEE ooppeenn(), ooppeennaatt(), and ccrreeaatt() return the new file descriptor, or -1 if an error occurred (in which case, _e_r_r_n_o is set appropri‐ ately). EERRRROORRSS ooppeenn(), ooppeennaatt(), and ccrreeaatt() can fail with the following errors: EEAACCCCEESS The requested access to the file is not allowed, or search permission is denied for one of the directories in the path pre‐ fix of _p_a_t_h_n_a_m_e, or the file did not exist yet and write access to the parent directory is not allowed. (See also ppaatthh__rreessoolluuttiioonn(7).) EEDDQQUUOOTT Where OO__CCRREEAATT is specified, the file does not exist, and the user's quota of disk blocks or inodes on the filesystem has been exhausted. EEEEXXIISSTT _p_a_t_h_n_a_m_e already exists and OO__CCRREEAATT and OO__EEXXCCLL were used. EEFFAAUULLTT _p_a_t_h_n_a_m_e points outside your accessible address space. EEFFBBIIGG See EEOOVVEERRFFLLOOWW. EEIINNTTRR While blocked waiting to complete an open of a slow device (e.g., a FIFO; see ffiiffoo(7)), the call was interrupted by a sig‐ nal handler; see ssiiggnnaall(7). EEIINNVVAALL The filesystem does not support the OO__DDIIRREECCTT flag. See NNOOTTEESS for more information. EEIINNVVAALL Invalid value in _f_l_a_g_s. EEIINNVVAALL OO__TTMMPPFFIILLEE was specified in _f_l_a_g_s, but neither OO__WWRROONNLLYY nor OO__RRDDWWRR was specified. EEIINNVVAALL OO__CCRREEAATT was specified in _f_l_a_g_s and the final component ("basename") of the new file's _p_a_t_h_n_a_m_e is invalid (e.g., it con‐ tains characters not permitted by the underlying filesystem). EEIISSDDIIRR _p_a_t_h_n_a_m_e refers to a directory and the access requested involved writing (that is, OO__WWRROONNLLYY or OO__RRDDWWRR is set). EEIISSDDIIRR _p_a_t_h_n_a_m_e refers to an existing directory, OO__TTMMPPFFIILLEE and one of OO__WWRROONNLLYY or OO__RRDDWWRR were specified in _f_l_a_g_s, but this kernel version does not provide the OO__TTMMPPFFIILLEE functionality. EELLOOOOPP Too many symbolic links were encountered in resolving _p_a_t_h_n_a_m_e. EELLOOOOPP _p_a_t_h_n_a_m_e was a symbolic link, and _f_l_a_g_s specified OO__NNOOFFOOLLLLOOWW but not OO__PPAATTHH. EEMMFFIILLEE The per-process limit on the number of open file descriptors has been reached (see the description of RRLLIIMMIITT__NNOOFFIILLEE in ggeettrrlliimmiitt(2)). EENNAAMMEETTOOOOLLOONNGG _p_a_t_h_n_a_m_e was too long. EENNFFIILLEE The system-wide limit on the total number of open files has been reached. EENNOODDEEVV _p_a_t_h_n_a_m_e refers to a device special file and no corresponding device exists. (This is a Linux kernel bug; in this situa‐ tion EENNXXIIOO must be returned.) EENNOOEENNTT OO__CCRREEAATT is not set and the named file does not exist. Or, a directory component in _p_a_t_h_n_a_m_e does not exist or is a dan‐ gling symbolic link. EENNOOEENNTT _p_a_t_h_n_a_m_e refers to a nonexistent directory, OO__TTMMPPFFIILLEE and one of OO__WWRROONNLLYY or OO__RRDDWWRR were specified in _f_l_a_g_s, but this ker‐ nel version does not provide the OO__TTMMPPFFIILLEE functionality. EENNOOMMEEMM The named file is a FIFO, but memory for the FIFO buffer can't be allocated because the per-user hard limit on memory allo‐ cation for pipes has been reached and the caller is not privileged; see ppiippee(7). EENNOOMMEEMM Insufficient kernel memory was available. EENNOOSSPPCC _p_a_t_h_n_a_m_e was to be created but the device containing _p_a_t_h_n_a_m_e has no room for the new file. EENNOOTTDDIIRR A component used as a directory in _p_a_t_h_n_a_m_e is not, in fact, a directory, or OO__DDIIRREECCTTOORRYY was specified and _p_a_t_h_n_a_m_e was not a directory. EENNXXIIOO OO__NNOONNBBLLOOCCKK | OO__WWRROONNLLYY is set, the named file is a FIFO, and no process has the FIFO open for reading. EENNXXIIOO The file is a device special file and no corresponding device exists. EEOOPPNNOOTTSSUUPPPP The filesystem containing _p_a_t_h_n_a_m_e does not support OO__TTMMPPFFIILLEE. EEOOVVEERRFFLLOOWW _p_a_t_h_n_a_m_e 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 _-_D___F_I_L_E___O_F_F_S_E_T___B_I_T_S_=_6_4 tried to open a file whose size exceeds _(_1_<_<_3_1_)_-_1 bytes; see also OO__LLAARRGGEEFFIILLEE above. This is the error specified by POSIX.1; in kernels before 2.6.24, Linux gave the error EEFFBBIIGG for this case. EEPPEERRMM The OO__NNOOAATTIIMMEE flag was specified, but the effective user ID of the caller did not match the owner of the file and the caller was not privileged. EEPPEERRMM The operation was prevented by a file seal; see ffccnnttll(2). EERROOFFSS _p_a_t_h_n_a_m_e refers to a file on a read-only filesystem and write access was requested. EETTXXTTBBSSYY _p_a_t_h_n_a_m_e refers to an executable image which is currently being executed and write access was requested. EETTXXTTBBSSYY _p_a_t_h_n_a_m_e refers to a file that is currently in use as a swap file, and the OO__TTRRUUNNCC flag was specified. EETTXXTTBBSSYY _p_a_t_h_n_a_m_e refers to a file that is currently being read by the kernel (e.g. for module/firmware loading), and write access was requested. EEWWOOUULLDDBBLLOOCCKK The OO__NNOONNBBLLOOCCKK flag was specified, and an incompatible lease was held on the file (see ffccnnttll(2)). The following additional errors can occur for ooppeennaatt(): EEBBAADDFF _d_i_r_f_d is not a valid file descriptor. EENNOOTTDDIIRR _p_a_t_h_n_a_m_e is a relative pathname and _d_i_r_f_d is a file descriptor referring to a file other than a directory. VVEERRSSIIOONNSS ooppeennaatt() was added to Linux in kernel 2.6.16; library support was added to glibc in version 2.4. CCOONNFFOORRMMIINNGG TTOO ooppeenn(), ccrreeaatt() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. ooppeennaatt(): POSIX.1-2008. The OO__DDIIRREECCTT, OO__NNOOAATTIIMMEE, OO__PPAATTHH, and OO__TTMMPPFFIILLEE flags are Linux-specific. One must define __GGNNUU__SSOOUURRCCEE to obtain their definitions. The OO__CCLLOOEEXXEECC, OO__DDIIRREECCTTOORRYY, and OO__NNOOFFOOLLLLOOWW 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 __PPOOSSIIXX__CC__SSOOUURRCCEE with a value greater than or equal to 200809L or __XXOOPPEENN__SSOOUURRCCEE with a value greater than or equal to 700. In glibc 2.11 and earlier, one obtains the definitions by defining __GGNNUU__SSOOUURRCCEE. As noted in ffeeaattuurree__tteesstt__mmaaccrrooss(7), feature test macros such as __PPOOSSIIXX__CC__SSOOUURRCCEE, __XXOOPPEENN__SSOOUURRCCEE, and __GGNNUU__SSOOUURRCCEE must be defined before including _a_n_y header files. NNOOTTEESS Under Linux, the OO__NNOONNBBLLOOCCKK 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 iiooccttll(2). The (undefined) effect of OO__RRDDOONNLLYY || OO__TTRRUUNNCC varies among implementations. On many systems the file is actually truncated. Note that ooppeenn() can open device special files, but ccrreeaatt() cannot create them; use mmkknnoodd(2) instead. If the file is newly created, its _s_t___a_t_i_m_e, _s_t___c_t_i_m_e, _s_t___m_t_i_m_e fields (respectively, time of last access, time of last status change, and time of last modification; see ssttaatt(2)) are set to the current time, and so are the _s_t___c_t_i_m_e and _s_t___m_t_i_m_e fields of the parent directory. Otherwise, if the file is modified because of the OO__TTRRUUNNCC flag, its _s_t___c_t_i_m_e and _s_t___m_t_i_m_e fields are set to the current time. The files in the _/_p_r_o_c_/_[_p_i_d_]_/_f_d directory show the open file descriptors of the process with the PID _p_i_d. The files in the _/_p_r_o_c_/_[_p_i_d_]_/_f_d_i_n_f_o directory show even more information about these files descriptors. See pprroocc(5) for further details of both of these directories. OOppeenn ffiillee ddeessccrriippttiioonnss The term open file description is the one used by POSIX to refer to the entries in the system-wide table of open files. In other contexts, this object is variously also called an "open file object", a "file handle", an "open file table entry", or—in kernel- developer parlance—a _s_t_r_u_c_t _f_i_l_e. When a file descriptor is duplicated (using dduupp(2) or similar), the duplicate refers to the same open file description as the original file descriptor, and the two file descriptors consequently share the file offset and file status flags. Such sharing can also occur between processes: a child process created via ffoorrkk(2) inherits duplicates of its parent's file descriptors, and those duplicates refer to the same open file descriptions. Each ooppeenn() of a file creates a new open file description; thus, there may be multiple open file descriptions corresponding to a file inode. On Linux, one can use the kkccmmpp(2) KKCCMMPP__FFIILLEE operation to test whether two file descriptors (in the same process or in two differ‐ ent processes) refer to the same open file description. SSyynncchhrroonniizzeedd II//OO The POSIX.1-2008 "synchronized I/O" option specifies different variants of synchronized I/O, and specifies the ooppeenn() flags OO__SSYYNNCC, OO__DDSSYYNNCC, and OO__RRSSYYNNCC for controlling the behavior. Regardless of whether an implementation supports this option, it must at least support the use of OO__SSYYNNCC for regular files. Linux implements OO__SSYYNNCC and OO__DDSSYYNNCC, but not OO__RRSSYYNNCC. (Somewhat incorrectly, glibc defines OO__RRSSYYNNCC to have the same value as OO__SSYYNNCC.) OO__SSYYNNCC provides synchronized I/O _f_i_l_e integrity completion, meaning write operations will flush data and all associated metadata to the underlying hardware. OO__DDSSYYNNCC provides synchronized I/O _d_a_t_a 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 com‐ plete 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 two types of completion, consider two pieces of file metadata: the file last modification timestamp (_s_t___m_t_i_m_e) 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, OO__DDSSYYNNCC would only guarantee to flush updates to the file length meta‐ data (whereas OO__SSYYNNCC would also always flush the last modification timestamp metadata). Before Linux 2.6.33, Linux implemented only the OO__SSYYNNCC flag for ooppeenn(). However, when that flag was specified, most filesystems actually provided the equivalent of synchronized I/O _d_a_t_a integrity completion (i.e., OO__SSYYNNCC was actually implemented as the equivalent of OO__DDSSYYNNCC). Since Linux 2.6.33, proper OO__SSYYNNCC support is provided. However, to ensure backward binary compatibility, OO__DDSSYYNNCC was defined with the same value as the historical OO__SSYYNNCC, and OO__SSYYNNCC was defined as a new (two-bit) flag value that includes the OO__DDSSYYNNCC flag value. This ensures that applications compiled against new headers get at least OO__DDSSYYNNCC semantics on pre-2.6.33 kernels. CC lliibbrraarryy//kkeerrnneell ddiiffffeerreenncceess Since version 2.26, the glibc wrapper function for ooppeenn() employs the ooppeennaatt() system call, rather than the kernel's ooppeenn() system call. For certain architectures, this is also true in glibc versions before 2.26. NNFFSS There are many infelicities in the protocol underlying NFS, affecting amongst others OO__SSYYNNCC and OO__NNDDEELLAAYY. On NFS filesystems with UID mapping enabled, ooppeenn() may return a file descriptor but, for example, rreeaadd(2) requests are denied with EEAACCCCEESS. This is because the client performs ooppeenn() by checking the permissions, but UID mapping is performed by the server upon read and write requests. FFIIFFOOss Opening the read or write end of a FIFO blocks until the other end is also opened (by another process or thread). See ffiiffoo(7) for further details. FFiillee aacccceessss mmooddee Unlike the other values that can be specified in _f_l_a_g_s, the _a_c_c_e_s_s _m_o_d_e values OO__RRDDOONNLLYY, OO__WWRROONNLLYY, and OO__RRDDWWRR do not specify indi‐ vidual bits. Rather, they define the low order two bits of _f_l_a_g_s, and are defined respectively as 0, 1, and 2. In other words, the combination OO__RRDDOONNLLYY || OO__WWRROONNLLYY is a logical error, and certainly does not have the same meaning as OO__RRDDWWRR. Linux reserves the special, nonstandard access mode 3 (binary 11) in _f_l_a_g_s to mean: check for read and write permission on the file and return a file descriptor that can't be used for reading or writing. This nonstandard access mode is used by some Linux drivers to return a file descriptor that is to be used only for device-specific iiooccttll(2) operations. RRaattiioonnaallee ffoorr ooppeennaatt(()) aanndd ootthheerr ddiirreeccttoorryy ffiillee ddeessccrriippttoorr AAPPIIss ooppeennaatt() and the other system calls and library functions that take a directory file descriptor argument (i.e., eexxeeccvveeaatt(2), ffaacc‐‐ cceessssaatt(2), ffaannoottiiffyy__mmaarrkk(2), ffcchhmmooddaatt(2), ffcchhoowwnnaatt(2), ffssttaattaatt(2), ffuuttiimmeessaatt(2), lliinnkkaatt(2), mmkkddiirraatt(2), mmkknnooddaatt(2), nnaammee__ttoo__hhaann‐‐ ddllee__aatt(2), rreeaaddlliinnkkaatt(2), rreennaammeeaatt(2), ssttaattxx(2), ssyymmlliinnkkaatt(2), uunnlliinnkkaatt(2), uuttiimmeennssaatt(2), mmkkffiiffooaatt(3), and ssccaannddiirraatt(3)) address two problems with the older interfaces that preceded them. Here, the explanation is in terms of the ooppeennaatt() call, but the ratio‐ nale is analogous for the other interfaces. First, ooppeennaatt() allows an application to avoid race conditions that could occur when using ooppeenn() 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 ooppeenn() could be changed in parallel with the call to ooppeenn(). Suppose, for example, that we wish to create the file _d_i_r_1_/_d_i_r_2_/_x_x_x_._d_e_p if the file _d_i_r_1_/_d_i_r_2_/_x_x_x exists. The problem is that between the existence check and the file-creation step, _d_i_r_1 or _d_i_r_2 (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 _d_i_r_f_d argument of (say) ffss‐‐ ttaattaatt(2) and ooppeennaatt(). The use of the _d_i_r_f_d file descriptor also has other benefits: * the file descriptor is a stable reference to the directory, even if the directory is renamed; and * the open file descriptor prevents the underlying filesystem from being dismounted, just as when a process has a current working directory on a filesystem. Second, ooppeennaatt() 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 _/_p_r_o_c_/_s_e_l_f_/_f_d_/dirfd, but less efficiently.) OO__DDIIRREECCTT The OO__DDIIRREECCTT flag may impose alignment restrictions on the length and address of user-space buffers and the file offset of I/Os. In Linux alignment restrictions vary by filesystem and kernel version and might be absent entirely. However there is currently no filesystem-independent interface for an application to discover these restrictions for a given file or filesystem. Some filesys‐ tems provide their own interfaces for doing so, for example the XXFFSS__IIOOCC__DDIIOOIINNFFOO operation in xxffssccttll(3). 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 filesystem. Since Linux 2.6.0, alignment to the logical block size of the underlying storage (typically 512 bytes) suffices. The logical block size can be determined using the iiooccttll(2) BBLLKKSSSSZZGGEETT operation or from the shell using the com‐ mand: blockdev --getss OO__DDIIRREECCTT I/Os should never be run concurrently with the ffoorrkk(2) system call, if the memory buffer is a private mapping (i.e., any mapping created with the mmmmaapp(2) MMAAPP__PPRRIIVVAATTEE flag; this includes memory allocated on the heap and statically allocated buffers). Any such I/Os, whether submitted via an asynchronous I/O interface or from another thread in the process, should be completed be‐ fore ffoorrkk(2) is called. Failure to do so can result in data corruption and undefined behavior in parent and child processes. This restriction does not apply when the memory buffer for the OO__DDIIRREECCTT I/Os was created using sshhmmaatt(2) or mmmmaapp(2) with the MMAAPP__SSHHAARREEDD flag. Nor does this restriction apply when the memory buffer has been advised as MMAADDVV__DDOONNTTFFOORRKK with mmaaddvviissee(2), ensur‐ ing that it will not be available to the child after ffoorrkk(2). The OO__DDIIRREECCTT flag was introduced in SGI IRIX, where it has alignment restrictions similar to those of Linux 2.4. IRIX has also a ffccnnttll(2) call to query appropriate alignments, and sizes. FreeBSD 4.x introduced a flag of the same name, but without alignment restrictions. OO__DDIIRREECCTT 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 ooppeenn() fails with the error EEIINNVVAALL if it is used. Applications should avoid mixing OO__DDIIRREECCTT and normal I/O to the same file, and especially to overlapping byte regions in the same file. 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 mmmmaapp(2) of files with direct I/O to the same files. The behavior of OO__DDIIRREECCTT 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 OO__DDIIRREECCTT 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 pre‐ serve the synchronous semantics of OO__DDIIRREECCTT. 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 OO__DDIIRREECCTT I/O. In summary, OO__DDIIRREECCTT is a potentially powerful tool that should be used with caution. It is recommended that applications treat use of OO__DDIIRREECCTT as a performance option which is disabled by default. "The thing that has always disturbed me about O_DIRECT is that the whole interface is just stupid, and was probably de‐ signed by a deranged monkey on some serious mind-controlling substances."—Linus BBUUGGSS Currently, it is not possible to enable signal-driven I/O by specifying OO__AASSYYNNCC when calling ooppeenn(); use ffccnnttll(2) to enable this flag. One must check for two different error codes, EEIISSDDIIRR and EENNOOEENNTT, when trying to determine whether the kernel supports OO__TTMMPPFFIILLEE functionality. When both OO__CCRREEAATT and OO__DDIIRREECCTTOORRYY are specified in _f_l_a_g_s and the file specified by _p_a_t_h_n_a_m_e does not exist, ooppeenn() will create a regular file (i.e., OO__DDIIRREECCTTOORRYY is ignored). SSEEEE AALLSSOO cchhmmoodd(2), cchhoowwnn(2), cclloossee(2), dduupp(2), ffccnnttll(2), lliinnkk(2), llsseeeekk(2), mmkknnoodd(2), mmmmaapp(2), mmoouunntt(2), ooppeenn__bbyy__hhaannddllee__aatt(2), rreeaadd(2), ssoocckkeett(2), ssttaatt(2), uummaasskk(2), uunnlliinnkk(2), wwrriittee(2), ffooppeenn(3), aaccll(5), ffiiffoo(7), iinnooddee(7), ppaatthh__rreessoolluuttiioonn(7), ssyymmlliinnkk(7) CCOOLLOOPPHHOONN This page is part of release 4.16 of the Linux _m_a_n_-_p_a_g_e_s project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. Linux 2018-04-30 OPEN(2)