1open(2) System Calls open(2)
2
6 open, openat - open a file
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <fcntl.h>
12 int open(const char *path, int oflag, /* mode_t mode */);
14 int openat(int fildes, const char *path, int oflag,
17 /* mode_t mode */);
18
21 The open() function establishes the connection between a file and a
22 file descriptor. It creates an open file description that refers to a
23 file and a file descriptor that refers to that open file description.
24 The file descriptor is used by other I/O functions to refer to that
25 file. The path argument points to a pathname naming the file.
26 The openat() function is identical to the open() function except that
29 the path argument is interpreted relative to the starting point implied
30 by the fildes argument. If the fildes argument has the special value
31 AT_FDCWD, a relative path argument will be resolved relative to the
32 current working directory. If the path argument is absolute, the fildes
33 argument is ignored.
34 The open() function returns a file descriptor for the named file that
37 is the lowest file descriptor not currently open for that process. The
38 open file description is new, and therefore the file descriptor does
39 not share it with any other process in the system. The FD_CLOEXEC file
40 descriptor flag associated with the new file descriptor is cleared.
41 The file offset used to mark the current position within the file is
44 set to the beginning of the file.
45 The file status flags and file access modes of the open file descrip‐
48 tion are set according to the value of oflag. The mode argument is used
49 only when O_CREAT is specified (see below.)
50 Values for oflag are constructed by a bitwise-inclusive-OR of flags
53 from the following list, defined in <fcntl.h>. Applications must spec‐
54 ify exactly one of the first three values (file access modes) below in
55 the value of oflag:
56 O_RDONLY Open for reading only.
58 O_WRONLY Open for writing only.
61 O_RDWR Open for reading and writing. The result is undefined if
64 this flag is applied to a FIFO.
65 Any combination of the following may be used:
69 O_APPEND
71 If set, the file offset is set to the end of the file prior to each
73 write.
74 O_CREAT
77 Create the file if it does not exist. This flag requires that the
79 mode argument be specified.
80 If the file exists, this flag has no effect except as noted under
82 O_EXCL below. Otherwise, the file is created with the user ID of
83 the file set to the effective user ID of the process. The group ID
84 of the file is set to the effective group IDs of the process, or if
85 the S_ISGID bit is set in the directory in which the file is being
86 created, the file's group ID is set to the group ID of its parent
87 directory. If the group ID of the new file does not match the
88 effective group ID or one of the supplementary groups IDs, the
89 S_ISGID bit is cleared. The access permission bits (see
90 <sys/stat.h>) of the file mode are set to the value of mode, modi‐
91 fied as follows (see creat(2)): a bitwise-AND is performed on the
92 file-mode bits and the corresponding bits in the complement of the
93 process's file mode creation mask. Thus, all bits set in the
94 process's file mode creation mask (see umask(2)) are correspond‐
95 ingly cleared in the file's permission mask. The "save text image
96 after execution bit" of the mode is cleared (see chmod(2)). O_SYNC
97 Write I/O operations on the file descriptor complete as defined by
98 synchronized I/O file integrity completion (see fcntl.h(3HEAD)
99 definition of O_SYNC.) When bits other than the file permission
100 bits are set, the effect is unspecified. The mode argument does not
101 affect whether the file is open for reading, writing or for both.
102 O_DSYNC
105 Write I/O operations on the file descriptor complete as defined by
107 synchronized I/O data integrity completion.
108 O_EXCL
111 If O_CREAT and O_EXCL are set, open() fails if the file exists. The
113 check for the existence of the file and the creation of the file if
114 it does not exist is atomic with respect to other threads executing
115 open() naming the same filename in the same directory with O_EXCL
116 and O_CREAT set. If O_EXCL and O_CREAT are set, and path names a
117 symbolic link, open() fails and sets errno to EEXIST, regardless of
118 the contents of the symbolic link. If O_EXCL is set and O_CREAT is
119 not set, the result is undefined.
120 O_LARGEFILE
123 If set, the offset maximum in the open file description is the
125 largest value that can be represented correctly in an object of
126 type off64_t.
127 O_NOCTTY
130 If set and path identifies a terminal device, open() does not cause
132 the terminal device to become the controlling terminal for the
133 process.
134 O_NOFOLLOW
137 If the path names a symbolic link, open() fails and sets errno to
139 ELOOP.
140 O_NOLINKS
143 If the link count of the named file is greater than 1, open() fails
145 and sets errno to EMLINK.
146 O_NONBLOCK or O_NDELAY
149 These flags can affect subsequent reads and writes (see read(2) and
151 write(2)). If both O_NDELAY and O_NONBLOCK are set, O_NONBLOCK
152 takes precedence.
153 When opening a FIFO with O_RDONLY or O_WRONLY set:
155 o If O_NONBLOCK or O_NDELAY is set, an open() for reading
157 only returns without delay. An open() for writing only
158 returns an error if no process currently has the file
159 open for reading.
160 o If O_NONBLOCK and O_NDELAY are clear, an open() for
162 reading only blocks until a thread opens the file for
163 writing. An open() for writing only blocks the calling
164 thread until a thread opens the file for reading.
165 After both ends of a FIFO have been opened, there is no guarantee
166 that further calls to open() O_RDONLY (O_WRONLY) will synchronize
167 with later calls to open() O_WRONLY (O_RDONLY) until both ends of
168 the FIFO have been closed by all readers and writers. Any data
169 written into a FIFO will be lost if both ends of the FIFO are
170 closed before the data is read.
171 When opening a block special or character special file that sup‐
173 ports non-blocking opens:
174 o If O_NONBLOCK or O_NDELAY is set, the open() function
176 returns without blocking for the device to be ready or
177 available. Subsequent behavior of the device is device-
178 specific.
179 o If O_NONBLOCK and O_NDELAY are clear, the open() func‐
181 tion blocks the calling thread until the device is ready
182 or available before returning.
183 Otherwise, the behavior of O_NONBLOCK and O_NDELAY is unspecified.
184 O_RSYNC
187 Read I/O operations on the file descriptor complete at the same
189 level of integrity as specified by the O_DSYNC and O_SYNC flags. If
190 both O_DSYNC and O_RSYNC are set in oflag, all I/O operations on
191 the file descriptor complete as defined by synchronized I/O data
192 integrity completion. If both O_SYNC and O_RSYNC are set in oflag,
193 all I/O operations on the file descriptor complete as defined by
194 synchronized I/O file integrity completion.
195 O_SYNC
198 Write I/O operations on the file descriptor complete as defined by
200 synchronized I/O file integrity completion.
201 O_TRUNC
204 If the file exists and is a regular file, and the file is success‐
206 fully opened O_RDWR or O_WRONLY, its length is truncated to 0 and
207 the mode and owner are unchanged. It has no effect on FIFO special
208 files or terminal device files. Its effect on other file types is
209 implementation-dependent. The result of using O_TRUNC with O_RDONLY
210 is undefined.
211 O_XATTR
214 If set in openat(), a relative path argument is interpreted as a
216 reference to an extended attribute of the file associated with the
217 supplied file descriptor. This flag therefore requires the pres‐
218 ence of a legal fildes argument. If set in open(), the implied file
219 descriptor is that for the current working directory. Extended
220 attributes must be referenced with a relative path; providing an
221 absolute path results in a normal file reference.
222 If O_CREAT is set and the file did not previously exist, upon success‐
226 ful completion, open() marks for update the st_atime, st_ctime, and
227 st_mtime fields of the file and the st_ctime and st_mtime fields of the
228 parent directory.
229 If O_TRUNC is set and the file did previously exist, upon successful
232 completion, open() marks for update the st_ctime and st_mtime fields of
233 the file.
234 If both the O_SYNC and O_DSYNC flags are set, the effect is as if only
237 the O_SYNC flag was set.
238 If path refers to a STREAMS file, oflag may be constructed from O_NON‐
241 BLOCK or O_NODELAY OR-ed with either O_RDONLY, O_WRONLY, or O_RDWR.
242 Other flag values are not applicable to STREAMS devices and have no
243 effect on them. The values O_NONBLOCK and O_NODELAY affect the opera‐
244 tion of STREAMS drivers and certain functions (see read(2), getmsg(2),
245 putmsg(2), and write(2)) applied to file descriptors associated with
246 STREAMS files. For STREAMS drivers, the implementation of O_NONBLOCK
247 and O_NODELAY is device-specific.
248 When open() is invoked to open a named stream, and the connld module
251 (see connld(7M)) has been pushed on the pipe, open() blocks until the
252 server process has issued an I_RECVFD ioctl() (see streamio(7I)) to
253 receive the file descriptor.
254 If path names the master side of a pseudo-terminal device, then it is
257 unspecified whether open() locks the slave side so that it cannot be
258 opened. Portable applications must call unlockpt(3C) before opening
259 the slave side.
260 If the file is a regular file and the local file system is mounted with
263 the nbmand mount option, then a mandatory share reservation is automat‐
264 ically obtained on the file. The share reservation is obtained as if
265 fcntl(2) were called with cmd F_SHARE_NBMAND and the fshare_t values
266 set as follows:
267 f_access Set to the type of read/write access for which the file is
269 opened.
270 f_deny F_NODNY
273 f_id The file descriptor value returned from open().
276 If path is a symbolic link and O_CREAT and O_EXCL are set, the link is
280 not followed.
281 Certain flag values can be set following open() as described in
284 fcntl(2).
285 The largest value that can be represented correctly in an object of
288 type off_t is established as the offset maximum in the open file
289 description.
290
292 Upon successful completion, the open() function opens the file and
293 return a non-negative integer representing the lowest numbered unused
294 file descriptor. Otherwise, −1 is returned, errno is set to indicate
295 the error, and no files are created or modified.
296
298 The open() and openat() functions will fail if:
299 EACCES Search permission is denied on a component of the path
301 prefix.
302 The file exists and the permissions specified by oflag
304 are denied.
305 The file does not exist and write permission is denied
307 for the parent directory of the file to be created.
308 O_TRUNC is specified and write permission is denied.
310 The {PRIV_FILE_DAC_SEARCH} privilege allows processes
312 to search directories regardless of permission bits.
313 The {PRIV_FILE_DAC_WRITE} privilege allows processes to
314 open files for writing regardless of permission bits.
315 See privileges(5) for special considerations when open‐
316 ing files owned by UID 0 for writing. The
317 {PRIV_FILE_DAC_READ} privilege allows processes to open
318 files for reading regardless of permission bits.
319 EAGAIN A mandatory share reservation could not be obtained
322 because the desired access conflicts with an existing
323 f_deny share reservation.
324 EBADF The file descriptor provided to openat() is invalid.
327 EDQUOT The file does not exist, O_CREAT is specified, and
330 either the directory where the new file entry is being
331 placed cannot be extended because the user's quota of
332 disk blocks on that file system has been exhausted, or
333 the user's quota of inodes on the file system where the
334 file is being created has been exhausted.
335 EEXIST The O_CREAT and O_EXCL flags are set and the named file
338 exists.
339 EILSEQ The path argument includes non-UTF8 characters and the
342 file system accepts only file names where all charac‐
343 ters are part of the UTF-8 character codeset.
344 EINTR A signal was caught during open().
347 EFAULT The path argument points to an illegal address.
350 EINVAL The system does not support synchronized I/O for this
353 file, or the O_XATTR flag was supplied and the underly‐
354 ing file system does not support extended file
355 attributes.
356 EIO The path argument names a STREAMS file and a hangup or
359 error occurred during the open().
360 EISDIR The named file is a directory and oflag includes
363 O_WRONLY or O_RDWR.
364 ELOOP Too many symbolic links were encountered in resolving
367 path.
368 A loop exists in symbolic links encountered during res‐
370 olution of the path argument.
371 The O_NOFOLLOW flag is set and the final component of
373 path is a symbolic link.
374 EMFILE There are currently {OPEN_MAX} file descriptors open in
377 the calling process.
378 EMLINK The O_NOLINKS flag is set and the named file has a link
381 count greater than 1.
382 EMULTIHOP Components of path require hopping to multiple remote
385 machines and the file system does not allow it.
386 ENAMETOOLONG The length of the path argument exceeds {PATH_MAX} or a
389 pathname component is longer than {NAME_MAX}.
390 ENFILE The maximum allowable number of files is currently open
393 in the system.
394 ENOENT The O_CREAT flag is not set and the named file does not
397 exist; or the O_CREAT flag is set and either the path
398 prefix does not exist or the path argument points to an
399 empty string.
400 ENOLINK The path argument points to a remote machine, and the
403 link to that machine is no longer active.
404 ENOSR The path argument names a STREAMS-based file and the
407 system is unable to allocate a STREAM.
408 ENOSPC The directory or file system that would contain the new
411 file cannot be expanded, the file does not exist, and
412 O_CREAT is specified.
413 ENOSYS The device specified by path does not support the open
416 operation.
417 ENOTDIR A component of the path prefix is not a directory or a
420 relative path was supplied to openat(), the O_XATTR
421 flag was not supplied, and the file descriptor does not
422 refer to a directory.
423 ENXIO The O_NONBLOCK flag is set, the named file is a FIFO,
426 the O_WRONLY flag is set, and no process has the file
427 open for reading; or the named file is a character spe‐
428 cial or block special file and the device associated
429 with this special file does not exist or has been
430 retired by the fault management framework .
431 EOPNOTSUPP An attempt was made to open a path that corresponds to
434 a AF_UNIX socket.
435 EOVERFLOW The named file is a regular file and either O_LARGEFILE
438 is not set and the size of the file cannot be repre‐
439 sented correctly in an object of type off_t or O_LARGE‐
440 FILE is set and the size of the file cannot be repre‐
441 sented correctly in an object of type off64_t.
442 EROFS The named file resides on a read-only file system and
445 either O_WRONLY, O_RDWR, O_CREAT (if file does not
446 exist), or O_TRUNC is set in the oflag argument.
447 The openat() function will fail if:
451 EBADF The fildes argument is not a valid open file descriptor or is
453 not AT_FTCWD.
454 The open() function may fail if:
458 EAGAIN The path argument names the slave side of a pseudo-ter‐
460 minal device that is locked.
461 EINVAL The value of the oflag argument is not valid.
464 ENAMETOOLONG Pathname resolution of a symbolic link produced an
467 intermediate result whose length exceeds {PATH_MAX}.
468 ENOMEM The path argument names a STREAMS file and the system
471 is unable to allocate resources.
472 ETXTBSY The file is a pure procedure (shared text) file that is
475 being executed and oflag is O_WRONLY or O_RDWR.
476
479 Example 1 Open a file for writing by the owner.
480 The following example opens the file /tmp/file, either by creating it
483 if it does not already exist, or by truncating its length to 0 if it
484 does exist. If the call creates a new file, the access permission bits
485 in the file mode of the file are set to permit reading and writing by
486 the owner, and to permit reading only by group members and others.
487 If the call to open() is successful, the file is opened for writing.
491 #include <fcntl.h>
494 ...
495 int fd;
496 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
497 char *filename = "/tmp/file";
498 ...
499 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
500 ...
501 Example 2 Open a file using an existence check.
504 The following example uses the open() function to try to create the
507 LOCKFILE file and open it for writing. Since the open() function speci‐
508 fies the O_EXCL flag, the call fails if the file already exists. In
509 that case, the application assumes that someone else is updating the
510 password file and exits.
511 #include <fcntl.h>
514 #include <stdio.h>
515 #include <stdlib.h>
516 #define LOCKFILE "/etc/ptmp"
517 ...
518 int pfd; /* Integer for file descriptor returned by open() call. */
519 ...
520 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
521 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
522 {
523 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
524 exit(1);
525 }
526 ...
527 Example 3 Open a file for writing.
530 The following example opens a file for writing, creating the file if it
533 does not already exist. If the file does exist, the system truncates
534 the file to zero bytes.
535 #include <fcntl.h>
538 #include <stdio.h>
539 #include <stdlib.h>
540 #define LOCKFILE "/etc/ptmp"
541 ...
542 int pfd;
543 char filename[PATH_MAX+1];
544 ...
545 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
546 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
547 {
548 perror("Cannot open output file\n"); exit(1);
549 }
550 ...
551
554 The open() function has a transitional interface for 64-bit file off‐
555 sets. See lf64(5). Note that using open64() is equivalent to using
556 open() with O_LARGEFILE set in oflag.
557
559 See attributes(5) for descriptions of the following attributes:
560 ┌─────────────────────────────┬──────────────────────────────┐
565 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
566 ├─────────────────────────────┼──────────────────────────────┤
567 │Interface Stability │Committed │
568 ├─────────────────────────────┼──────────────────────────────┤
569 │MT-Level │Async-Signal-Safe │
570 ├─────────────────────────────┼──────────────────────────────┤
571 │Standard │For open(), see standards(5). │
572 └─────────────────────────────┴──────────────────────────────┘
573
575 Intro(2), chmod(2), close(2), creat(2), dup(2), exec(2), fcntl(2),
576 getmsg(2), getrlimit(2), lseek(2), putmsg(2), read(2), stat(2),
577 umask(2), write(2), attropen(3C), fcntl.h(3HEAD), stat.h(3HEAD),
578 unlockpt(3C), attributes(5), lf64(5), privileges(5), standards(5),
579 connld(7M), streamio(7I)
580
582 Hierarchical Storage Management (HSM) file systems can sometimes cause
583 long delays when opening a file, since HSM files must be recalled from
584 secondary storage.
585SunOS 5.11 16 Jun 2008 open(2)