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

NAME

6       open, creat - open and possibly create a file or device
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       int creat(const char *pathname, mode_t mode);
16

DESCRIPTION

18       Given a pathname for a file, open() returns a file descriptor, a small,
19       non-negative integer for  use  in  subsequent  system  calls  (read(2),
20       write(2), lseek(2), fcntl(2), etc.).  The file descriptor returned by a
21       successful call will be the lowest-numbered file  descriptor  not  cur‐
22       rently open for the process.
23
24       The  new  file  descriptor  is  set  to remain open across an execve(2)
25       (i.e., the FD_CLOEXEC file descriptor flag  described  in  fcntl(2)  is
26       initially  disabled).   The  file offset is set to the beginning of the
27       file (see lseek(2)).
28
29       A call to open() creates a new open file description, an entry  in  the
30       system-wide  table  of  open files.  This entry records the file offset
31       and the file status flags (modifiable via the  fcntl()  F_SETFL  opera‐
32       tion).   A file descriptor is a reference to one of these entries; this
33       reference is unaffected if pathname is subsequently removed or modified
34       to  refer  to  a different file.  The new open file description is ini‐
35       tially not shared with any other process, but  sharing  may  arise  via
36       fork(2).
37
38       The  parameter  flags  must  include one of the following access modes:
39       O_RDONLY, O_WRONLY, or O_RDWR.  These request opening  the  file  read-
40       only, write-only, or read/write, respectively.
41
42       In addition, zero or more file creation flags and file status flags can
43       be bitwise-or'd in flags.  The file creation flags are O_CREAT, O_EXCL,
44       O_NOCTTY,  and O_TRUNC.  The file status flags are all of the remaining
45       flags listed below.  The distinction between these two groups of  flags
46       is that the file status flags can be retrieved and (in some cases) mod‐
47       ified using fcntl(2).  The full list of file creation  flags  and  file
48       status flags is as follows:
49
50       O_APPEND
51              The file is opened in append mode. Before each write(), the file
52              offset is positioned at the end of the file, as if with lseek().
53              O_APPEND may lead to corrupted files on NFS file systems if more
54              than one process appends data  to  a  file  at  once.   This  is
55              because  NFS does not support appending to a file, so the client
56              kernel has to simulate it, which can't be done  without  a  race
57              condition.
58
59       O_ASYNC
60              Enable  signal-driven  I/O: generate a signal (SIGIO by default,
61              but this can be changed  via  fcntl(2))  when  input  or  output
62              becomes  possible on this file descriptor.  This feature is only
63              available for terminals, pseudo-terminals, sockets,  and  (since
64              Linux 2.6) pipes and FIFOs.  See fcntl(2) for further details.
65
66       O_CREAT
67              If  the file does not exist it will be created.  The owner (user
68              ID) of the file is set to the effective user ID of the  process.
69              The  group  ownership  (group ID) is set either to the effective
70              group ID of the process or to the group ID of the parent  direc‐
71              tory  (depending  on  filesystem type and mount options, and the
72              mode of the parent directory, see, e.g., the mount options  bsd‐
73              groups  and  sysvgroups  of the ext2 filesystem, as described in
74              mount(8)).
75
76       O_DIRECT
77              Try to minimize cache effects of the I/O to and from this  file.
78              In  general  this  will degrade performance, but it is useful in
79              special situations, such  as  when  applications  do  their  own
80              caching.   File I/O is done directly to/from user space buffers.
81              The I/O is synchronous, i.e., at the completion of a read(2)  or
82              write(2),  data  is  guaranteed to have been transferred.  Under
83              Linux 2.4 transfer sizes, and the alignment of user  buffer  and
84              file  offset  must all be multiples of the logical block size of
85              the file system. Under Linux 2.6 alignment  to  512-byte  bound‐
86              aries suffices.
87
88              A  semantically  similar  (but  deprecated)  interface for block
89              devices is described in raw(8).
90
91       O_DIRECTORY
92              If pathname is not a directory, cause the open  to  fail.   This
93              flag is Linux-specific, and was added in kernel version 2.1.126,
94              to avoid denial-of-service problems if opendir(3) is called on a
95              FIFO  or  tape  device,  but  should  not be used outside of the
96              implementation of opendir.
97
98       O_EXCL When used with O_CREAT, if the file  already  exists  it  is  an
99              error and the open() will fail. In this context, a symbolic link
100              exists, regardless of where it points to.  O_EXCL is  broken  on
101              NFS file systems; programs which rely on it for performing lock‐
102              ing tasks will contain a race condition.  The solution for  per‐
103              forming  atomic  file  locking  using  a lockfile is to create a
104              unique file on the same file system (e.g.,  incorporating  host‐
105              name  and  pid),  use link(2) to make a link to the lockfile. If
106              link() returns  0,  the  lock  is  successful.   Otherwise,  use
107              stat(2)  on  the  unique  file  to  check  if its link count has
108              increased to 2, in which case the lock is also successful.
109
110       O_LARGEFILE
111              (LFS) Allow files whose sizes cannot be represented in an  off_t
112              (but  can  be  represented  in  an  off64_t)  to be opened.  The
113              _LARGEFILE64_SOURCE macro must be defined  in  order  to  obtain
114              this  definition.   Setting  the  _FILE_OFFSET_BITS feature test
115              macro to 64 (rather than using  O_LARGEFILE)  is  the  preferred
116              method  of  obtaining  method of accessing large files on 32-bit
117              systems (see feature_test_macros(7)).
118
119       O_NOATIME
120              (Since Linux 2.6.8) Do not update  the  file  last  access  time
121              (st_atime  in the inode) when the file is read(2).  This flag is
122              intended for use by indexing or backup programs, where  its  use
123              can significantly reduce the amount of disk activity.  This flag
124              may not be effective on all filesystems.  One  example  is  NFS,
125              where the server maintains the access time.
126
127       O_NOCTTY
128              If  pathname  refers to a terminal device — see tty(4) — it will
129              not become  the  process's  controlling  terminal  even  if  the
130              process does not have one.
131
132       O_NOFOLLOW
133              If  pathname is a symbolic link, then the open fails.  This is a
134              FreeBSD extension, which was added to Linux in version  2.1.126.
135              Symbolic  links in earlier components of the pathname will still
136              be followed.
137
138       O_NONBLOCK or O_NDELAY
139              When possible, the file is opened in non-blocking mode.  Neither
140              the  open() nor any subsequent operations on the file descriptor
141              which is returned will cause the calling process to  wait.   For
142              the  handling  of  FIFOs (named pipes), see also fifo(7).  For a
143              discussion of the  effect  of  O_NONBLOCK  in  conjunction  with
144              mandatory file locks and with file leases, see fcntl(2).
145
146
147       O_SYNC The  file  is  opened  for  synchronous I/O. Any write()s on the
148              resulting file descriptor will block the calling  process  until
149              the data has been physically written to the underlying hardware.
150              But see RESTRICTIONS below.
151
152       O_TRUNC
153              If the file already exists and is a regular file  and  the  open
154              mode  allows  writing  (i.e.,  is O_RDWR or O_WRONLY) it will be
155              truncated to length 0.  If the file is a FIFO or terminal device
156              file,  the  O_TRUNC  flag  is  ignored.  Otherwise the effect of
157              O_TRUNC is unspecified.
158
159       Some of these optional flags can be altered  using  fcntl()  after  the
160       file has been opened.
161
162       The  argument  mode specifies the permissions to use in case a new file
163       is created. It is modified by the process's umask in the usual way: the
164       permissions  of  the  created file are (mode & ~umask).  Note that this
165       mode only applies to future accesses of the  newly  created  file;  the
166       open()  call that creates a read-only file may well return a read/write
167       file descriptor.
168
169       The following symbolic constants are provided for mode:
170
171       S_IRWXU
172              00700 user (file owner) has read, write and execute permission
173
174       S_IRUSR
175              00400 user has read permission
176
177       S_IWUSR
178              00200 user has write permission
179
180       S_IXUSR
181              00100 user has execute permission
182
183       S_IRWXG
184              00070 group has read, write and execute permission
185
186       S_IRGRP
187              00040 group has read permission
188
189       S_IWGRP
190              00020 group has write permission
191
192       S_IXGRP
193              00010 group has execute permission
194
195       S_IRWXO
196              00007 others have read, write and execute permission
197
198       S_IROTH
199              00004 others have read permission
200
201       S_IWOTH
202              00002 others have write permission
203
204       S_IXOTH
205              00001 others have execute permission
206
207       mode must be specified when O_CREAT is in the  flags,  and  is  ignored
208       otherwise.
209
210       creat()    is    equivalent    to    open()   with   flags   equal   to
211       O_CREAT|O_WRONLY|O_TRUNC.
212

