1OPEN(2)                    Linux Programmer's Manual                   OPEN(2)
2
3
4

NAME

6       open, openat, creat - open and possibly create a file
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/stat.h>
11       #include <fcntl.h>
12
13       int open(const char *pathname, int flags);
14       int open(const char *pathname, int flags, mode_t mode);
15
16       int creat(const char *pathname, mode_t mode);
17
18       int openat(int dirfd, const char *pathname, int flags);
19       int openat(int dirfd, const char *pathname, int flags, mode_t mode);
20
21       /* Documented separately, in openat2(2): */
22       int openat2(int dirfd, const char *pathname,
23                   const struct open_how *how, size_t size);
24
25   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
26
27       openat():
28           Since glibc 2.10:
29               _POSIX_C_SOURCE >= 200809L
30           Before glibc 2.10:
31               _ATFILE_SOURCE
32

DESCRIPTION

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
38       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
42       descriptor not currently open for the process.
43
44       By  default,  the  new  file descriptor is set to remain open across an
45       execve(2) (i.e., the  FD_CLOEXEC  file  descriptor  flag  described  in
46       fcntl(2)  is  initially disabled); the O_CLOEXEC flag, described below,
47       can be used to change this default.  The file  offset  is  set  to  the
48       beginning of the file (see lseek(2)).
49
50       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
58       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
62       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
69       operations.  The file status flags can be retrieved and (in some cases)
70       modified; see fcntl(2) for details.
71
72       The  full  list of file creation flags and file status flags is as fol‐
73       lows:
74
75       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
79              operation are performed as a single atomic step.
80
81              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
83              because  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
87       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
90              becomes  possible  on  this  file  descriptor.   This feature is
91              available only  for  terminals,  pseudoterminals,  sockets,  and
92              (since  Linux  2.6)  pipes  and FIFOs.  See fcntl(2) for further
93              details.  See also BUGS, below.
94
95       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
98              fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag.
99
100              Note that the use of this  flag  is  essential  in  some  multi‐
101              threaded  programs,  because  using  a separate fcntl(2) F_SETFD
102              operation to set the FD_CLOEXEC flag does not suffice  to  avoid
103              race  conditions  where  one  thread opens a file descriptor and
104              attempts to set its close-on-exec flag  using  fcntl(2)  at  the
105              same  time  as  another  thread  does  a fork(2) plus execve(2).
106              Depending on the order of execution, the race may  lead  to  the
107              file  descriptor returned by open() being unintentionally leaked
108              to the program executed by the child process created by fork(2).
109              (This  kind of race is in principle possible for any system call
110              that creates a file descriptor whose close-on-exec  flag  should
111              be  set, and various other Linux system calls provide an equiva‐
112              lent of the O_CLOEXEC flag to deal with this problem.)
113
114       O_CREAT
115              If pathname does not exist, create it as a regular file.
116
117              The owner (user ID) of the new file is set to the effective user
118              ID of the process.
119
120              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
129              The mode argument specifies the file mode bits be applied when a
130              new  file  is  created.   This  argument  must  be supplied when
131              O_CREAT or O_TMPFILE is specified in flags; if  neither  O_CREAT
132              nor O_TMPFILE is specified, then mode is ignored.  The effective
133              mode is modified by the process's umask in the usual way: in the
134              absence  of  a  default  ACL,  the  mode  of the created file is
135              (mode & ~umask).  Note that this mode  applies  only  to  future
136              accesses of the newly created file; the open() call that creates
137              a read-only file may well return a read/write file descriptor.
138
139              The following symbolic constants are provided for mode:
140
141              S_IRWXU  00700 user (file owner) has read,  write,  and  execute
142                       permission
143
144              S_IRUSR  00400 user has read permission
145
146              S_IWUSR  00200 user has write permission
147
148              S_IXUSR  00100 user has execute permission
149
150              S_IRWXG  00070 group has read, write, and execute permission
151
152              S_IRGRP  00040 group has read permission
153
154              S_IWGRP  00020 group has write permission
155
156              S_IXGRP  00010 group has execute permission
157
158              S_IRWXO  00007 others have read, write, and execute permission
159
160              S_IROTH  00004 others have read permission
161
162              S_IWOTH  00002 others have write permission
163
164              S_IXOTH  00001 others have execute permission
165
166              According  to  POSIX, the effect when other bits are set in mode
167              is unspecified.  On Linux, the following bits are  also  honored
168              in mode:
169
170              S_ISUID  0004000 set-user-ID bit
171
172              S_ISGID  0002000 set-group-ID bit (see inode(7)).
173
174              S_ISVTX  0001000 sticky bit (see inode(7)).
175
176       O_DIRECT (since Linux 2.4.10)
177              Try  to minimize cache effects of the I/O to and from this file.
178              In general this will degrade performance, but it  is  useful  in
179              special  situations,  such  as  when  applications  do their own
180              caching.  File I/O is done directly to/from user-space  buffers.
181              The  O_DIRECT  flag  on its own makes an effort to transfer data
182              synchronously, but does not give the guarantees  of  the  O_SYNC
183              flag that data and necessary metadata are transferred.  To guar‐
184              antee synchronous I/O,  O_SYNC  must  be  used  in  addition  to
185              O_DIRECT.  See NOTES below for further discussion.
186
187              A  semantically  similar  (but  deprecated)  interface for block
188              devices is described in raw(8).
189
190       O_DIRECTORY
191              If pathname is not a directory, cause the open  to  fail.   This
192              flag  was  added  in kernel version 2.1.126, to avoid denial-of-
193              service problems if opendir(3) is  called  on  a  FIFO  or  tape
194              device.
195
196       O_DSYNC
197              Write  operations  on  the  file  will complete according to the
198              requirements of synchronized I/O data integrity completion.
199
200              By the time write(2) (and similar) return, the output  data  has
201              been transferred to the underlying hardware, along with any file
202              metadata that would be required to retrieve that data (i.e.,  as
203              though  each  write(2)  was followed by a call to fdatasync(2)).
204              See NOTES below.
205
206       O_EXCL Ensure that this call creates the file: if this flag  is  speci‐
207              fied  in  conjunction with O_CREAT, and pathname already exists,
208              then open() fails with the error EEXIST.
209
210              When these two flags are specified, symbolic links are not  fol‐
211              lowed: if pathname is a symbolic link, then open() fails regard‐
212              less of where the symbolic link points.
213
214              In general, the behavior of O_EXCL is undefined if  it  is  used
215              without  O_CREAT.   There  is  one  exception:  on Linux 2.6 and
216              later, O_EXCL can be used without O_CREAT if pathname refers  to
217              a  block  device.   If  the block device is in use by the system
218              (e.g., mounted), open() fails with the error EBUSY.
219
220              On NFS, O_EXCL is supported only when using NFSv3  or  later  on
221              kernel  2.6  or later.  In NFS environments where O_EXCL support
222              is not provided, programs that rely on it for performing locking
223              tasks  will  contain  a  race condition.  Portable programs that
224              want to perform atomic file locking using a lockfile,  and  need
225              to avoid reliance on NFS support for O_EXCL, can create a unique
226              file on the same filesystem (e.g.,  incorporating  hostname  and
227              PID),  and  use  link(2)  to  make  a  link to the lockfile.  If
228              link(2) returns 0,  the  lock  is  successful.   Otherwise,  use
229              stat(2)  on  the  unique  file  to  check  if its link count has
230              increased to 2, in which case the lock is also successful.
231
232       O_LARGEFILE
233              (LFS) Allow files whose sizes cannot be represented in an  off_t
234              (but  can  be  represented  in  an  off64_t)  to be opened.  The
235              _LARGEFILE64_SOURCE macro must be defined (before including  any
236              header  files)  in order to obtain this definition.  Setting the
237              _FILE_OFFSET_BITS feature test macro to 64  (rather  than  using
238              O_LARGEFILE) is the preferred method of accessing large files on
239              32-bit systems (see feature_test_macros(7)).
240
241       O_NOATIME (since Linux 2.6.8)
242              Do not update the file last access time (st_atime in the  inode)
243              when the file is read(2).
244
245              This  flag  can  be employed only if one of the following condi‐
246              tions is true:
247
248              *  The effective UID of the process matches the owner UID of the
249                 file.
250
251              *  The calling process has the CAP_FOWNER capability in its user
252                 namespace and the owner UID of the file has a mapping in  the
253                 namespace.
254
255              This  flag  is  intended for use by indexing or backup programs,
256              where its use can significantly reduce the amount of disk activ‐
257              ity.   This  flag  may not be effective on all filesystems.  One
258              example is NFS, where the server maintains the access time.
259
260       O_NOCTTY
261              If pathname refers to a terminal device—see tty(4)—it  will  not
262              become  the  process's  controlling terminal even if the process
263              does not have one.
264
265       O_NOFOLLOW
266              If the trailing component (i.e., basename) of pathname is a sym‐
267              bolic link, then the open fails, with the error ELOOP.  Symbolic
268              links in earlier components of the pathname will still  be  fol‐
269              lowed.   (Note  that the ELOOP error that can occur in this case
270              is indistinguishable from the case where an open  fails  because
271              there  are  too many symbolic links found while resolving compo‐
272              nents in the prefix part of the pathname.)
273
274              This flag is a FreeBSD extension, which was added  to  Linux  in
275              version  2.1.126,  and  has  subsequently  been  standardized in
276              POSIX.1-2008.
277
278              See also O_PATH below.
279
280       O_NONBLOCK or O_NDELAY
281              When possible, the file is opened in nonblocking mode.   Neither
282              the  open()  nor  any  subsequent  I/O  operations  on  the file
283              descriptor which is returned will cause the calling  process  to
284              wait.
285
286              Note  that  the setting of this flag has no effect on the opera‐
287              tion of poll(2), select(2), epoll(7), and similar,  since  those
288              interfaces  merely  inform  the  caller  about  whether  a  file
289              descriptor is "ready", meaning that an I/O  operation  performed
290              on  the file descriptor with the O_NONBLOCK flag clear would not
291              block.
292
293              Note that this flag has no effect for regular  files  and  block
294              devices;  that  is,  I/O  operations  will  (briefly) block when
295              device activity is required, regardless of whether O_NONBLOCK is
296              set.   Since  O_NONBLOCK  semantics  might  eventually be imple‐
297              mented, applications should not depend  upon  blocking  behavior
298              when specifying this flag for regular files and block devices.
299
300              For  the handling of FIFOs (named pipes), see also fifo(7).  For
301              a discussion of the effect of  O_NONBLOCK  in  conjunction  with
302              mandatory file locks and with file leases, see fcntl(2).
303
304       O_PATH (since Linux 2.6.39)
305              Obtain  a  file descriptor that can be used for two purposes: to
306              indicate a location in the filesystem tree and to perform opera‐
307              tions  that  act  purely at the file descriptor level.  The file
308              itself is not opened, and other file operations (e.g.,  read(2),
309              write(2), fchmod(2), fchown(2), fgetxattr(2), ioctl(2), mmap(2))
310              fail with the error EBADF.
311
312              The following operations can be performed on the resulting  file
313              descriptor:
314
315              *  close(2).
316
317              *  fchdir(2),  if  the  file  descriptor  refers  to a directory
318                 (since Linux 3.5).
319
320              *  fstat(2) (since Linux 3.6).
321
322              *  fstatfs(2) (since Linux 3.12).
323
324              *  Duplicating the file descriptor  (dup(2),  fcntl(2)  F_DUPFD,
325                 etc.).
326
327              *  Getting  and  setting file descriptor flags (fcntl(2) F_GETFD
328                 and F_SETFD).
329
330              *  Retrieving open file status flags using the fcntl(2)  F_GETFL
331                 operation: the returned flags will include the bit O_PATH.
332
333              *  Passing the file descriptor as the dirfd argument of openat()
334                 and the other "*at()" system calls.  This includes  linkat(2)
335                 with  AT_EMPTY_PATH  (or  via procfs using AT_SYMLINK_FOLLOW)
336                 even if the file is not a directory.
337
338              *  Passing the file descriptor to another  process  via  a  UNIX
339                 domain socket (see SCM_RIGHTS in unix(7)).
340
341              When  O_PATH  is  specified  in  flags,  flag  bits  other  than
342              O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW are ignored.
343
344              Opening a file or directory with the  O_PATH  flag  requires  no
345              permissions  on the object itself (but does require execute per‐
346              mission on the directories in the path  prefix).   Depending  on
347              the  subsequent operation, a check for suitable file permissions
348              may be performed (e.g., fchdir(2) requires execute permission on
349              the  directory referred to by its file descriptor argument).  By
350              contrast, obtaining a reference to a filesystem object by  open‐
351              ing it with the O_RDONLY flag requires that the caller have read
352              permission on the object, even  when  the  subsequent  operation
353              (e.g.,  fchdir(2), fstat(2)) does not require read permission on
354              the object.
355
356              If pathname is a symbolic link and the O_NOFOLLOW flag  is  also
357              specified,  then the call returns a file descriptor referring to
358              the symbolic link.  This file descriptor  can  be  used  as  the
359              dirfd  argument  in calls to fchownat(2), fstatat(2), linkat(2),
360              and readlinkat(2) with an empty pathname to have the calls oper‐
361              ate on the symbolic link.
362
363              If  pathname  refers to an automount point that has not yet been
364              triggered, so no other filesystem is mounted  on  it,  then  the
365              call returns a file descriptor referring to the automount direc‐
366              tory without triggering a mount.  fstatfs(2) can then be used to
367              determine  if  it  is,  in  fact, an untriggered automount point
368              (.f_type == AUTOFS_SUPER_MAGIC).
369
370              One use of O_PATH for regular files is to provide the equivalent
371              of  POSIX.1's  O_EXEC  functionality.  This permits us to open a
372              file for which we have execute permission but not  read  permis‐
373              sion,  and then execute that file, with steps something like the
374              following:
375
376                  char buf[PATH_MAX];
377                  fd = open("some_prog", O_PATH);
378                  snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
379                  execl(buf, "some_prog", (char *) NULL);
380
381              An O_PATH file descriptor can also be passed as the argument  of
382              fexecve(3).
383
384       O_SYNC Write  operations  on  the  file  will complete according to the
385              requirements of synchronized I/O file integrity  completion  (by
386              contrast  with  the  synchronized  I/O data integrity completion
387              provided by O_DSYNC.)
388
389              By the time write(2) (or similar) returns, the output  data  and
390              associated file metadata have been transferred to the underlying
391              hardware (i.e., as though each write(2) was followed by  a  call
392              to fsync(2)).  See NOTES below.
393
394       O_TMPFILE (since Linux 3.11)
395              Create an unnamed temporary regular file.  The pathname argument
396              specifies a directory; an unnamed inode will be created in  that
397              directory's  filesystem.  Anything written to the resulting file
398              will be lost when the last file descriptor is closed, unless the
399              file is given a name.
400
401              O_TMPFILE  must be specified with one of O_RDWR or O_WRONLY and,
402              optionally, O_EXCL.  If O_EXCL is not specified, then  linkat(2)
403              can be used to link the temporary file into the filesystem, mak‐
404              ing it permanent, using code like the following:
405
406                  char path[PATH_MAX];
407                  fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
408                                          S_IRUSR | S_IWUSR);
409
410                  /* File I/O on 'fd'... */
411
412                  linkat(fd, NULL, AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
413
414                  /* If the caller doesn't have the CAP_DAC_READ_SEARCH
415                     capability (needed to use AT_EMPTY_PATH with linkat(2)),
416                     and there is a proc(5) filesystem mounted, then the
417                     linkat(2) call above can be replaced with:
418
419                  snprintf(path, PATH_MAX,  "/proc/self/fd/%d", fd);
420                  linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
421                                          AT_SYMLINK_FOLLOW);
422                  */
423
424              In this case, the open() mode argument determines the file  per‐
425              mission mode, as with O_CREAT.
426
427              Specifying  O_EXCL in conjunction with O_TMPFILE prevents a tem‐
428              porary file from being linked into the filesystem in  the  above
429              manner.   (Note  that the meaning of O_EXCL in this case is dif‐
430              ferent from the meaning of O_EXCL otherwise.)
431
432              There are two main use cases for O_TMPFILE:
433
434              *  Improved tmpfile(3) functionality: race-free creation of tem‐
435                 porary  files that (1) are automatically deleted when closed;
436                 (2) can never be reached via any pathname; (3) are  not  sub‐
437                 ject to symlink attacks; and (4) do not require the caller to
438                 devise unique names.
439
440              *  Creating a file that is initially invisible,  which  is  then
441                 populated with data and adjusted to have appropriate filesys‐
442                 tem attributes  (fchown(2),  fchmod(2),  fsetxattr(2),  etc.)
443                 before being atomically linked into the filesystem in a fully
444                 formed state (using linkat(2) as described above).
445
446              O_TMPFILE requires support by the underlying filesystem; only  a
447              subset  of  Linux filesystems provide that support.  In the ini‐
448              tial implementation, support was provided  in  the  ext2,  ext3,
449              ext4,  UDF,  Minix,  and  shmem  filesystems.  Support for other
450              filesystems has subsequently been added as follows:  XFS  (Linux
451              3.15);  Btrfs  (Linux 3.16); F2FS (Linux 3.16); and ubifs (Linux
452              4.9)
453
454       O_TRUNC
455              If the file already exists and is a regular file and the  access
456              mode  allows  writing  (i.e.,  is O_RDWR or O_WRONLY) it will be
457              truncated to length 0.  If the file is a FIFO or terminal device
458              file,  the  O_TRUNC  flag  is ignored.  Otherwise, the effect of
459              O_TRUNC is unspecified.
460
461   creat()
462       A call to creat() is equivalent to calling open() with flags  equal  to
463       O_CREAT|O_WRONLY|O_TRUNC.
464
465   openat()
466       The  openat()  system  call operates in exactly the same way as open(),
467       except for the differences described here.
468
469       If the pathname given in pathname is relative, then it  is  interpreted
470       relative  to  the  directory  referred  to by the file descriptor dirfd
471       (rather than relative to the current working directory of  the  calling
472       process, as is done by open() for a relative pathname).
473
474       If  pathname  is relative and dirfd is the special value AT_FDCWD, then
475       pathname is interpreted relative to the current  working  directory  of
476       the calling process (like open()).
477
478       If pathname is absolute, then dirfd is ignored.
479
480   openat2(2)
481       The  openat2(2) system call is an extension of openat(), and provides a
482       superset of the features of openat().  It is documented separately,  in
483       openat2(2).
484

RETURN VALUE

486       open(), openat(), and creat() return the new file descriptor (a nonneg‐
487       ative integer), or -1 if an error occurred (in which case, errno is set
488       appropriately).
489

ERRORS

491       open(), openat(), and creat() can fail with the following errors:
492
493       EACCES The  requested access to the file is not allowed, or search per‐
494              mission is denied for one of the directories in the path  prefix
495              of  pathname,  or the file did not exist yet and write access to
496              the parent directory is not  allowed.   (See  also  path_resolu‐
497              tion(7).)
498
499       EACCES Where   O_CREAT   is  specified,  the  protected_fifos  or  pro‐
500              tected_regular sysctl is enabled, the file already exists and is
501              a  FIFO  or  regular  file, the owner of the file is neither the
502              current user nor the owner of the containing directory, and  the
503              containing  directory  is  both  world-  or  group-writable  and
504              sticky.  For details, see the descriptions of  /proc/sys/fs/pro‐
505              tected_fifos and /proc/sys/fs/protected_regular in proc(5).
506
507       EDQUOT Where  O_CREAT  is  specified,  the file does not exist, and the
508              user's quota of disk blocks or inodes on the filesystem has been
509              exhausted.
510
511       EEXIST pathname already exists and O_CREAT and O_EXCL were used.
512
513       EFAULT pathname points outside your accessible address space.
514
515       EFBIG  See EOVERFLOW.
516
517       EINTR  While  blocked  waiting  to  complete  an  open of a slow device
518              (e.g., a FIFO; see fifo(7)), the call was interrupted by a  sig‐
519              nal handler; see signal(7).
520
521       EINVAL The  filesystem  does  not support the O_DIRECT flag.  See NOTES
522              for more information.
523
524       EINVAL Invalid value in flags.
525
526       EINVAL O_TMPFILE was specified  in  flags,  but  neither  O_WRONLY  nor
527              O_RDWR was specified.
528
529       EINVAL O_CREAT  was  specified in flags and the final component ("base‐
530              name") of the new file's pathname is invalid (e.g., it  contains
531              characters not permitted by the underlying filesystem).
532
533       EINVAL The  final  component ("basename") of pathname is invalid (e.g.,
534              it contains characters not permitted by the underlying  filesys‐
535              tem).
536
537       EISDIR pathname refers to a directory and the access requested involved
538              writing (that is, O_WRONLY or O_RDWR is set).
539
540       EISDIR pathname refers to an existing directory, O_TMPFILE and  one  of
541              O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
542              sion does not provide the O_TMPFILE functionality.
543
544       ELOOP  Too many symbolic links were encountered in resolving pathname.
545
546       ELOOP  pathname was a symbolic link, and flags specified O_NOFOLLOW but
547              not O_PATH.
548
549       EMFILE The per-process limit on the number of open file descriptors has
550              been reached (see the  description  of  RLIMIT_NOFILE  in  getr‐
551              limit(2)).
552
553       ENAMETOOLONG
554              pathname was too long.
555
556       ENFILE The system-wide limit on the total number of open files has been
557              reached.
558
559       ENODEV pathname refers to a device special file  and  no  corresponding
560              device  exists.   (This is a Linux kernel bug; in this situation
561              ENXIO must be returned.)
562
563       ENOENT O_CREAT is not set and the named file does not exist.
564
565       ENOENT A directory component in pathname does not exist or  is  a  dan‐
566              gling symbolic link.
567
568       ENOENT pathname refers to a nonexistent directory, O_TMPFILE and one of
569              O_WRONLY or O_RDWR were specified in flags, but this kernel ver‐
570              sion does not provide the O_TMPFILE functionality.
571
572       ENOMEM The  named  file is a FIFO, but memory for the FIFO buffer can't
573              be allocated because the per-user hard limit on  memory  alloca‐
574              tion  for  pipes  has  been reached and the caller is not privi‐
575              leged; see pipe(7).
576
577       ENOMEM Insufficient kernel memory was available.
578
579       ENOSPC pathname was to be created but the  device  containing  pathname
580              has no room for the new file.
581
582       ENOTDIR
583              A  component  used as a directory in pathname is not, in fact, a
584              directory, or O_DIRECTORY was specified and pathname was  not  a
585              directory.
586
587       ENXIO  O_NONBLOCK  |  O_WRONLY is set, the named file is a FIFO, and no
588              process has the FIFO open for reading.
589
590       ENXIO  The file is a device special file and  no  corresponding  device
591              exists.
592
593       ENXIO  The file is a UNIX domain socket.
594
595       EOPNOTSUPP
596              The filesystem containing pathname does not support O_TMPFILE.
597
598       EOVERFLOW
599              pathname  refers  to  a  regular  file  that  is too large to be
600              opened.  The usual scenario here is that an application compiled
601              on  a  32-bit  platform  without -D_FILE_OFFSET_BITS=64 tried to
602              open a  file  whose  size  exceeds  (1<<31)-1  bytes;  see  also
603              O_LARGEFILE  above.   This is the error specified by POSIX.1; in
604              kernels before 2.6.24, Linux gave the error EFBIG for this case.
605
606       EPERM  The O_NOATIME flag was specified, but the effective user  ID  of
607              the  caller  did  not match the owner of the file and the caller
608              was not privileged.
609
610       EPERM  The operation was prevented by a file seal; see fcntl(2).
611
612       EROFS  pathname refers to a file on a read-only  filesystem  and  write
613              access was requested.
614
615       ETXTBSY
616              pathname  refers to an executable image which is currently being
617              executed and write access was requested.
618
619       ETXTBSY
620              pathname refers to a file that is currently in  use  as  a  swap
621              file, and the O_TRUNC flag was specified.
622
623       ETXTBSY
624              pathname  refers  to  a file that is currently being read by the
625              kernel (e.g. for module/firmware loading), and write access  was
626              requested.
627
628       EWOULDBLOCK
629              The O_NONBLOCK flag was specified, and an incompatible lease was
630              held on the file (see fcntl(2)).
631
632       The following additional errors can occur for openat():
633
634       EBADF  dirfd is not a valid file descriptor.
635
636       ENOTDIR
637              pathname is a relative pathname and dirfd is a  file  descriptor
638              referring to a file other than a directory.
639

VERSIONS

641       openat() was added to Linux in kernel 2.6.16; library support was added
642       to glibc in version 2.4.
643

CONFORMING TO

645       open(), creat() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
646
647       openat(): POSIX.1-2008.
648
649       openat2(2) is Linux-specific.
650
651       The O_DIRECT, O_NOATIME, O_PATH, and  O_TMPFILE  flags  are  Linux-spe‐
652       cific.  One must define _GNU_SOURCE to obtain their definitions.
653
654       The  O_CLOEXEC,  O_DIRECTORY, and O_NOFOLLOW flags are not specified in
655       POSIX.1-2001, but are specified in POSIX.1-2008.  Since glibc 2.12, one
656       can  obtain their definitions by defining either _POSIX_C_SOURCE with a
657       value greater than or equal to 200809L or _XOPEN_SOURCE  with  a  value
658       greater  than  or equal to 700.  In glibc 2.11 and earlier, one obtains
659       the definitions by defining _GNU_SOURCE.
660
661       As  noted  in  feature_test_macros(7),  feature  test  macros  such  as
662       _POSIX_C_SOURCE,  _XOPEN_SOURCE, and _GNU_SOURCE must be defined before
663       including any header files.
664

NOTES

666       Under Linux, the O_NONBLOCK flag is sometimes used in cases  where  one
667       wants  to  open  but does not necessarily have the intention to read or
668       write.  For example, this may be used to open a device in order to  get
669       a file descriptor for use with ioctl(2).
670
671       The  (undefined)  effect of O_RDONLY | O_TRUNC varies among implementa‐
672       tions.  On many systems the file is actually truncated.
673
674       Note that open() can open device special files, but creat() cannot cre‐
675       ate them; use mknod(2) instead.
676
677       If  the  file is newly created, its st_atime, st_ctime, st_mtime fields
678       (respectively, time of last access, time of  last  status  change,  and
679       time  of  last  modification; see stat(2)) are set to the current time,
680       and so are the st_ctime and st_mtime fields of  the  parent  directory.
681       Otherwise,  if  the  file  is modified because of the O_TRUNC flag, its
682       st_ctime and st_mtime fields are set to the current time.
683
684       The files in the /proc/[pid]/fd directory show the open  file  descrip‐
685       tors   of   the   process   with   the  PID  pid.   The  files  in  the
686       /proc/[pid]/fdinfo directory show even  more  information  about  these
687       file  descriptors.   See  proc(5)  for further details of both of these
688       directories.
689
690       The Linux header file <asm/fcntl.h> doesn't define O_ASYNC;  the  (BSD-
691       derived) FASYNC synonym is defined instead.
692
693   Open file descriptions
694       The term open file description is the one used by POSIX to refer to the
695       entries in the system-wide table of open  files.   In  other  contexts,
696       this  object  is  variously  also called an "open file object", a "file
697       handle", an "open file table entry", or—in kernel-developer  parlance—a
698       struct file.
699
700       When  a  file  descriptor  is duplicated (using dup(2) or similar), the
701       duplicate refers to the same open file description as the original file
702       descriptor,  and  the  two file descriptors consequently share the file
703       offset and file status flags.  Such sharing can also occur between pro‐
704       cesses:  a child process created via fork(2) inherits duplicates of its
705       parent's file descriptors, and those duplicates refer to the same  open
706       file descriptions.
707
708       Each  open() of a file creates a new open file description; thus, there
709       may be multiple open file descriptions corresponding to a file inode.
710
711       On Linux, one can use the kcmp(2) KCMP_FILE operation to  test  whether
712       two  file  descriptors  (in  the  same process or in two different pro‐
713       cesses) refer to the same open file description.
714
715   Synchronized I/O
716       The POSIX.1-2008 "synchronized I/O" option specifies different variants
717       of  synchronized  I/O,  and specifies the open() flags O_SYNC, O_DSYNC,
718       and O_RSYNC for controlling the behavior.   Regardless  of  whether  an
719       implementation  supports  this option, it must at least support the use
720       of O_SYNC for regular files.
721
722       Linux implements O_SYNC and O_DSYNC, but not O_RSYNC.  Somewhat  incor‐
723       rectly,  glibc  defines  O_RSYNC  to  have  the  same  value as O_SYNC.
724       (O_RSYNC is defined in the Linux header file <asm/fcntl.h>  on  HP  PA-
725       RISC, but it is not used.)
726
727       O_SYNC  provides  synchronized  I/O  file integrity completion, meaning
728       write operations will flush data and all  associated  metadata  to  the
729       underlying  hardware.  O_DSYNC provides synchronized I/O data integrity
730       completion, meaning write operations will flush data to the  underlying
731       hardware,  but  will  only  flush metadata updates that are required to
732       allow a subsequent  read  operation  to  complete  successfully.   Data
733       integrity  completion can reduce the number of disk operations that are
734       required for applications  that  don't  need  the  guarantees  of  file
735       integrity completion.
736
737       To  understand the difference between the two types of completion, con‐
738       sider two pieces of file metadata: the file last modification timestamp
739       (st_mtime)  and  the file length.  All write operations will update the
740       last file modification timestamp, but only writes that add data to  the
741       end  of  the  file  will change the file length.  The last modification
742       timestamp is not needed to ensure that a read  completes  successfully,
743       but  the  file  length is.  Thus, O_DSYNC would only guarantee to flush
744       updates to the file length metadata (whereas O_SYNC would  also  always
745       flush the last modification timestamp metadata).
746
747       Before Linux 2.6.33, Linux implemented only the O_SYNC flag for open().
748       However, when that flag was specified, most filesystems  actually  pro‐
749       vided  the  equivalent  of  synchronized  I/O data integrity completion
750       (i.e., O_SYNC was actually implemented as the equivalent of O_DSYNC).
751
752       Since Linux 2.6.33, proper O_SYNC support  is  provided.   However,  to
753       ensure backward binary compatibility, O_DSYNC was defined with the same
754       value as the historical O_SYNC, and O_SYNC was defined as a  new  (two-
755       bit)  flag  value  that  includes the O_DSYNC flag value.  This ensures
756       that applications compiled against new headers  get  at  least  O_DSYNC
757       semantics on pre-2.6.33 kernels.
758
759   C library/kernel differences
760       Since  version  2.26, the glibc wrapper function for open() employs the
761       openat() system call, rather than the kernel's open() system call.  For
762       certain architectures, this is also true in glibc versions before 2.26.
763
764   NFS
765       There  are  many infelicities in the protocol underlying NFS, affecting
766       amongst others O_SYNC and O_NDELAY.
767
768       On NFS filesystems with UID mapping enabled, open() may return  a  file
769       descriptor  but,  for example, read(2) requests are denied with EACCES.
770       This is because the client performs open() by checking the permissions,
771       but  UID  mapping  is  performed  by  the  server  upon  read and write
772       requests.
773
774   FIFOs
775       Opening the read or write end of a FIFO blocks until the other  end  is
776       also  opened  (by  another process or thread).  See fifo(7) for further
777       details.
778
779   File access mode
780       Unlike the other values that can be specified in flags, the access mode
781       values  O_RDONLY,  O_WRONLY, and O_RDWR do not specify individual bits.
782       Rather, they define the low order two bits of flags,  and  are  defined
783       respectively  as 0, 1, and 2.  In other words, the combination O_RDONLY
784       | O_WRONLY is a logical error, and certainly does  not  have  the  same
785       meaning as O_RDWR.
786
787       Linux  reserves  the  special, nonstandard access mode 3 (binary 11) in
788       flags to mean: check for read and write  permission  on  the  file  and
789       return  a  file  descriptor  that can't be used for reading or writing.
790       This nonstandard access mode is used by some Linux drivers to return  a
791       file  descriptor  that  is to be used only for device-specific ioctl(2)
792       operations.
793
794   Rationale for openat() and other directory file descriptor APIs
795       openat() and the other system calls and library functions that  take  a
796       directory  file  descriptor  argument (i.e., execveat(2), faccessat(2),
797       fanotify_mark(2),  fchmodat(2),  fchownat(2),  fspick(2),   fstatat(2),
798       futimesat(2),   linkat(2),   mkdirat(2),   move_mount(2),   mknodat(2),
799       name_to_handle_at(2),    open_tree(2),    openat2(2),    readlinkat(2),
800       renameat(2),  statx(2),  symlinkat(2), unlinkat(2), utimensat(2), mkfi‐
801       foat(3), and scandirat(3)) address two problems with the  older  inter‐
802       faces  that  preceded  them.   Here, the explanation is in terms of the
803       openat() call, but the rationale is analogous for the other interfaces.
804
805       First, openat() allows an application to  avoid  race  conditions  that
806       could  occur  when using open() to open files in directories other than
807       the current working directory.  These race conditions result  from  the
808       fact  that some component of the directory prefix given to open() could
809       be changed in parallel with the call to open().  Suppose, for  example,
810       that  we  wish  to  create  the  file  dir1/dir2/xxx.dep  if  the  file
811       dir1/dir2/xxx exists.  The problem is that between the existence  check
812       and  the  file-creation  step,  dir1  or  dir2 (which might be symbolic
813       links) could be modified to point to a different location.  Such  races
814       can  be  avoided by opening a file descriptor for the target directory,
815       and then specifying that file descriptor as the dirfd argument of (say)
816       fstatat(2) and openat().  The use of the dirfd file descriptor also has
817       other benefits:
818
819       *  the file descriptor is a stable reference to the directory, even  if
820          the directory is renamed; and
821
822       *  the  open  file  descriptor  prevents the underlying filesystem from
823          being dismounted, just as when  a  process  has  a  current  working
824          directory on a filesystem.
825
826       Second,  openat()  allows  the  implementation of a per-thread "current
827       working directory", via file descriptor(s) maintained by  the  applica‐
828       tion.   (This functionality can also be obtained by tricks based on the
829       use of /proc/self/fd/dirfd, but less efficiently.)
830
831       The dirfd argument for these APIs can be obtained by  using  open()  or
832       openat()  to  open  a directory (with either the O_RDONLY or the O_PATH
833       flag).  Alternatively, such a file descriptor can be obtained by apply‐
834       ing dirfd(3) to a directory stream created using opendir(3).
835
836       When these APIs are given a dirfd argument of AT_FDCWD or the specified
837       pathname is absolute, then they handle their pathname argument  in  the
838       same  was  as  the  corresponding  conventional APIs.  However, in this
839       case, several of the APIs have a flags argument that provides access to
840       functionality that is not available with the corresponding conventional
841       APIs.
842
843   O_DIRECT
844       The O_DIRECT flag may impose alignment restrictions on the  length  and
845       address  of  user-space  buffers and the file offset of I/Os.  In Linux
846       alignment restrictions vary by filesystem and kernel version and  might
847       be  absent entirely.  However there is currently no filesystem-indepen‐
848       dent interface for an application to discover these restrictions for  a
849       given  file  or  filesystem.  Some filesystems provide their own inter‐
850       faces for doing  so,  for  example  the  XFS_IOC_DIOINFO  operation  in
851       xfsctl(3).
852
853       Under  Linux  2.4, transfer sizes, and the alignment of the user buffer
854       and the file offset must all be multiples of the logical block size  of
855       the filesystem.  Since Linux 2.6.0, alignment to the logical block size
856       of the underlying storage (typically 512 bytes) suffices.  The  logical
857       block  size can be determined using the ioctl(2) BLKSSZGET operation or
858       from the shell using the command:
859
860           blockdev --getss
861
862       O_DIRECT I/Os should never be run concurrently with the fork(2)  system
863       call, if the memory buffer is a private mapping (i.e., any mapping cre‐
864       ated with the mmap(2) MAP_PRIVATE flag; this includes memory  allocated
865       on  the heap and statically allocated buffers).  Any such I/Os, whether
866       submitted via an asynchronous I/O interface or from another  thread  in
867       the  process, should be completed before fork(2) is called.  Failure to
868       do so can result in data corruption and undefined  behavior  in  parent
869       and  child  processes.  This restriction does not apply when the memory
870       buffer for the O_DIRECT I/Os was created using shmat(2) or mmap(2) with
871       the  MAP_SHARED  flag.  Nor does this restriction apply when the memory
872       buffer has been advised as MADV_DONTFORK with madvise(2), ensuring that
873       it will not be available to the child after fork(2).
874
875       The  O_DIRECT  flag  was introduced in SGI IRIX, where it has alignment
876       restrictions similar to those of Linux 2.4.  IRIX has also  a  fcntl(2)
877       call  to  query  appropriate alignments, and sizes.  FreeBSD 4.x intro‐
878       duced a flag of the same name, but without alignment restrictions.
879
880       O_DIRECT support was added under Linux in kernel version 2.4.10.  Older
881       Linux kernels simply ignore this flag.  Some filesystems may not imple‐
882       ment the flag, in which case open() fails with the error EINVAL  if  it
883       is used.
884
885       Applications  should  avoid  mixing O_DIRECT and normal I/O to the same
886       file, and especially to overlapping byte  regions  in  the  same  file.
887       Even when the filesystem correctly handles the coherency issues in this
888       situation, overall I/O throughput is likely to  be  slower  than  using
889       either  mode alone.  Likewise, applications should avoid mixing mmap(2)
890       of files with direct I/O to the same files.
891
892       The behavior of O_DIRECT with NFS will differ from  local  filesystems.
893       Older  kernels,  or kernels configured in certain ways, may not support
894       this combination.  The NFS protocol does not support passing  the  flag
895       to  the  server, so O_DIRECT I/O will bypass the page cache only on the
896       client; the server may still cache the I/O.  The client asks the server
897       to  make  the  I/O synchronous to preserve the synchronous semantics of
898       O_DIRECT.  Some servers will perform poorly under these  circumstances,
899       especially  if the I/O size is small.  Some servers may also be config‐
900       ured to lie to clients about the I/O  having  reached  stable  storage;
901       this  will avoid the performance penalty at some risk to data integrity
902       in the event of server power failure.  The Linux NFS client  places  no
903       alignment restrictions on O_DIRECT I/O.
904
905       In summary, O_DIRECT is a potentially powerful tool that should be used
906       with caution.   It  is  recommended  that  applications  treat  use  of
907       O_DIRECT as a performance option which is disabled by default.
908

BUGS

910       Currently, it is not possible to enable signal-driven I/O by specifying
911       O_ASYNC when calling open(); use fcntl(2) to enable this flag.
912
913       One must check for two different error codes, EISDIR and  ENOENT,  when
914       trying  to  determine whether the kernel supports O_TMPFILE functional‐
915       ity.
916
917       When both O_CREAT and O_DIRECTORY are specified in flags and  the  file
918       specified by pathname does not exist, open() will create a regular file
919       (i.e., O_DIRECTORY is ignored).
920

SEE ALSO

922       chmod(2), chown(2),  close(2),  dup(2),  fcntl(2),  link(2),  lseek(2),
923       mknod(2), mmap(2), mount(2), open_by_handle_at(2), openat2(2), read(2),
924       socket(2), stat(2), umask(2), unlink(2),  write(2),  fopen(3),  acl(5),
925       fifo(7), inode(7), path_resolution(7), symlink(7)
926

COLOPHON

928       This  page  is  part of release 5.07 of the Linux man-pages project.  A
929       description of the project, information about reporting bugs,  and  the
930       latest     version     of     this    page,    can    be    found    at
931       https://www.kernel.org/doc/man-pages/.
932
933
934
935Linux                             2020-06-09                           OPEN(2)
Impressum