1open(2)                       System Calls Manual                      open(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

503       On  success, open(), openat(), and creat() return the new file descrip‐
504       tor (a nonnegative integer).  On error, -1 is returned and errno is set
505       to indicate the error.
506

ERRORS

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

VERSIONS

660       The  (undefined)  effect of O_RDONLY | O_TRUNC varies among implementa‐
661       tions.  On many systems the file is actually truncated.
662
663   Synchronized I/O
664       The POSIX.1-2008 "synchronized I/O" option specifies different variants
665       of  synchronized  I/O,  and specifies the open() flags O_SYNC, O_DSYNC,
666       and O_RSYNC for controlling the behavior.  Regardless of whether an im‐
667       plementation  supports this option, it must at least support the use of
668       O_SYNC for regular files.
669
670       Linux implements O_SYNC and O_DSYNC, but not O_RSYNC.  Somewhat  incor‐
671       rectly,  glibc  defines  O_RSYNC  to  have  the  same  value as O_SYNC.
672       (O_RSYNC is defined in the Linux header file <asm/fcntl.h>  on  HP  PA-
673       RISC, but it is not used.)
674
675       O_SYNC  provides  synchronized  I/O  file integrity completion, meaning
676       write operations will flush data and all associated metadata to the un‐
677       derlying  hardware.   O_DSYNC  provides synchronized I/O data integrity
678       completion, meaning write operations will flush data to the  underlying
679       hardware, but will only flush metadata updates that are required to al‐
680       low a subsequent read operation to complete successfully.  Data  integ‐
681       rity  completion  can reduce the number of disk operations that are re‐
682       quired for applications that don't need the guarantees of  file  integ‐
683       rity completion.
684
685       To  understand the difference between the two types of completion, con‐
686       sider two pieces of file metadata: the file last modification timestamp
687       (st_mtime)  and  the file length.  All write operations will update the
688       last file modification timestamp, but only writes that add data to  the
689       end  of  the  file  will change the file length.  The last modification
690       timestamp is not needed to ensure that a read  completes  successfully,
691       but  the  file  length is.  Thus, O_DSYNC would only guarantee to flush
692       updates to the file length metadata (whereas O_SYNC would  also  always
693       flush the last modification timestamp metadata).
694
695       Before Linux 2.6.33, Linux implemented only the O_SYNC flag for open().
696       However, when that flag was specified, most filesystems  actually  pro‐
697       vided  the  equivalent  of  synchronized  I/O data integrity completion
698       (i.e., O_SYNC was actually implemented as the equivalent of O_DSYNC).
699
700       Since Linux 2.6.33, proper O_SYNC support is provided.  However, to en‐
701       sure  backward  binary compatibility, O_DSYNC was defined with the same
702       value as the historical O_SYNC, and O_SYNC was defined as a  new  (two-
703       bit)  flag  value  that  includes the O_DSYNC flag value.  This ensures
704       that applications compiled against new headers get at least O_DSYNC se‐
705       mantics before Linux 2.6.33.
706
707   C library/kernel differences
708       Since  glibc  2.26,  the  glibc wrapper function for open() employs the
709       openat() system call, rather than the kernel's open() system call.  For
710       certain architectures, this is also true before glibc 2.26.
711

STANDARDS

713       open()
714       creat()
715       openat()
716              POSIX.1-2008.
717
718       openat2(2) Linux.
719
720       The  O_DIRECT,  O_NOATIME,  O_PATH,  and O_TMPFILE flags are Linux-spe‐
721       cific.  One must define _GNU_SOURCE to obtain their definitions.
722
723       The O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW flags are not  specified  in
724       POSIX.1-2001, but are specified in POSIX.1-2008.  Since glibc 2.12, one
725       can obtain their definitions by defining either _POSIX_C_SOURCE with  a
726       value  greater  than  or equal to 200809L or _XOPEN_SOURCE with a value
727       greater than or equal to 700.  In glibc 2.11 and earlier,  one  obtains
728       the definitions by defining _GNU_SOURCE.
729

HISTORY

731       open()
732       creat()
733              SVr4, 4.3BSD, POSIX.1-2001.
734
735       openat()
736              POSIX.1-2008.  Linux 2.6.16, glibc 2.4.
737

NOTES

739       Under  Linux,  the O_NONBLOCK flag is sometimes used in cases where one
740       wants to open but does not necessarily have the intention  to  read  or
741       write.   For example, this may be used to open a device in order to get
742       a file descriptor for use with ioctl(2).
743
744       Note that open() can open device special files, but creat() cannot cre‐
745       ate them; use mknod(2) instead.
746
747       If  the  file is newly created, its st_atime, st_ctime, st_mtime fields
748       (respectively, time of last access, time of  last  status  change,  and
749       time  of  last  modification; see stat(2)) are set to the current time,
750       and so are the st_ctime and st_mtime fields of  the  parent  directory.
751       Otherwise,  if  the  file  is modified because of the O_TRUNC flag, its
752       st_ctime and st_mtime fields are set to the current time.
753
754       The files in the /proc/pid/fd directory show the open file  descriptors
755       of the process with the PID pid.  The files in the /proc/pid/fdinfo di‐
756       rectory show even more information about these file  descriptors.   See
757       proc(5) for further details of both of these directories.
758
759       The  Linux  header file <asm/fcntl.h> doesn't define O_ASYNC; the (BSD-
760       derived) FASYNC synonym is defined instead.
761
762   Open file descriptions
763       The term open file description is the one used by POSIX to refer to the
764       entries  in  the  system-wide  table of open files.  In other contexts,
765       this object is variously also called an "open  file  object",  a  "file
766       handle",  an "open file table entry", or—in kernel-developer parlance—a
767       struct file.
768
769       When a file descriptor is duplicated (using dup(2) or similar), the du‐
770       plicate  refers  to the same open file description as the original file
771       descriptor, and the two file descriptors consequently  share  the  file
772       offset and file status flags.  Such sharing can also occur between pro‐
773       cesses: a child process created via fork(2) inherits duplicates of  its
774       parent's  file descriptors, and those duplicates refer to the same open
775       file descriptions.
776
777       Each open() of a file creates a new open file description; thus,  there
778       may be multiple open file descriptions corresponding to a file inode.
779
780       On  Linux,  one can use the kcmp(2) KCMP_FILE operation to test whether
781       two file descriptors (in the same process  or  in  two  different  pro‐
782       cesses) refer to the same open file description.
783
784   NFS
785       There  are  many infelicities in the protocol underlying NFS, affecting
786       amongst others O_SYNC and O_NDELAY.
787
788       On NFS filesystems with UID mapping enabled, open() may return  a  file
789       descriptor  but,  for example, read(2) requests are denied with EACCES.
790       This is because the client performs open() by checking the permissions,
791       but  UID  mapping  is  performed  by the server upon read and write re‐
792       quests.
793
794   FIFOs
795       Opening the read or write end of a FIFO blocks until the other  end  is
796       also  opened  (by  another process or thread).  See fifo(7) for further
797       details.
798
799   File access mode
800       Unlike the other values that can be specified in flags, the access mode
801       values  O_RDONLY,  O_WRONLY, and O_RDWR do not specify individual bits.
802       Rather, they define the low order two bits of flags,  and  are  defined
803       respectively  as 0, 1, and 2.  In other words, the combination O_RDONLY
804       | O_WRONLY is a logical error, and certainly does  not  have  the  same
805       meaning as O_RDWR.
806
807       Linux  reserves  the  special, nonstandard access mode 3 (binary 11) in
808       flags to mean: check for read and write permission on the file and  re‐
809       turn a file descriptor that can't be used for reading or writing.  This
810       nonstandard access mode is used by some Linux drivers to return a  file
811       descriptor  that is to be used only for device-specific ioctl(2) opera‐
812       tions.
813
814   Rationale for openat() and other directory file descriptor APIs
815       openat() and the other system calls and library functions that  take  a
816       directory  file  descriptor  argument (i.e., execveat(2), faccessat(2),
817       fanotify_mark(2), fchmodat(2), fchownat(2), fspick(2), fstatat(2),  fu‐
818       timesat(2),   linkat(2),   mkdirat(2),   mknodat(2),  mount_setattr(2),
819       move_mount(2), name_to_handle_at(2),  open_tree(2),  openat2(2),  read‐
820       linkat(2),   renameat(2),  renameat2(2),  statx(2),  symlinkat(2),  un‐
821       linkat(2), utimensat(2), mkfifoat(3),  and  scandirat(3))  address  two
822       problems  with  the older interfaces that preceded them.  Here, the ex‐
823       planation is in terms of the openat() call, but the rationale is analo‐
824       gous for the other interfaces.
825
826       First,  openat()  allows  an  application to avoid race conditions that
827       could occur when using open() to open files in directories  other  than
828       the  current  working directory.  These race conditions result from the
829       fact that some component of the directory prefix given to open()  could
830       be  changed in parallel with the call to open().  Suppose, for example,
831       that  we  wish  to  create  the  file  dir1/dir2/xxx.dep  if  the  file
832       dir1/dir2/xxx  exists.  The problem is that between the existence check
833       and the file-creation step, dir1  or  dir2  (which  might  be  symbolic
834       links)  could be modified to point to a different location.  Such races
835       can be avoided by opening a file descriptor for the  target  directory,
836       and then specifying that file descriptor as the dirfd argument of (say)
837       fstatat(2) and openat().  The use of the dirfd file descriptor also has
838       other benefits:
839
840       •  the  file descriptor is a stable reference to the directory, even if
841          the directory is renamed; and
842
843       •  the open file descriptor prevents the underlying filesystem from be‐
844          ing  dismounted, just as when a process has a current working direc‐
845          tory on a filesystem.
846
847       Second, openat() allows the implementation  of  a  per-thread  "current
848       working  directory",  via file descriptor(s) maintained by the applica‐
849       tion.  (This functionality can also be obtained by tricks based on  the
850       use of /proc/self/fd/dirfd, but less efficiently.)
851
852       The  dirfd  argument  for these APIs can be obtained by using open() or
853       openat() to open a directory (with either the O_RDONLY  or  the  O_PATH
854       flag).  Alternatively, such a file descriptor can be obtained by apply‐
855       ing dirfd(3) to a directory stream created using opendir(3).
856
857       When these APIs are given a dirfd argument of AT_FDCWD or the specified
858       pathname  is  absolute, then they handle their pathname argument in the
859       same way as the corresponding  conventional  APIs.   However,  in  this
860       case, several of the APIs have a flags argument that provides access to
861       functionality that is not available with the corresponding conventional
862       APIs.
863
864   O_DIRECT
865       The  O_DIRECT  flag may impose alignment restrictions on the length and
866       address of user-space buffers and the file offset of  I/Os.   In  Linux
867       alignment  restrictions vary by filesystem and kernel version and might
868       be absent entirely.  The handling  of  misaligned  O_DIRECT  I/Os  also
869       varies; they can either fail with EINVAL or fall back to buffered I/O.
870
871       Since Linux 6.1, O_DIRECT support and alignment restrictions for a file
872       can be queried using statx(2), using the STATX_DIOALIGN flag.   Support
873       for STATX_DIOALIGN varies by filesystem; see statx(2).
874
875       Some  filesystems  provide  their  own interfaces for querying O_DIRECT
876       alignment restrictions, for example the  XFS_IOC_DIOINFO  operation  in
877       xfsctl(3).  STATX_DIOALIGN should be used instead when it is available.
878
879       If  none  of the above is available, then direct I/O support and align‐
880       ment restrictions can only be assumed from known characteristics of the
881       filesystem,  the individual file, the underlying storage device(s), and
882       the kernel version.  In Linux 2.4, most filesystems based on block  de‐
883       vices require that the file offset and the length and memory address of
884       all I/O segments be multiples of the filesystem block  size  (typically
885       4096  bytes).   In  Linux  2.6.0, this was relaxed to the logical block
886       size of the block device (typically 512 bytes).  A block device's logi‐
887       cal block size can be determined using the ioctl(2) BLKSSZGET operation
888       or from the shell using the command:
889
890           blockdev --getss
891
892       O_DIRECT I/Os should never be run concurrently with the fork(2)  system
893       call, if the memory buffer is a private mapping (i.e., any mapping cre‐
894       ated with the mmap(2) MAP_PRIVATE flag; this includes memory  allocated
895       on  the heap and statically allocated buffers).  Any such I/Os, whether
896       submitted via an asynchronous I/O interface or from another  thread  in
897       the  process, should be completed before fork(2) is called.  Failure to
898       do so can result in data corruption and undefined  behavior  in  parent
899       and  child  processes.  This restriction does not apply when the memory
900       buffer for the O_DIRECT I/Os was created using shmat(2) or mmap(2) with
901       the  MAP_SHARED  flag.  Nor does this restriction apply when the memory
902       buffer has been advised as MADV_DONTFORK with madvise(2), ensuring that
903       it will not be available to the child after fork(2).
904
905       The  O_DIRECT  flag  was introduced in SGI IRIX, where it has alignment
906       restrictions similar to those of Linux 2.4.  IRIX has also  a  fcntl(2)
907       call  to  query  appropriate alignments, and sizes.  FreeBSD 4.x intro‐
908       duced a flag of the same name, but without alignment restrictions.
909
910       O_DIRECT support was added in Linux 2.4.10.  Older Linux kernels simply
911       ignore  this  flag.   Some  filesystems  may not implement the flag, in
912       which case open() fails with the error EINVAL if it is used.
913
914       Applications should avoid mixing O_DIRECT and normal I/O  to  the  same
915       file,  and  especially  to  overlapping  byte regions in the same file.
916       Even when the filesystem correctly handles the coherency issues in this
917       situation, overall I/O throughput is likely to be slower than using ei‐
918       ther mode alone.  Likewise, applications should avoid mixing mmap(2) of
919       files with direct I/O to the same files.
920
921       The  behavior  of O_DIRECT with NFS will differ from local filesystems.
922       Older kernels, or kernels configured in certain ways, may  not  support
923       this  combination.   The NFS protocol does not support passing the flag
924       to the server, so O_DIRECT I/O will bypass the page cache only  on  the
925       client; the server may still cache the I/O.  The client asks the server
926       to make the I/O synchronous to preserve the  synchronous  semantics  of
927       O_DIRECT.   Some servers will perform poorly under these circumstances,
928       especially if the I/O size is small.  Some servers may also be  config‐
929       ured  to  lie  to  clients about the I/O having reached stable storage;
930       this will avoid the performance penalty at some risk to data  integrity
931       in  the  event of server power failure.  The Linux NFS client places no
932       alignment restrictions on O_DIRECT I/O.
933
934       In summary, O_DIRECT is a potentially powerful tool that should be used
935       with  caution.   It is recommended that applications treat use of O_DI‐
936       RECT as a performance option which is disabled by default.
937

BUGS

939       Currently, it is not possible to enable signal-driven I/O by specifying
940       O_ASYNC when calling open(); use fcntl(2) to enable this flag.
941
942       One  must  check for two different error codes, EISDIR and ENOENT, when
943       trying to determine whether the kernel supports  O_TMPFILE  functional‐
944       ity.
945
946       When  both  O_CREAT and O_DIRECTORY are specified in flags and the file
947       specified by pathname does not exist, open() will create a regular file
948       (i.e., O_DIRECTORY is ignored).
949

SEE ALSO

951       chmod(2),  chown(2),  close(2),  dup(2),  fcntl(2),  link(2), lseek(2),
952       mknod(2), mmap(2), mount(2), open_by_handle_at(2), openat2(2), read(2),
953       socket(2),  stat(2),  umask(2),  unlink(2), write(2), fopen(3), acl(5),
954       fifo(7), inode(7), path_resolution(7), symlink(7)
955
956
957
958Linux man-pages 6.05              2023-05-20                           open(2)
Impressum