RETURN VALUE

214       open() and creat() return the new file descriptor, or -1  if  an  error
215       occurred (in which case, errno is set appropriately).
216

NOTES

218       Note that open() can open device special files, but creat() cannot cre‐
219       ate them; use mknod(2) instead.
220
221       On NFS file systems with UID mapping enabled, open() may return a  file
222       descriptor  but  e.g. read(2) requests are denied with EACCES.  This is
223       because the client performs open() by checking the permissions, but UID
224       mapping is performed by the server upon read and write requests.
225
226       If  the  file is newly created, its st_atime, st_ctime, st_mtime fields
227       (respectively, time of last access, time of  last  status  change,  and
228       time  of  last  modification; see stat(2)) are set to the current time,
229       and so are the st_ctime and st_mtime fields of  the  parent  directory.
230       Otherwise,  if  the  file  is modified because of the O_TRUNC flag, its
231       st_ctime and st_mtime fields are set to the current time.
232

ERRORS

234       EACCES The requested access to the file is not allowed, or search  per‐
235              mission  is denied for one of the directories in the path prefix
236              of pathname, or the file did not exist yet and write  access  to
237              the  parent  directory  is  not allowed.  (See also path_resolu‐
238              tion(2).)
239
240       EEXIST pathname already exists and O_CREAT and O_EXCL were used.
241
242       EFAULT pathname points outside your accessible address space.
243
244       EFBIG  pathname refers to a regular file, too large to be  opened;  see
245              O_LARGEFILE  above.  (POSIX.1-2001 specifies the error EOVERFLOW
246              for this case.)
247
248       EISDIR pathname refers to a directory and the access requested involved
249              writing (that is, O_WRONLY or O_RDWR is set).
250
251       ELOOP  Too  many symbolic links were encountered in resolving pathname,
252              or O_NOFOLLOW was specified but pathname was a symbolic link.
253
254       EMFILE The process already has the maximum number of files open.
255
256       ENAMETOOLONG
257              pathname was too long.
258
259       ENFILE The system limit on the total number  of  open  files  has  been
260              reached.
261
262       ENODEV pathname  refers  to  a device special file and no corresponding
263              device exists.  (This is a Linux kernel bug; in  this  situation
264              ENXIO must be returned.)
265
266       ENOENT O_CREAT  is  not  set  and the named file does not exist.  Or, a
267              directory component in pathname does not exist or is a  dangling
268              symbolic link.
269
270       ENOMEM Insufficient kernel memory was available.
271
272       ENOSPC pathname  was  to  be created but the device containing pathname
273              has no room for the new file.
274
275       ENOTDIR
276              A component used as a directory in pathname is not, in  fact,  a
277              directory,  or  O_DIRECTORY was specified and pathname was not a
278              directory.
279
280       ENXIO  O_NONBLOCK | O_WRONLY is set, the named file is a  FIFO  and  no
281              process has the file open for reading.  Or, the file is a device
282              special file and no corresponding device exists.
283
284       EPERM  The O_NOATIME flag was specified, but the effective user  ID  of
285              the  caller  did  not match the owner of the file and the caller
286              was not privileged (CAP_FOWNER).
287
288       EROFS  pathname refers to a file on a read-only  filesystem  and  write
289              access was requested.
290
291       ETXTBSY
292              pathname  refers to an executable image which is currently being
293              executed and write access was requested.
294
295       EWOULDBLOCK
296              The O_NONBLOCK flag was specified, and an incompatible lease was
297              held on the file (see fcntl(2)).
298

