1OPEN(2) Linux Programmer's Manual OPEN(2)
2
6 open, openat, creat - open and possibly create a file
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <fcntl.h>
12 int open(const char *pathname, int flags);
14 int open(const char *pathname, int flags, mode_t mode);
15 int creat(const char *pathname, mode_t mode);
17 int openat(int dirfd, const char *pathname, int flags);
19 int openat(int dirfd, const char *pathname, int flags, mode_t mode);
20 /* Documented separately, in openat2(2): */
22 int openat2(int dirfd, const char *pathname,
23 const struct open_how *how, size_t size);
24 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
26 openat():
28 Since glibc 2.10:
29 _POSIX_C_SOURCE >= 200809L
30 Before glibc 2.10:
31 _ATFILE_SOURCE
32
34 The open() system call opens the file specified by pathname. If the
35 specified file does not exist, it may optionally (if O_CREAT is speci‐
36 fied in flags) be created by open().
37 The return value of open() is a file descriptor, a small, nonnegative
39 integer that is used in subsequent system calls (read(2), write(2),
40 lseek(2), fcntl(2), etc.) to refer to the open file. The file descrip‐
41 tor returned by a successful call will be the lowest-numbered file de‐
42 scriptor not currently open for the process.
43 By default, the new file descriptor is set to remain open across an ex‐
45 ecve(2) (i.e., the FD_CLOEXEC file descriptor flag described in fc‐
46 ntl(2) is initially disabled); the O_CLOEXEC flag, described below, can
47 be used to change this default. The file offset is set to the begin‐
48 ning of the file (see lseek(2)).
49 A call to open() creates a new open file description, an entry in the
51 system-wide table of open files. The open file description records the
52 file offset and the file status flags (see below). A file descriptor
53 is a reference to an open file description; this reference is unaf‐
54 fected if pathname is subsequently removed or modified to refer to a
55 different file. For further details on open file descriptions, see
56 NOTES.
57 The argument flags must include one of the following access modes:
59 O_RDONLY, O_WRONLY, or O_RDWR. These request opening the file read-
60 only, write-only, or read/write, respectively.
61 In addition, zero or more file creation flags and file status flags can
63 be bitwise-or'd in flags. The file creation flags are O_CLOEXEC,
64 O_CREAT, O_DIRECTORY, O_EXCL, O_NOCTTY, O_NOFOLLOW, O_TMPFILE, and
65 O_TRUNC. The file status flags are all of the remaining flags listed
66 below. The distinction between these two groups of flags is that the
67 file creation flags affect the semantics of the open operation itself,
68 while the file status flags affect the semantics of subsequent I/O op‐
69 erations. The file status flags can be retrieved and (in some cases)
70 modified; see fcntl(2) for details.
71 The full list of file creation flags and file status flags is as fol‐
73 lows:
74 O_APPEND
76 The file is opened in append mode. Before each write(2), the
77 file offset is positioned at the end of the file, as if with
78 lseek(2). The modification of the file offset and the write op‐
79 eration are performed as a single atomic step.
80 O_APPEND may lead to corrupted files on NFS filesystems if more
82 than one process appends data to a file at once. This is be‐
83 cause NFS does not support appending to a file, so the client
84 kernel has to simulate it, which can't be done without a race
85 condition.
86 O_ASYNC
88 Enable signal-driven I/O: generate a signal (SIGIO by default,
89 but this can be changed via fcntl(2)) when input or output be‐
90 comes possible on this file descriptor. This feature is avail‐
91 able only for terminals, pseudoterminals, sockets, and (since
92 Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.
93 See also BUGS, below.
94 O_CLOEXEC (since Linux 2.6.23)
96 Enable the close-on-exec flag for the new file descriptor.
97 Specifying this flag permits a program to avoid additional fc‐
98 ntl(2) F_SETFD operations to set the FD_CLOEXEC flag.
99 Note that the use of this flag is essential in some multi‐
101 threaded programs, because using a separate fcntl(2) F_SETFD op‐
102 eration to set the FD_CLOEXEC flag does not suffice to avoid
103 race conditions where one thread opens a file descriptor and at‐
104 tempts to set its close-on-exec flag using fcntl(2) at the same
105 time as another thread does a fork(2) plus execve(2). Depending
106 on the order of execution, the race may lead to the file de‐
107 scriptor returned by open() being unintentionally leaked to the
108 program executed by the child process created by fork(2). (This
109 kind of race is in principle possible for any system call that
110 creates a file descriptor whose close-on-exec flag should be
111 set, and various other Linux system calls provide an equivalent
112 of the O_CLOEXEC flag to deal with this problem.)
113 O_CREAT
115 If pathname does not exist, create it as a regular file.
116 The owner (user ID) of the new file is set to the effective user
118 ID of the process.
119 The group ownership (group ID) of the new file is set either to
121 the effective group ID of the process (System V semantics) or to
122 the group ID of the parent directory (BSD semantics). On Linux,
123 the behavior depends on whether the set-group-ID mode bit is set
124 on the parent directory: if that bit is set, then BSD semantics
125 apply; otherwise, System V semantics apply. For some filesys‐
126 tems, the behavior also depends on the bsdgroups and sysvgroups
127 mount options described in mount(8).
128 The mode argument specifies the file mode bits to be applied
130 when a new file is created. If neither O_CREAT nor O_TMPFILE is
131 specified in flags, then mode is ignored (and can thus be speci‐
132 fied as 0, or simply omitted). The mode argument must be sup‐
133 plied if O_CREAT or O_TMPFILE is specified in flags; if it is
134 not supplied, some arbitrary bytes from the stack will be ap‐
135 plied as the file mode.
136 The effective mode is modified by the process's umask in the
138 usual way: in the absence of a default ACL, the mode of the cre‐
139 ated file is (mode & ~umask).
140 Note that mode applies only to future accesses of the newly cre‐
142 ated file; the open() call that creates a read-only file may
143 well return a read/write file descriptor.
144 The following symbolic constants are provided for mode:
146 S_IRWXU 00700 user (file owner) has read, write, and execute
148 permission
149 S_IRUSR 00400 user has read permission
151 S_IWUSR 00200 user has write permission
153 S_IXUSR 00100 user has execute permission
155 S_IRWXG 00070 group has read, write, and execute permission
157 S_IRGRP 00040 group has read permission
159 S_IWGRP 00020 group has write permission
161 S_IXGRP 00010 group has execute permission
163 S_IRWXO 00007 others have read, write, and execute permission
165 S_IROTH 00004 others have read permission
167 S_IWOTH 00002 others have write permission
169 S_IXOTH 00001 others have execute permission
171 According to POSIX, the effect when other bits are set in mode
173 is unspecified. On Linux, the following bits are also honored
174 in mode:
175 S_ISUID 0004000 set-user-ID bit
177 S_ISGID 0002000 set-group-ID bit (see inode(7)).
179 S_ISVTX 0001000 sticky bit (see inode(7)).
181 O_DIRECT (since Linux 2.4.10)
183 Try to minimize cache effects of the I/O to and from this file.
184 In general this will degrade performance, but it is useful in
185 special situations, such as when applications do their own
186 caching. File I/O is done directly to/from user-space buffers.
187 The O_DIRECT flag on its own makes an effort to transfer data
188 synchronously, but does not give the guarantees of the O_SYNC
189 flag that data and necessary metadata are transferred. To guar‐
190 antee synchronous I/O, O_SYNC must be used in addition to O_DI‐
191 RECT. See NOTES below for further discussion.
192 A semantically similar (but deprecated) interface for block de‐
194 vices is described in raw(8).
195 O_DIRECTORY
197 If pathname is not a directory, cause the open to fail. This
198 flag was added in kernel version 2.1.126, to avoid denial-of-
199 service problems if opendir(3) is called on a FIFO or tape de‐
200 vice.
201 O_DSYNC
203 Write operations on the file will complete according to the re‐
204 quirements of synchronized I/O data integrity completion.
205 By the time write(2) (and similar) return, the output data has
207 been transferred to the underlying hardware, along with any file
208 metadata that would be required to retrieve that data (i.e., as
209 though each write(2) was followed by a call to fdatasync(2)).
210 See NOTES below.
211 O_EXCL Ensure that this call creates the file: if this flag is speci‐
213 fied in conjunction with O_CREAT, and pathname already exists,
214 then open() fails with the error EEXIST.
215 When these two flags are specified, symbolic links are not fol‐
217 lowed: if pathname is a symbolic link, then open() fails regard‐
218 less of where the symbolic link points.
219 In general, the behavior of O_EXCL is undefined if it is used
221 without O_CREAT. There is one exception: on Linux 2.6 and
222 later, O_EXCL can be used without O_CREAT if pathname refers to
223 a block device. If the block device is in use by the system
224 (e.g., mounted), open() fails with the error EBUSY.
225 On NFS, O_EXCL is supported only when using NFSv3 or later on
227 kernel 2.6 or later. In NFS environments where O_EXCL support
228 is not provided, programs that rely on it for performing locking
229 tasks will contain a race condition. Portable programs that
230 want to perform atomic file locking using a lockfile, and need
231 to avoid reliance on NFS support for O_EXCL, can create a unique
232 file on the same filesystem (e.g., incorporating hostname and
233 PID), and use link(2) to make a link to the lockfile. If
234 link(2) returns 0, the lock is successful. Otherwise, use
235 stat(2) on the unique file to check if its link count has in‐
236 creased to 2, in which case the lock is also successful.
237 O_LARGEFILE
239 (LFS) Allow files whose sizes cannot be represented in an off_t
240 (but can be represented in an off64_t) to be opened. The
241 _LARGEFILE64_SOURCE macro must be defined (before including any
242 header files) in order to obtain this definition. Setting the
243 _FILE_OFFSET_BITS feature test macro to 64 (rather than using
244 O_LARGEFILE) is the preferred method of accessing large files on
245 32-bit systems (see feature_test_macros(7)).
246 O_NOATIME (since Linux 2.6.8)
248 Do not update the file last access time (st_atime in the inode)
249 when the file is read(2).
250 This flag can be employed only if one of the following condi‐
252 tions is true:
253 * The effective UID of the process matches the owner UID of the
255 file.
256 * The calling process has the CAP_FOWNER capability in its user
258 namespace and the owner UID of the file has a mapping in the
259 namespace.
260 This flag is intended for use by indexing or backup programs,
262 where its use can significantly reduce the amount of disk activ‐
263 ity. This flag may not be effective on all filesystems. One
264 example is NFS, where the server maintains the access time.
265 O_NOCTTY
267 If pathname refers to a terminal device—see tty(4)—it will not
268 become the process's controlling terminal even if the process
269 does not have one.
270 O_NOFOLLOW
272 If the trailing component (i.e., basename) of pathname is a sym‐
273 bolic link, then the open fails, with the error ELOOP. Symbolic
274 links in earlier components of the pathname will still be fol‐
275 lowed. (Note that the ELOOP error that can occur in this case
276 is indistinguishable from the case where an open fails because
277 there are too many symbolic links found while resolving compo‐
278 nents in the prefix part of the pathname.)
279 This flag is a FreeBSD extension, which was added to Linux in
281 version 2.1.126, and has subsequently been standardized in
282 POSIX.1-2008.
283 See also O_PATH below.
285 O_NONBLOCK or O_NDELAY
287 When possible, the file is opened in nonblocking mode. Neither
288 the open() nor any subsequent I/O operations on the file de‐
289 scriptor which is returned will cause the calling process to
290 wait.
291 Note that the setting of this flag has no effect on the opera‐
293 tion of poll(2), select(2), epoll(7), and similar, since those
294 interfaces merely inform the caller about whether a file de‐
295 scriptor is "ready", meaning that an I/O operation performed on
296 the file descriptor with the O_NONBLOCK flag clear would not
297 block.
298 Note that this flag has no effect for regular files and block
300 devices; that is, I/O operations will (briefly) block when de‐
301 vice activity is required, regardless of whether O_NONBLOCK is
302 set. Since O_NONBLOCK semantics might eventually be imple‐
303 mented, applications should not depend upon blocking behavior
304 when specifying this flag for regular files and block devices.
305 For the handling of FIFOs (named pipes), see also fifo(7). For
307 a discussion of the effect of O_NONBLOCK in conjunction with
308 mandatory file locks and with file leases, see fcntl(2).
309 O_PATH (since Linux 2.6.39)
311 Obtain a file descriptor that can be used for two purposes: to
312 indicate a location in the filesystem tree and to perform opera‐
313 tions that act purely at the file descriptor level. The file
314 itself is not opened, and other file operations (e.g., read(2),
315 write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2), mmap(2))
316 fail with the error EBADF.
317 The following operations can be performed on the resulting file
319 descriptor:
320 * close(2).
322 * fchdir(2), if the file descriptor refers to a directory
324 (since Linux 3.5).
325 * fstat(2) (since Linux 3.6).
327 * fstatfs(2) (since Linux 3.12).
329 * Duplicating the file descriptor (dup(2), fcntl(2) F_DUPFD,
331 etc.).
332 * Getting and setting file descriptor flags (fcntl(2) F_GETFD
334 and F_SETFD).
335 * Retrieving open file status flags using the fcntl(2) F_GETFL
337 operation: the returned flags will include the bit O_PATH.
338 * Passing the file descriptor as the dirfd argument of openat()
340 and the other "*at()" system calls. This includes linkat(2)
341 with AT_EMPTY_PATH (or via procfs using AT_SYMLINK_FOLLOW)
342 even if the file is not a directory.
343 * Passing the file descriptor to another process via a UNIX do‐
345 main socket (see SCM_RIGHTS in unix(7)).
346 When O_PATH is specified in flags, flag bits other than
348 O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW are ignored.
349 Opening a file or directory with the O_PATH flag requires no
351 permissions on the object itself (but does require execute per‐
352 mission on the directories in the path prefix). Depending on
353 the subsequent operation, a check for suitable file permissions
354 may be performed (e.g., fchdir(2) requires execute permission on
355 the directory referred to by its file descriptor argument). By
356 contrast, obtaining a reference to a filesystem object by open‐
357 ing it with the O_RDONLY flag requires that the caller have read
358 permission on the object, even when the subsequent operation
359 (e.g., fchdir(2), fstat(2)) does not require read permission on
360 the object.
361 If pathname is a symbolic link and the O_NOFOLLOW flag is also
363 specified, then the call returns a file descriptor referring to
364 the symbolic link. This file descriptor can be used as the
365 dirfd argument in calls to fchownat(2), fstatat(2), linkat(2),
366 and readlinkat(2) with an empty pathname to have the calls oper‐
367 ate on the symbolic link.
368 If pathname refers to an automount point that has not yet been
370 triggered, so no other filesystem is mounted on it, then the
371 call returns a file descriptor referring to the automount direc‐
372 tory without triggering a mount. fstatfs(2) can then be used to
373 determine if it is, in fact, an untriggered automount point
374 (.f_type == AUTOFS_SUPER_MAGIC).
375 One use of O_PATH for regular files is to provide the equivalent
377 of POSIX.1's O_EXEC functionality. This permits us to open a
378 file for which we have execute permission but not read permis‐
379 sion, and then execute that file, with steps something like the
380 following:
381 char buf[PATH_MAX];
383 fd = open("some_prog", O_PATH);
384 snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
385 execl(buf, "some_prog", (char *) NULL);
386 An O_PATH file descriptor can also be passed as the argument of
388 fexecve(3).
389 O_SYNC Write operations on the file will complete according to the re‐
391 quirements of synchronized I/O file integrity completion (by
392 contrast with the synchronized I/O data integrity completion
393 provided by O_DSYNC.)
394 By the time write(2) (or similar) returns, the output data and
396 associated file metadata have been transferred to the underlying
397 hardware (i.e., as though each write(2) was followed by a call
398 to fsync(2)). See NOTES below.
399 O_TMPFILE (since Linux 3.11)
401 Create an unnamed temporary regular file. The pathname argument
402 specifies a directory; an unnamed inode will be created in that
403 directory's filesystem. Anything written to the resulting file
404 will be lost when the last file descriptor is closed, unless the
405 file is given a name.
406 O_TMPFILE must be specified with one of O_RDWR or O_WRONLY and,
408 optionally, O_EXCL. If O_EXCL is not specified, then linkat(2)
409 can be used to link the temporary file into the filesystem, mak‐
410 ing it permanent, using code like the following:
411 char path[PATH_MAX];
413 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
414 S_IRUSR | S_IWUSR);
415 /* File I/O on 'fd'... */
417 linkat(fd, NULL, AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
419 /* If the caller doesn't have the CAP_DAC_READ_SEARCH
421 capability (needed to use AT_EMPTY_PATH with linkat(2)),
422 and there is a proc(5) filesystem mounted, then the
423 linkat(2) call above can be replaced with:
424 snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
426 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
427 AT_SYMLINK_FOLLOW);
428 */
429 In this case, the open() mode argument determines the file per‐
431 mission mode, as with O_CREAT.
432 Specifying O_EXCL in conjunction with O_TMPFILE prevents a tem‐
434 porary file from being linked into the filesystem in the above
435 manner. (Note that the meaning of O_EXCL in this case is dif‐
436 ferent from the meaning of O_EXCL otherwise.)
437 There are two main use cases for O_TMPFILE:
439 * Improved tmpfile(3) functionality: race-free creation of tem‐
441 porary files that (1) are automatically deleted when closed;
442 (2) can never be reached via any pathname; (3) are not sub‐
443 ject to symlink attacks; and (4) do not require the caller to
444 devise unique names.
445 * Creating a file that is initially invisible, which is then
447 populated with data and adjusted to have appropriate filesys‐
448 tem attributes (fchown(2), fchmod(2), fsetxattr(2), etc.)
449 before being atomically linked into the filesystem in a fully
450 formed state (using linkat(2) as described above).
451 O_TMPFILE requires support by the underlying filesystem; only a
453 subset of Linux filesystems provide that support. In the ini‐
454 tial implementation, support was provided in the ext2, ext3,
455 ext4, UDF, Minix, and shmem filesystems. Support for other
456 filesystems has subsequently been added as follows: XFS (Linux
457 3.15); Btrfs (Linux 3.16); F2FS (Linux 3.16); and ubifs (Linux
458 4.9)
459 O_TRUNC
461 If the file already exists and is a regular file and the access
462 mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be
463 truncated to length 0. If the file is a FIFO or terminal device
464 file, the O_TRUNC flag is ignored. Otherwise, the effect of
465 O_TRUNC is unspecified.
466 creat()
468 A call to creat() is equivalent to calling open() with flags equal to
469 O_CREAT|O_WRONLY|O_TRUNC.
470 openat()
472 The openat() system call operates in exactly the same way as open(),
473 except for the differences described here.
474 If the pathname given in pathname is relative, then it is interpreted
476 relative to the directory referred to by the file descriptor dirfd
477 (rather than relative to the current working directory of the calling
478 process, as is done by open() for a relative pathname).
479 If pathname is relative and dirfd is the special value AT_FDCWD, then
481 pathname is interpreted relative to the current working directory of
482 the calling process (like open()).
483 If pathname is absolute, then dirfd is ignored.
485 openat2(2)
487 The openat2(2) system call is an extension of openat(), and provides a
488 superset of the features of openat(). It is documented separately, in
489 openat2(2).
490
492 open(), openat(), and creat() return the new file descriptor (a nonneg‐
493 ative integer), or -1 if an error occurred (in which case, errno is set
494 appropriately).
495
497 open(), openat(), and creat() can fail with the following errors:
498 EACCES The requested access to the file is not allowed, or search per‐
500 mission is denied for one of the directories in the path prefix
501 of pathname, or the file did not exist yet and write access to
502 the parent directory is not allowed. (See also path_resolu‐
503 tion(7).)
504 EACCES Where O_CREAT is specified, the protected_fifos or pro‐
506 tected_regular sysctl is enabled, the file already exists and is
507 a FIFO or regular file, the owner of the file is neither the
508 current user nor the owner of the containing directory, and the
509 containing directory is both world- or group-writable and
510 sticky. For details, see the descriptions of /proc/sys/fs/pro‐
511 tected_fifos and /proc/sys/fs/protected_regular in proc(5).
512 EBUSY O_EXCL was specified in flags and pathname refers to a block de‐
514 vice that is in use by the system (e.g., it is mounted).
515 EDQUOT Where O_CREAT is specified, the file does not exist, and the
517 user's quota of disk blocks or inodes on the filesystem has been
518 exhausted.
519 EEXIST pathname already exists and O_CREAT and O_EXCL were used.
521 EFAULT pathname points outside your accessible address space.
523 EFBIG See EOVERFLOW.
525 EINTR While blocked waiting to complete an open of a slow device
527 (e.g., a FIFO; see fifo(7)), the call was interrupted by a sig‐
528 nal handler; see signal(7).
529 EINVAL The filesystem does not support the O_DIRECT flag. See NOTES
531 for more information.
532 EINVAL Invalid value in flags.
534 EINVAL O_TMPFILE was specified in flags, but neither O_WRONLY nor
536 O_RDWR was specified.
537 EINVAL O_CREAT was specified in flags and the final component ("base‐
539 name") of the new file's pathname is invalid (e.g., it contains
540 characters not permitted by the underlying filesystem).
541 EINVAL The final component ("basename") of pathname is invalid (e.g.,
543 it contains characters not permitted by the underlying filesys‐
544 tem).
545 EISDIR pathname refers to a directory and the access requested involved
547 writing (that is, O_WRONLY or O_RDWR is set).
548 EISDIR pathname refers to an existing directory, O_TMPFILE and one of
550 O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
551 sion does not provide the O_TMPFILE functionality.
552 ELOOP Too many symbolic links were encountered in resolving pathname.
554 ELOOP pathname was a symbolic link, and flags specified O_NOFOLLOW but
556 not O_PATH.
557 EMFILE The per-process limit on the number of open file descriptors has
559 been reached (see the description of RLIMIT_NOFILE in getr‐
560 limit(2)).
561 ENAMETOOLONG
563 pathname was too long.
564 ENFILE The system-wide limit on the total number of open files has been
566 reached.
567 ENODEV pathname refers to a device special file and no corresponding
569 device exists. (This is a Linux kernel bug; in this situation
570 ENXIO must be returned.)
571 ENOENT O_CREAT is not set and the named file does not exist.
573 ENOENT A directory component in pathname does not exist or is a dan‐
575 gling symbolic link.
576 ENOENT pathname refers to a nonexistent directory, O_TMPFILE and one of
578 O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
579 sion does not provide the O_TMPFILE functionality.
580 ENOMEM The named file is a FIFO, but memory for the FIFO buffer can't
582 be allocated because the per-user hard limit on memory alloca‐
583 tion for pipes has been reached and the caller is not privi‐
584 leged; see pipe(7).
585 ENOMEM Insufficient kernel memory was available.
587 ENOSPC pathname was to be created but the device containing pathname
589 has no room for the new file.
590 ENOTDIR
592 A component used as a directory in pathname is not, in fact, a
593 directory, or O_DIRECTORY was specified and pathname was not a
594 directory.
595 ENXIO O_NONBLOCK | O_WRONLY is set, the named file is a FIFO, and no
597 process has the FIFO open for reading.
598 ENXIO The file is a device special file and no corresponding device
600 exists.
601 ENXIO The file is a UNIX domain socket.
603 EOPNOTSUPP
605 The filesystem containing pathname does not support O_TMPFILE.
606 EOVERFLOW
608 pathname refers to a regular file that is too large to be
609 opened. The usual scenario here is that an application compiled
610 on a 32-bit platform without -D_FILE_OFFSET_BITS=64 tried to
611 open a file whose size exceeds (1<<31)-1 bytes; see also
612 O_LARGEFILE above. This is the error specified by POSIX.1; in
613 kernels before 2.6.24, Linux gave the error EFBIG for this case.
614 EPERM The O_NOATIME flag was specified, but the effective user ID of
616 the caller did not match the owner of the file and the caller
617 was not privileged.
618 EPERM The operation was prevented by a file seal; see fcntl(2).
620 EROFS pathname refers to a file on a read-only filesystem and write
622 access was requested.
623 ETXTBSY
625 pathname refers to an executable image which is currently being
626 executed and write access was requested.
627 ETXTBSY
629 pathname refers to a file that is currently in use as a swap
630 file, and the O_TRUNC flag was specified.
631 ETXTBSY
633 pathname refers to a file that is currently being read by the
634 kernel (e.g., for module/firmware loading), and write access was
635 requested.
636 EWOULDBLOCK
638 The O_NONBLOCK flag was specified, and an incompatible lease was
639 held on the file (see fcntl(2)).
640 The following additional errors can occur for openat():
642 EBADF dirfd is not a valid file descriptor.
644 ENOTDIR
646 pathname is a relative pathname and dirfd is a file descriptor
647 referring to a file other than a directory.
648
650 openat() was added to Linux in kernel 2.6.16; library support was added
651 to glibc in version 2.4.
652
654 open(), creat() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
655 openat(): POSIX.1-2008.
657 openat2(2) is Linux-specific.
659 The O_DIRECT, O_NOATIME, O_PATH, and O_TMPFILE flags are Linux-spe‐
661 cific. One must define _GNU_SOURCE to obtain their definitions.
662 The O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW flags are not specified in
664 POSIX.1-2001, but are specified in POSIX.1-2008. Since glibc 2.12, one
665 can obtain their definitions by defining either _POSIX_C_SOURCE with a
666 value greater than or equal to 200809L or _XOPEN_SOURCE with a value
667 greater than or equal to 700. In glibc 2.11 and earlier, one obtains
668 the definitions by defining _GNU_SOURCE.
669 As noted in feature_test_macros(7), feature test macros such as
671 _POSIX_C_SOURCE, _XOPEN_SOURCE, and _GNU_SOURCE must be defined before
672 including any header files.
673
675 Under Linux, the O_NONBLOCK flag is sometimes used in cases where one
676 wants to open but does not necessarily have the intention to read or
677 write. For example, this may be used to open a device in order to get
678 a file descriptor for use with ioctl(2).
679 The (undefined) effect of O_RDONLY | O_TRUNC varies among implementa‐
681 tions. On many systems the file is actually truncated.
682 Note that open() can open device special files, but creat() cannot cre‐
684 ate them; use mknod(2) instead.
685 If the file is newly created, its st_atime, st_ctime, st_mtime fields
687 (respectively, time of last access, time of last status change, and
688 time of last modification; see stat(2)) are set to the current time,
689 and so are the st_ctime and st_mtime fields of the parent directory.
690 Otherwise, if the file is modified because of the O_TRUNC flag, its
691 st_ctime and st_mtime fields are set to the current time.
692 The files in the /proc/[pid]/fd directory show the open file descrip‐
694 tors of the process with the PID pid. The files in the /proc/[pid]/fd‐
695 info directory show even more information about these file descriptors.
696 See proc(5) for further details of both of these directories.
697 The Linux header file <asm/fcntl.h> doesn't define O_ASYNC; the (BSD-
699 derived) FASYNC synonym is defined instead.
700 Open file descriptions
702 The term open file description is the one used by POSIX to refer to the
703 entries in the system-wide table of open files. In other contexts,
704 this object is variously also called an "open file object", a "file
705 handle", an "open file table entry", or—in kernel-developer parlance—a
706 struct file.
707 When a file descriptor is duplicated (using dup(2) or similar), the du‐
709 plicate refers to the same open file description as the original file
710 descriptor, and the two file descriptors consequently share the file
711 offset and file status flags. Such sharing can also occur between pro‐
712 cesses: a child process created via fork(2) inherits duplicates of its
713 parent's file descriptors, and those duplicates refer to the same open
714 file descriptions.
715 Each open() of a file creates a new open file description; thus, there
717 may be multiple open file descriptions corresponding to a file inode.
718 On Linux, one can use the kcmp(2) KCMP_FILE operation to test whether
720 two file descriptors (in the same process or in two different pro‐
721 cesses) refer to the same open file description.
722 Synchronized I/O
724 The POSIX.1-2008 "synchronized I/O" option specifies different variants
725 of synchronized I/O, and specifies the open() flags O_SYNC, O_DSYNC,
726 and O_RSYNC for controlling the behavior. Regardless of whether an im‐
727 plementation supports this option, it must at least support the use of
728 O_SYNC for regular files.
729 Linux implements O_SYNC and O_DSYNC, but not O_RSYNC. Somewhat incor‐
731 rectly, glibc defines O_RSYNC to have the same value as O_SYNC.
732 (O_RSYNC is defined in the Linux header file <asm/fcntl.h> on HP PA-
733 RISC, but it is not used.)
734 O_SYNC provides synchronized I/O file integrity completion, meaning
736 write operations will flush data and all associated metadata to the un‐
737 derlying hardware. O_DSYNC provides synchronized I/O data integrity
738 completion, meaning write operations will flush data to the underlying
739 hardware, but will only flush metadata updates that are required to al‐
740 low a subsequent read operation to complete successfully. Data integ‐
741 rity completion can reduce the number of disk operations that are re‐
742 quired for applications that don't need the guarantees of file integ‐
743 rity completion.
744 To understand the difference between the two types of completion, con‐
746 sider two pieces of file metadata: the file last modification timestamp
747 (st_mtime) and the file length. All write operations will update the
748 last file modification timestamp, but only writes that add data to the
749 end of the file will change the file length. The last modification
750 timestamp is not needed to ensure that a read completes successfully,
751 but the file length is. Thus, O_DSYNC would only guarantee to flush
752 updates to the file length metadata (whereas O_SYNC would also always
753 flush the last modification timestamp metadata).
754 Before Linux 2.6.33, Linux implemented only the O_SYNC flag for open().
756 However, when that flag was specified, most filesystems actually pro‐
757 vided the equivalent of synchronized I/O data integrity completion
758 (i.e., O_SYNC was actually implemented as the equivalent of O_DSYNC).
759 Since Linux 2.6.33, proper O_SYNC support is provided. However, to en‐
761 sure backward binary compatibility, O_DSYNC was defined with the same
762 value as the historical O_SYNC, and O_SYNC was defined as a new (two-
763 bit) flag value that includes the O_DSYNC flag value. This ensures
764 that applications compiled against new headers get at least O_DSYNC se‐
765 mantics on pre-2.6.33 kernels.
766 C library/kernel differences
768 Since version 2.26, the glibc wrapper function for open() employs the
769 openat() system call, rather than the kernel's open() system call. For
770 certain architectures, this is also true in glibc versions before 2.26.
771 NFS
773 There are many infelicities in the protocol underlying NFS, affecting
774 amongst others O_SYNC and O_NDELAY.
775 On NFS filesystems with UID mapping enabled, open() may return a file
777 descriptor but, for example, read(2) requests are denied with EACCES.
778 This is because the client performs open() by checking the permissions,
779 but UID mapping is performed by the server upon read and write re‐
780 quests.
781 FIFOs
783 Opening the read or write end of a FIFO blocks until the other end is
784 also opened (by another process or thread). See fifo(7) for further
785 details.
786 File access mode
788 Unlike the other values that can be specified in flags, the access mode
789 values O_RDONLY, O_WRONLY, and O_RDWR do not specify individual bits.
790 Rather, they define the low order two bits of flags, and are defined
791 respectively as 0, 1, and 2. In other words, the combination O_RDONLY
792 | O_WRONLY is a logical error, and certainly does not have the same
793 meaning as O_RDWR.
794 Linux reserves the special, nonstandard access mode 3 (binary 11) in
796 flags to mean: check for read and write permission on the file and re‐
797 turn a file descriptor that can't be used for reading or writing. This
798 nonstandard access mode is used by some Linux drivers to return a file
799 descriptor that is to be used only for device-specific ioctl(2) opera‐
800 tions.
801 Rationale for openat() and other directory file descriptor APIs
803 openat() and the other system calls and library functions that take a
804 directory file descriptor argument (i.e., execveat(2), faccessat(2),
805 fanotify_mark(2), fchmodat(2), fchownat(2), fspick(2), fstatat(2), fu‐
806 timesat(2), linkat(2), mkdirat(2), move_mount(2), mknodat(2),
807 name_to_handle_at(2), open_tree(2), openat2(2), readlinkat(2), re‐
808 nameat(2), statx(2), symlinkat(2), unlinkat(2), utimensat(2), mkfi‐
809 foat(3), and scandirat(3)) address two problems with the older inter‐
810 faces that preceded them. Here, the explanation is in terms of the
811 openat() call, but the rationale is analogous for the other interfaces.
812 First, openat() allows an application to avoid race conditions that
814 could occur when using open() to open files in directories other than
815 the current working directory. These race conditions result from the
816 fact that some component of the directory prefix given to open() could
817 be changed in parallel with the call to open(). Suppose, for example,
818 that we wish to create the file dir1/dir2/xxx.dep if the file
819 dir1/dir2/xxx exists. The problem is that between the existence check
820 and the file-creation step, dir1 or dir2 (which might be symbolic
821 links) could be modified to point to a different location. Such races
822 can be avoided by opening a file descriptor for the target directory,
823 and then specifying that file descriptor as the dirfd argument of (say)
824 fstatat(2) and openat(). The use of the dirfd file descriptor also has
825 other benefits:
826 * the file descriptor is a stable reference to the directory, even if
828 the directory is renamed; and
829 * the open file descriptor prevents the underlying filesystem from be‐
831 ing dismounted, just as when a process has a current working direc‐
832 tory on a filesystem.
833 Second, openat() allows the implementation of a per-thread "current
835 working directory", via file descriptor(s) maintained by the applica‐
836 tion. (This functionality can also be obtained by tricks based on the
837 use of /proc/self/fd/dirfd, but less efficiently.)
838 The dirfd argument for these APIs can be obtained by using open() or
840 openat() to open a directory (with either the O_RDONLY or the O_PATH
841 flag). Alternatively, such a file descriptor can be obtained by apply‐
842 ing dirfd(3) to a directory stream created using opendir(3).
843 When these APIs are given a dirfd argument of AT_FDCWD or the specified
845 pathname is absolute, then they handle their pathname argument in the
846 same way as the corresponding conventional APIs. However, in this
847 case, several of the APIs have a flags argument that provides access to
848 functionality that is not available with the corresponding conventional
849 APIs.
850 O_DIRECT
852 The O_DIRECT flag may impose alignment restrictions on the length and
853 address of user-space buffers and the file offset of I/Os. In Linux
854 alignment restrictions vary by filesystem and kernel version and might
855 be absent entirely. However there is currently no filesystem-indepen‐
856 dent interface for an application to discover these restrictions for a
857 given file or filesystem. Some filesystems provide their own inter‐
858 faces for doing so, for example the XFS_IOC_DIOINFO operation in xf‐
859 sctl(3).
860 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
862 and the file offset must all be multiples of the logical block size of
863 the filesystem. Since Linux 2.6.0, alignment to the logical block size
864 of the underlying storage (typically 512 bytes) suffices. The logical
865 block size can be determined using the ioctl(2) BLKSSZGET operation or
866 from the shell using the command:
867 blockdev --getss
869 O_DIRECT I/Os should never be run concurrently with the fork(2) system
871 call, if the memory buffer is a private mapping (i.e., any mapping cre‐
872 ated with the mmap(2) MAP_PRIVATE flag; this includes memory allocated
873 on the heap and statically allocated buffers). Any such I/Os, whether
874 submitted via an asynchronous I/O interface or from another thread in
875 the process, should be completed before fork(2) is called. Failure to
876 do so can result in data corruption and undefined behavior in parent
877 and child processes. This restriction does not apply when the memory
878 buffer for the O_DIRECT I/Os was created using shmat(2) or mmap(2) with
879 the MAP_SHARED flag. Nor does this restriction apply when the memory
880 buffer has been advised as MADV_DONTFORK with madvise(2), ensuring that
881 it will not be available to the child after fork(2).
882 The O_DIRECT flag was introduced in SGI IRIX, where it has alignment
884 restrictions similar to those of Linux 2.4. IRIX has also a fcntl(2)
885 call to query appropriate alignments, and sizes. FreeBSD 4.x intro‐
886 duced a flag of the same name, but without alignment restrictions.
887 O_DIRECT support was added under Linux in kernel version 2.4.10. Older
889 Linux kernels simply ignore this flag. Some filesystems may not imple‐
890 ment the flag, in which case open() fails with the error EINVAL if it
891 is used.
892 Applications should avoid mixing O_DIRECT and normal I/O to the same
894 file, and especially to overlapping byte regions in the same file.
895 Even when the filesystem correctly handles the coherency issues in this
896 situation, overall I/O throughput is likely to be slower than using ei‐
897 ther mode alone. Likewise, applications should avoid mixing mmap(2) of
898 files with direct I/O to the same files.
899 The behavior of O_DIRECT with NFS will differ from local filesystems.
901 Older kernels, or kernels configured in certain ways, may not support
902 this combination. The NFS protocol does not support passing the flag
903 to the server, so O_DIRECT I/O will bypass the page cache only on the
904 client; the server may still cache the I/O. The client asks the server
905 to make the I/O synchronous to preserve the synchronous semantics of
906 O_DIRECT. Some servers will perform poorly under these circumstances,
907 especially if the I/O size is small. Some servers may also be config‐
908 ured to lie to clients about the I/O having reached stable storage;
909 this will avoid the performance penalty at some risk to data integrity
910 in the event of server power failure. The Linux NFS client places no
911 alignment restrictions on O_DIRECT I/O.
912 In summary, O_DIRECT is a potentially powerful tool that should be used
914 with caution. It is recommended that applications treat use of O_DI‐
915 RECT as a performance option which is disabled by default.
916
918 Currently, it is not possible to enable signal-driven I/O by specifying
919 O_ASYNC when calling open(); use fcntl(2) to enable this flag.
920 One must check for two different error codes, EISDIR and ENOENT, when
922 trying to determine whether the kernel supports O_TMPFILE functional‐
923 ity.
924 When both O_CREAT and O_DIRECTORY are specified in flags and the file
926 specified by pathname does not exist, open() will create a regular file
927 (i.e., O_DIRECTORY is ignored).
928
930 chmod(2), chown(2), close(2), dup(2), fcntl(2), link(2), lseek(2),
931 mknod(2), mmap(2), mount(2), open_by_handle_at(2), openat2(2), read(2),
932 socket(2), stat(2), umask(2), unlink(2), write(2), fopen(3), acl(5),
933 fifo(7), inode(7), path_resolution(7), symlink(7)
934
936 This page is part of release 5.10 of the Linux man-pages project. A
937 description of the project, information about reporting bugs, and the
938 latest version of this page, can be found at
939 https://www.kernel.org/doc/man-pages/.
940Linux 2020-11-01 OPEN(2)