1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Portions Copyright (c) 2013, OmniTI Computer Consulting, Inc.
47 .\" All Rights Reserved.
48 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
49 .\" Copyright 2020 Joyent, Inc.
50 .\" Copyright 2022 Oxide Computer Company
51 .\"
52 .Dd February 5, 2022
53 .Dt OPEN 2
54 .Os
55 .Sh NAME
56 .Nm open ,
57 .Nm openat
58 .Nd open a file
59 .Sh SYNOPSIS
60 .In sys/types.h
61 .In sys/stat.h
62 .In fcntl.h
63 .Ft int
64 .Fo open
65 .Fa "const char *path"
66 .Fa "int oflag"
67 .Op , Fa "mode_t mode"
68 .Fc
69 .Ft int
70 .Fo openat
71 .Fa "int fildes"
72 .Fa "const char *path"
73 .Fa "int oflag"
74 .Op , Fa "mode_t mode"
75 .Fc
76 .Sh DESCRIPTION
77 The
78 .Fn open
79 function establishes the connection between a file and a file descriptor.
80 It creates an open file description that refers to a file and a file descriptor
81 that refers to that open file description.
82 The file descriptor is used by other I/O functions to refer to that file.
83 The
84 .Fa path
85 argument points to a pathname naming the file.
86 .Pp
87 The
88 .Fn openat
89 function is identical to the
90 .Fn open
91 function except
92 that the
93 .Fa path
94 argument is interpreted relative to the starting point
95 implied by the
96 .Fa fildes
97 argument.
98 If the
99 .Fa fildes
100 argument has the special value
101 .Dv AT_FDCWD ,
102 a relative path argument will be resolved relative to the current working
103 directory.
104 If the
105 .Fa path
106 argument is absolute, the
107 .Fa fildes
108 argument is ignored.
109 .Pp
110 The
111 .Fn open
112 function returns a file descriptor for the named file that is the lowest file
113 descriptor not currently open for that process.
114 The open file description is new, and therefore the file descriptor does not
115 share it with any other process in the system.
116 The
117 .Dv FD_CLOEXEC
118 file descriptor flag associated with the new file descriptor is cleared.
119 .Pp
120 The file offset used to mark the current position within the file is set to the
121 beginning of the file.
122 .Pp
123 The file status flags and file access modes of the open file description are
124 set according to the value of
125 .Fa oflag .
126 The
127 .Fa mode
128 argument is used only
129 when
130 .Dv O_CREAT
131 is specified
132 .Pq "see below" .
133 .Pp
134 Values for
135 .Fa oflag
136 are constructed by a bitwise-inclusive-OR of flags from
137 the following list, defined in
138 .Xr fcntl.h 3HEAD .
139 Applications must specify exactly one of the first three values (file access
140 modes) below in the value of
141 .Fa oflag :
142 .Bl -tag -width Ds
143 .It Dv O_RDONLY
144 Open for reading only.
145 .It Dv O_WRONLY
146 Open for writing only.
147 .It Dv O_RDWR
148 Open for reading and writing.
149 The result is undefined if this flag is applied to a FIFO.
150 .El
151 .Pp
152 Any combination of the following may be used:
153 .Bl -tag -width Ds
154 .It Dv O_APPEND
155 If set, the file offset is set to the end of the file prior to each write.
156 .It Dv O_CREAT
157 Create the file if it does not exist.
158 This flag requires that the
159 .Fa mode
160 argument be specified.
161 .Pp
162 If the file exists, this flag has no effect except as noted under
163 .Dv O_EXCL
164 below.
165 Otherwise, the file is created with the user ID of the file set to the
166 effective user ID of the process.
167 The group ID of the file is set to the effective group IDs of the process, or
168 if the
169 .Dv S_ISGID
170 bit is set in the directory in which the file is being created, the file's
171 group ID is set to the group ID of its parent directory.
172 If the group ID of the new file does not match the effective group
173 ID or one of the supplementary groups IDs, the
174 .Dv S_ISGID bit is cleared.
175 .Pp
176 The access permission bits
177 .Po
178 see
179 .Xr stat.h 3HEAD
180 .Pc
181 of the file mode are set to the value of
182 .Fa mode ,
183 modified as follows
184 .Po
185 see
186 .Xr creat 2
187 .Pc :
188 a bitwise-AND is performed on the file-mode bits and the corresponding bits in
189 the complement of the process's file mode creation mask.
190 Thus, all bits set in the process's file mode creation mask
191 .Po
192 see
193 .Xr umask 2
194 .Pc
195 are correspondingly cleared in the file's permission mask.
196 The
197 .Dq save text image after execution bit
198 of the mode is cleared
199 .Po
200 see
201 .Xr chmod 2
202 .Pc .
203 When bits other than the file permission bits are set, the effect is
204 unspecified.
205 The
206 .Fa mode
207 argument does not affect whether the file is open for reading, writing or for
208 both.
209 .It Dv O_DIRECT
210 Indicates that the file data is not going to be reused in the near future.
211 When possible, data is read or written directly between the application's
212 memory and the device when the data is accessed with
213 .Xr read 2
214 and
215 .Xr write 2
216 operations.
217 See
218 .Xr directio 3C
219 for more details.
220 .It Dv O_DIRECTORY
221 Indicates that attempts to open
222 .Fa path
223 should fail unless
224 .Fa path
225 is a directory.
226 If both
227 .Dv O_CREAT
228 and
229 .Dv O_DIRECTORY
230 are specified then the call will fail if it would result in a file being
231 created.
232 If a directory already exists at
233 .Fa path
234 then it will behave as if the
235 .Dv O_DIRECTORY
236 flag had not been present.
237 If the
238 .Dv O_EXCL
239 and
240 .Dv O_CREAT
241 flags are specified, then the call will always fail as they imply a file should
242 always be created.
243 .It Dv O_DSYNC
244 Write I/O operations on the file descriptor complete as defined by synchronized
245 I/O data integrity completion.
246 .It Dv O_EXCL
247 If
248 .Dv O_CREAT
249 and
250 .Dv O_EXCL
251 are set,
252 .Fn open
253 fails if the file exists.
254 The check for the existence of the file and the creation of the file if
255 it does not exist is atomic with respect to other threads executing
256 .Fn open
257 naming the same filename in the same directory with
258 .Dv O_EXCL
259 and
260 .Dv O_CREAT
261 set.
262 If
263 .Dv O_EXCL
264 and
265 .Dv O_CREAT
266 are set, and
267 .Fa path
268 names a symbolic link,
269 .Fn open
270 fails and sets
271 .Va errno
272 to
273 .Er EEXIST ,
274 regardless of the contents of the symbolic link.
275 If
276 .Dv O_EXCL
277 is set and
278 .Dv O_CREAT
279 is not set, the result is undefined.
280 .It Dv O_EXEC
281 If set, indicates that the file should be opened for execute permission.
282 This option is only valid for regular files; an error will be returned if the
283 target is not a regular file.
284 .It Dv O_LARGEFILE
285 If set, the offset maximum in the open file description is the largest value
286 that can be represented correctly in an object of type
287 .Vt off64_t .
288 .It Dv O_NOCTTY
289 If set and
290 .Fa path
291 identifies a terminal device,
292 .Fn open
293 does not cause the terminal device to become the controlling terminal for the
294 process.
295 .It Dv O_NOFOLLOW
296 If the path names a symbolic link,
297 .Fn open
298 fails and sets
299 .Va errno
300 to
301 .Er ELOOP .
302 .It Dv O_NOLINKS
303 If the link count of the named file is greater than
304 .Sy 1 ,
305 .Fn open
306 fails and sets
307 .Va errno
308 to
309 .Er EMLINK .
310 .It Dv O_CLOEXEC
311 If set, the file descriptor returned will be closed prior to any future
312 .Xr exec 2
313 calls.
314 .It Dv O_NONBLOCK O_NDELAY
315 These flags can affect subsequent reads and writes
316 .Po
317 see
318 .Xr read 2
319 and
320 .Xr write 2
321 .Pc .
322 If both
323 .Dv O_NDELAY
324 and
325 .Dv O_NONBLOCK
326 are set,
327 .Dv O_NONBLOCK
328 takes precedence.
329 .Pp
330 When opening a FIFO with
331 .Dv O_RDONLY
332 or
333 .Dv O_WRONLY
334 set:
335 .Bl -bullet
336 .It
337 If
338 .Dv O_NONBLOCK
339 or
340 .Dv O_NDELAY
341 is set, an
342 .Fn open
343 for reading only returns without delay.
344 An
345 .Fn open
346 for writing only returns an error if no process currently has the file open for
347 reading.
348 .It
349 If
350 .Dv O_NONBLOCK
351 and
352 .Dv O_NDELAY
353 are clear, an
354 .Fn open
355 for reading only blocks until a thread opens the file for writing.
356 An
357 .Fn open
358 for writing only blocks the calling thread until a thread opens the file for
359 reading.
360 .El
361 .Pp
362 After both ends of a FIFO have been opened once, there is no guarantee that
363 further calls to
364 .Fn open
365 .Dv O_RDONLY
366 .Pq Dv O_WRONLY
367 will synchronize with later calls to
368 .Fn open
369 .Dv O_WRONLY
370 .Pq Dv O_RDONLY
371 until both ends of the FIFO have been closed by all readers and writers.
372 Any data written into a FIFO will be lost if both ends of the FIFO are closed
373 before the data is read.
374 .Pp
375 When opening a block special or character special file that supports
376 non-blocking opens:
377 .Bl -bullet
378 .It
379 If
380 .Dv O_NONBLOCK
381 or
382 .Dv O_NDELAY
383 is set, the
384 .Fn open
385 function returns without blocking for the device to be ready or available.
386 Subsequent behavior of the device is device-specific.
387 .It
388 If
389 .Dv O_NONBLOCK
390 and
391 .Dv O_NDELAY
392 are clear, the
393 .Fn open
394 function blocks the calling thread until the device is ready or available
395 before returning.
396 .El
397 .Pp
398 Otherwise, the behavior of
399 .Dv O_NONBLOCK
400 and
401 .Dv O_NDELAY
402 is unspecified.
403 .It Dv O_RSYNC
404 Read I/O operations on the file descriptor complete at the same level of
405 integrity as specified by the
406 .Dv O_DSYNC
407 and
408 .Dv O_SYNC
409 flags.
410 If both
411 .Dv O_DSYNC
412 and
413 .Dv O_RSYNC
414 are set in
415 .Fa oflag ,
416 all I/O operations on the file descriptor complete as defined by synchronized
417 I/O data integrity completion.
418 If both
419 .Dv O_SYNC
420 and
421 .Dv O_RSYNC
422 are set in
423 .Fa oflag ,
424 all I/O operations on the file descriptor complete as defined by synchronized
425 I/O file integrity completion.
426 .It Dv O_SEARCH
427 If set, indicates that the directory should be opened for searching.
428 This option is only valid for a directory; an error will be returned if the
429 target is not a directory.
430 .It Dv O_SYNC
431 Write I/O operations on the file descriptor complete as defined by synchronized
432 I/O file integrity completion
433 .Po
434 see
435 .Xr fcntl.h 3HEAD
436 .Pc
437 definition of
438 .Dv O_SYNC .
439 .It Dv O_TRUNC
440 If the file exists and is a regular file, and the file is successfully opened
441 .Dv O_RDWR
442 or
443 .Dv O_WRONLY ,
444 its length is truncated to
445 .Sy 0
446 and the mode and owner are unchanged.
447 It has no effect on FIFO special files or terminal device files.
448 Its effect on other file types is implementation-dependent.
449 The result of using
450 .Dv O_TRUNC
451 with
452 .Dv O_RDONLY
453 is undefined.
454 .It Dv O_XATTR
455 If set in
456 .Fn openat ,
457 a relative path argument is interpreted as a reference to an extended attribute
458 of the file associated with the supplied file descriptor.
459 This flag therefore requires the presence of a legal
460 .Fa fildes
461 argument.
462 If set in
463 .Fn open ,
464 the implied file descriptor is that for the current working directory.
465 Extended attributes must be referenced with a relative path; providing an
466 absolute path results in a normal file reference.
467 .El
468 .Pp
469 If
470 .Dv O_CREAT
471 is set and the file did not previously exist, upon successful completion,
472 .Fn open
473 marks for update the
474 .Fa st_atime ,
475 .Fa st_ctime ,
476 and
477 .Fa st_mtime
478 fields of the file and the
479 .Fa st_ctime
480 and
481 .Fa st_mtime
482 fields of the parent directory.
483 .Pp
484 If
485 .Dv O_TRUNC
486 is set and the file did previously exist, upon successful completion,
487 .Fn open
488 marks for update the
489 .Fa st_ctime
490 and
491 .Fa st_mtime
492 fields of the file.
493 .Pp
494 If both the
495 .Dv O_SYNC
496 and
497 .Dv O_DSYNC
498 flags are set, the effect is as if only the
499 .Dv O_SYNC
500 flag was set.
501 .Pp
502 If
503 .Fa path
504 refers to a STREAMS file,
505 .Fa oflag
506 may be constructed from
507 .Dv O_NONBLOCK
508 or
509 .Dv O_NODELAY
510 OR-ed with either
511 .Dv O_RDONLY ,
512 .Dv O_WRONLY ,
513 or
514 .Dv O_RDWR .
515 Other flag values are not applicable to STREAMS devices and have no effect on
516 them.
517 The values
518 .Dv O_NONBLOCK
519 and
520 .Dv O_NODELAY
521 affect the operation of STREAMS drivers and certain functions
522 .Po
523 see
524 .Xr read 2 ,
525 .Xr getmsg 2 ,
526 .Xr putmsg 2 ,
527 and
528 .Xr write 2
529 .Pc
530 applied to file descriptors associated with STREAMS files.
531 For STREAMS drivers, the implementation of
532 .Dv O_NONBLOCK
533 and
534 .Dv O_NODELAY
535 is device-specific.
536 .Pp
537 When
538 .Fn open
539 is invoked to open a named stream, and the
540 .Xr connld 7M
541 module has been pushed on the pipe,
542 .Fn open
543 blocks until the server process has issued an
544 .Dv I_RECVFD
545 .Xr ioctl 2
546 .Po
547 see
548 .Xr streamio 7I
549 .Pc
550 to receive the file descriptor.
551 .Pp
552 If
553 .Fa path
554 names the manager side of a pseudo-terminal device, then it is unspecified
555 whether
556 .Fn open
557 locks the subsidiary side so that it cannot be opened.
558 Portable applications must call
559 .Xr unlockpt 3C
560 before opening the subsidiary side.
561 .Pp
562 If the file is a regular file and the local file system is mounted with the
563 .Cm nbmand
564 mount option, then a mandatory share reservation is automatically obtained on
565 the file.
566 The share reservation is obtained as if
567 .Xr fcntl 2
568 were called with
569 .Fa cmd
570 .Dv F_SHARE_NBMAND
571 and the
572 .Vt fshare_t
573 values set as follows:
574 .Bl -tag -width Ds -offset Ds
575 .It Fa f_access
576 Set to the type of read/write access for which the file is opened.
577 .It Fa f_deny
578 .Dv F_NODNY
579 .It Fa f_id
580 The file descriptor value returned from
581 .Fn open .
582 .El
583 .Pp
584 If
585 .Fa path
586 is a symbolic link and
587 .Dv O_CREAT
588 and
589 .Dv O_EXCL
590 are set, the link is not followed.
591 .Pp
592 Certain flag values can be set following
593 .Fn open
594 as described in
595 .Xr fcntl 2 .
596 .Pp
597 The largest value that can be represented correctly in an object of type
598 .Vt off_t
599 is established as the offset maximum in the open file description.
600 .Sh RETURN VALUES
601 The
602 .Fn open
603 and
604 .Fn openat
605 functions open the file and, if successful, return a non-negative integer
606 representing the lowest numbered unused file descriptor; otherwise the
607 value
608 .Sy -1
609 is returned and the global variable
610 .Va errno
611 is set to indicate the error and no files are created or modified.
612 .Sh EXAMPLES
613 .Sy Example 1
614 Open a file for writing by the owner.
615 .Pp
616 The following example opens the file
617 .Pa /tmp/file ,
618 either by creating it if it does not already exist, or by truncating its length
619 to
620 .Sy 0
621 if it does exist.
622 If the call creates a new file, the access permission bits in the file mode of
623 the file are set to permit reading and writing by the owner, and to permit
624 reading only by group members and others.
625 .Pp
626 If the call to
627 .Fn open
628 is successful, the file is opened for writing.
629 .Bd -literal -offset Ds
630 #include <fcntl.h>
631 \&...
632 int fd;
633 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
634 char *filename = "/tmp/file";
635 \&...
636 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
637 \&...
638 .Ed
639 .Pp
640 .Sy Example 2
641 Open a file using an existence check.
642 .Pp
643 The following example uses the
644 .Fn open
645 function to try to create the
646 .Dv LOCKFILE
647 file and open it for writing.
648 Since the
649 .Fn open
650 function specifies the
651 .Dv O_EXCL
652 flag, the call fails if the file already exists.
653 In that case, the application assumes that someone else is updating the
654 password file and exits.
655 .Bd -literal -offset Ds
656 #include <fcntl.h>
657 #include <stdio.h>
658 #include <stdlib.h>
659 #include <err.h>
660 \&...
661 #define LOCKFILE "/etc/ptmp"
662 \&...
663 int pfd; /* Integer for file descriptor returned by open() call. */
664 \&...
665 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
666 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
667 err(1, "Cannot open %s. Try again later.", LOCKFILE);
668 }
669 \&...
670 .Ed
671 .Pp
672 .Sy Example 3
673 Open a file for writing.
674 .Pp
675 The following example opens a file for writing, creating the file if it does
676 not already exist.
677 If the file does exist, the system truncates the file to zero bytes.
678 .Bd -literal -offset Ds
679 #include <fcntl.h>
680 #include <stdio.h>
681 #include <stdlib.h>
682 #include <err.h>
683 \&...
684 int pfd;
685 char filename[PATH_MAX+1];
686 \&...
687 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
688 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) < 0) {
689 err(1, "Cannot open output file");
690 }
691 \&...
692 .Ed
693 .Sh ERRORS
694 The
695 .Fn open
696 and
697 .Fn openat
698 functions will fail if:
699 .Bl -tag -width Er
700 .It Er EACCES
701 Search permission is denied on a component of the path prefix.
702 .Pp
703 The file exists and the permissions specified by
704 .Fa oflag
705 are denied.
706 .Pp
707 The file does not exist and write permission is denied for the parent directory
708 of the file to be created.
709 .Pp
710 .Dv O_TRUNC
711 is specified and write permission is denied.
712 .Pp
713 The
714 .Brq Dv PRIV_FILE_DAC_SEARCH
715 privilege allows processes to search directories regardless of permission bits.
716 The
717 .Brq Dv PRIV_FILE_DAC_WRITE
718 privilege allows processes to open files for writing regardless of permission
719 bits.
720 See
721 .Xr privileges 5 for special considerations when opening files owned by user ID
722 .Sy 0
723 for writing.
724 The
725 .Brq Dv PRIV_FILE_DAC_READ
726 privilege allows
727 processes to open files for reading regardless of permission bits.
728 .It Er EAGAIN
729 A mandatory share reservation could not be obtained because the desired access
730 conflicts with an existing
731 .Fa f_deny
732 share reservation
733 .Po
734 see
735 .Xr fcntl 2
736 .Pc .
737 .It Er EDQUOT
738 The file does not exist,
739 .Dv O_CREAT
740 is specified, and either the directory where the new file entry is being placed
741 cannot be extended because the user's quota of disk blocks on that file system
742 has been exhausted, or the user's quota of inodes on the file system where the
743 file is being created has been exhausted.
744 .It Er EEXIST
745 The
746 .Dv O_CREAT
747 and
748 .Dv O_EXCL
749 flags are set and the named file already exists.
750 .It Er EILSEQ
751 The
752 .Fa path
753 argument includes bytes that are not valid UTF-8 characters, and the file
754 system accepts only file names where all characters are part of the UTF-8
755 character codeset.
756 .It Er EINTR
757 A signal was caught during
758 .Fn open .
759 .It Er EFAULT
760 The
761 .Fa path
762 argument points to an illegal address.
763 .It Er EINVAL
764 Either the system does not support synchronized or direct I/O for this file, or
765 the
766 .Dv O_XATTR
767 flag was supplied and the underlying file system does not support extended file
768 attributes.
769 .It Er EIO
770 The
771 .Fa path
772 argument names a STREAMS file and a hangup or error occurred during the
773 .Fn open .
774 .It Er EISDIR
775 The named file is a directory and
776 .Fa oflag
777 includes
778 .Dv O_WRONLY
779 or
780 .Dv O_RDWR .
781 .It Er ELOOP
782 Too many symbolic links were encountered in resolving
783 .Fa path .
784 .Pp
785 A loop exists in symbolic links encountered during resolution of the
786 .Fa path
787 argument.
788 .Pp
789 The
790 .Dv O_NOFOLLOW
791 flag is set and the final component of path is a symbolic link.
792 .It Er EMFILE
793 There are currently
794 .Brq Dv OPEN_MAX
795 file descriptors open in the calling process.
796 .It Er EMLINK
797 The
798 .Dv O_NOLINKS
799 flag is set and the named file has a link count greater than
800 .Sy 1 .
801 .It Er EMULTIHOP
802 Components of
803 .Fa path
804 require hopping to multiple remote machines and the file system does not allow
805 it.
806 .It Er ENAMETOOLONG
807 The length of the
808 .Fa path
809 argument exceeds
810 .Brq Dv PATH_MAX
811 or a pathname component is longer than
812 .Brq Dv NAME_MAX .
813 .It Er ENFILE
814 The maximum allowable number of files is currently open in the system.
815 .It Er ENOENT
816 The
817 .Dv O_CREAT
818 flag is not set and the named file does not exist; or the
819 .Dv O_CREAT
820 flag is set and either the path prefix does not exist or the
821 .Fa path
822 argument points to an empty string.
823 .Pp
824 The
825 .Dv O_CREAT
826 and
827 .Dv O_DIRECTORY
828 flags were both set and
829 .Fa path
830 did not point to a file.
831 .It Er ENOEXEC
832 The
833 .Dv O_EXEC
834 flag is set and
835 .Fa path
836 does not point to a regular file.
837 .It Er ENOLINK
838 The
839 .Fa path
840 argument points to a remote machine, and the link to that machine is no longer
841 active.
842 .It Er ENOSR
843 Th
844 .Fa path
845 argument names a STREAMS-based file and the system is unable to allocate a
846 STREAM.
847 .It Er ENOSPC
848 The directory or file system that would contain the new file cannot be
849 expanded, the file does not exist, and
850 .Dv O_CREAT
851 is specified.
852 .It Er ENOSYS
853 The device specified by
854 .Fa path
855 does not support the open operation.
856 .It Er ENOTDIR
857 A component of the path prefix is not a directory or a relative path was
858 supplied to
859 .Fn openat ,
860 the
861 .Dv O_XATTR
862 flag was not supplied, and the file descriptor does not refer to a directory.
863 The
864 .Dv O_SEARCH
865 flag was passed and
866 .Fa path
867 does not refer to a directory.
868 .Pp
869 The
870 .Dv O_DIRECTORY
871 flag was set and the file was not a directory.
872 .It Er ENXIO
873 The
874 .Dv O_NONBLOCK
875 flag is set, the named file is a FIFO, the
876 .Dv O_WRONLY
877 flag is set, and no process has the file open for reading; or the named file is
878 a character special or block special file and the device associated with this
879 special file does not exist or has been retired by the fault management
880 framework.
881 .It Er EOPNOTSUPP
882 An attempt was made to open a path that corresponds to an
883 .Dv AF_UNIX
884 socket.
885 .It Er EOVERFLOW
886 The named file is a regular file and either
887 .Dv O_LARGEFILE
888 is not set and the size of the file cannot be represented correctly in an
889 object of type
890 .Vt off_t
891 or
892 .Dv O_LARGEFILE
893 is set and the size of the file cannot be represented correctly in an object of
894 type
895 .Vt off64_t .
896 .It Er EROFS
897 The named file resides on a read-only file system and either
898 .Dv O_WRONLY ,
899 .Dv O_RDWR ,
900 .Dv O_CREAT
901 (if file does not exist), or
902 .Dv O_TRUNC
903 is set in the
904 .Fa oflag
905 argument.
906 .El
907 .Pp
908 The
909 .Fn openat
910 function will fail if:
911 .Bl -tag -width Er
912 .It Er EBADF
913 The
914 .Fa fildes
915 argument is not a valid open file descriptor or is not
916 .Dv AT_FTCWD .
917 .El
918 .Pp
919 The
920 .Fn open
921 function may fail if:
922 .Bl -tag -width Er
923 .It Er EAGAIN
924 The
925 .Fa path
926 argument names the subsidiary side of a pseudo-terminal device that is locked.
927 .It Er EINVAL
928 The value of the
929 .Fa oflag
930 argument is not valid.
931 .It Er ENAMETOOLONG
932 Pathname resolution of a symbolic link produced an intermediate result whose
933 length exceeds
934 .Brq Dv PATH_MAX .
935 .It Er ENOMEM
936 The
937 .Fa path
938 argument names a STREAMS file and the system is unable to allocate resources.
939 .It Er ETXTBSY
940 The file is a pure procedure (shared text) file that is being executed and
941 .Fa oflag
942 is
943 .Dv O_WRONLY
944 or
945 .Dv O_RDWR .
946 .El
947 .Sh USAGE
948 The
949 .Fn open
950 function has a transitional interface for 64-bit file offsets.
951 See
952 .Xr lf64 5 .
953 Note that using
954 .Fn open64
955 is equivalent to using
956 .Fn open with
957 .Dv O_LARGEFILE
958 set in
959 .Fa oflag .
960 .Sh INTERFACE STABILITY
961 .Sy Committed
962 .Sh MT LEVEL
963 .Sy Async-Signal-Safe
964 .Sh SEE ALSO
965 .Xr chmod 2 ,
966 .Xr close 2 ,
967 .Xr creat 2 ,
968 .Xr dup 2 ,
969 .Xr exec 2 ,
970 .Xr fcntl 2 ,
971 .Xr getmsg 2 ,
972 .Xr getrlimit 2 ,
973 .Xr Intro 2 ,
974 .Xr lseek 2 ,
975 .Xr putmsg 2 ,
976 .Xr read 2 ,
977 .Xr stat 2 ,
978 .Xr umask 2 ,
979 .Xr write 2 ,
980 .Xr attropen 3C ,
981 .Xr directio 3C ,
982 .Xr unlockpt 3C ,
983 .Xr fcntl.h 3HEAD ,
984 .Xr stat.h 3HEAD ,
985 .Xr attributes 5 ,
986 .Xr lf64 5 ,
987 .Xr privileges 5 ,
988 .Xr standards 5 ,
989 .Xr streamio 7I ,
990 .Xr connld 7M
991 .Sh NOTES
992 Hierarchical Storage Management
993 .Pq HSM
994 file systems can sometimes cause long delays when opening a file, since HSM
995 files must be recalled from secondary storage.