NOTE

300       Under  Linux,  the O_NONBLOCK flag indicates that one wants to open but
301       does not necessarily have the intention to read or write.  This is typ‐
302       ically  used  to open devices in order to get a file descriptor for use
303       with ioctl(2).
304

CONFORMING TO

306       SVr4, 4.3BSD, POSIX.1-2001.  The O_NOATIME, O_NOFOLLOW, and O_DIRECTORY
307       flags are Linux specific.  One may have to define the _GNU_SOURCE macro
308       to get their definitions.
309
310       The (undefined) effect of O_RDONLY | O_TRUNC varies  among  implementa‐
311       tions.  On many systems the file is actually truncated.
312
313       The  O_DIRECT  flag  was introduced in SGI IRIX, where it has alignment
314       restrictions similar to those of Linux 2.4.  IRIX has also  a  fcntl(2)
315       call  to  query appropriate alignments, and sizes.   FreeBSD 4.x intro‐
316       duced a flag of same name, but without alignment restrictions.  Support
317       was  added  under  Linux in kernel version 2.4.10.  Older Linux kernels
318       simply ignore this flag.  One may have to define the _GNU_SOURCE  macro
319       to get its definition.
320

BUGS

322       "The  thing  that  has  always  disturbed me about O_DIRECT is that the
323       whole interface is just stupid, and was probably designed by a deranged
324       monkey on some serious mind-controlling substances." — Linus
325
326       Currently, it is not possible to enable signal-driven I/O by specifying
327       O_ASYNC when calling open(); use fcntl(2) to enable this flag.
328

RESTRICTIONS

330       There are many infelicities in the protocol underlying  NFS,  affecting
331       amongst others O_SYNC and O_NDELAY.
332
333       POSIX provides for three different variants of synchronised I/O, corre‐
334       sponding to the flags O_SYNC, O_DSYNC and O_RSYNC.  Currently (2.1.130)
335       these are all synonymous under Linux.
336

SEE ALSO

338       close(2),  dup(2),  fcntl(2),  link(2),  lseek(2),  mknod(2), mount(2),
339       mmap(2), openat(2), path_resolution(2),  read(2),  socket(2),  stat(2),
340       umask(2),     unlink(2),     write(2),    fopen(3),    fifo(7),    fea‐
341       ture_test_macros(7)
342
343
344
345Linux 2.6.12                      2005-06-22                           OPEN(2)
Impressum