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