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 .\"
51 .TH OPEN 2 "Mar 10, 2020"
52 .SH NAME
53 open, openat \- open a file
54 .SH SYNOPSIS
55 .nf
56 #include <sys/types.h>
57 #include <sys/stat.h>
58 #include <fcntl.h>
59
60 \fBint\fR \fBopen\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIoflag\fR, \fB/* mode_t\fR \fImode\fR */);
61 .fi
62
63 .LP
64 .nf
65 \fBint\fR \fBopenat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR, \fBint\fR \fIoflag\fR,
66 \fB/* mode_t\fR \fImode\fR */);
67 .fi
68
69 .SH DESCRIPTION
70 The \fBopen()\fR function establishes the connection between a file and a file
71 descriptor. It creates an open file description that refers to a file and a
72 file descriptor that refers to that open file description. The file descriptor
73 is used by other I/O functions to refer to that file. The \fIpath\fR argument
74 points to a pathname naming the file.
75 .sp
76 .LP
77 The \fBopenat()\fR function is identical to the \fBopen()\fR function except
78 that the \fIpath\fR argument is interpreted relative to the starting point
79 implied by the \fIfildes\fR argument. If the \fIfildes\fR argument has the
80 special value \fBAT_FDCWD\fR, a relative path argument will be resolved
81 relative to the current working directory. If the \fIpath\fR argument is
82 absolute, the \fIfildes\fR argument is ignored.
83 .sp
84 .LP
85 The \fBopen()\fR function returns a file descriptor for the named file that is
86 the lowest file descriptor not currently open for that process. The open file
87 description is new, and therefore the file descriptor does not share it with
88 any other process in the system. The \fBFD_CLOEXEC\fR file descriptor flag
89 associated with the new file descriptor is cleared.
90 .sp
91 .LP
92 The file offset used to mark the current position within the file is set to the
93 beginning of the file.
94 .sp
95 .LP
96 The file status flags and file access modes of the open file description are
97 set according to the value of \fIoflag\fR. The \fImode\fR argument is used only
98 when \fBO_CREAT\fR is specified (see below.)
99 .sp
100 .LP
101 Values for \fIoflag\fR are constructed by a bitwise-inclusive-OR of flags from
102 the following list, defined in <\fBfcntl.h\fR>. Applications must specify
103 exactly one of the first three values (file access modes) below in the value of
104 \fIoflag\fR:
105 .sp
106 .ne 2
107 .na
108 \fB\fBO_RDONLY\fR\fR
109 .ad
110 .RS 12n
111 Open for reading only.
112 .RE
113
114 .sp
115 .ne 2
116 .na
117 \fB\fBO_WRONLY\fR\fR
118 .ad
119 .RS 12n
120 Open for writing only.
121 .RE
122
123 .sp
124 .ne 2
125 .na
126 \fB\fBO_RDWR\fR\fR
127 .ad
128 .RS 12n
129 Open for reading and writing. The result is undefined if this flag is applied
130 to a FIFO.
131 .RE
132
133 .sp
134 .LP
135 Any combination of the following may be used:
136 .sp
137 .ne 2
138 .na
139 \fB\fBO_APPEND\fR\fR
140 .ad
141 .sp .6
142 .RS 4n
143 If set, the file offset is set to the end of the file prior to each write.
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fBO_CREAT\fR\fR
150 .ad
151 .sp .6
152 .RS 4n
153 Create the file if it does not exist. This flag requires that the \fImode\fR
154 argument be specified.
155 .sp
156 If the file exists, this flag has no effect except as noted under \fBO_EXCL\fR
157 below. Otherwise, the file is created with the user \fBID\fR of the file set
158 to the effective user \fBID\fR of the process. The group \fBID\fR of the file
159 is set to the effective group \fBIDs\fR of the process, or if the \fBS_ISGID\fR
160 bit is set in the directory in which the file is being created, the file's
161 group \fBID\fR is set to the group \fBID\fR of its parent directory. If the
162 group \fBID\fR of the new file does not match the effective group \fBID\fR or
163 one of the supplementary groups IDs, the \fBS_ISGID\fR bit is cleared. The
164 access permission bits (see \fB<sys/stat.h>\fR) of the file mode are set to the
165 value of \fImode\fR, modified as follows (see \fBcreat\fR(2)): a bitwise-AND is
166 performed on the file-mode bits and the corresponding bits in the complement of
167 the process's file mode creation mask. Thus, all bits set in the process's file
168 mode creation mask (see \fBumask\fR(2)) are correspondingly cleared in the
169 file's permission mask. The "save text image after execution bit" of the mode
170 is cleared (see \fBchmod\fR(2)). When bits other than the file permission bits
171 are set, the effect is unspecified. The \fImode\fR argument does not affect
172 whether the file is open for reading, writing or for both.
173 .RE
174
175 .sp
176 .ne 2
177 .na
178 .B O_DIRECT
179 .ad
180 .sp .6
181 .RS 4n
182 Indicates that the file data is not going to be reused in the near future.
183 When possible, data is read or written directly between the application's
184 memory and the device when the data is accessed with \fBread\fR(2) and
185 \fBwrite\fR(2) operations. See \fBdirectio\fR(3C) for more details.
186 .RE
187
188 .sp
189 .ne 2
190 .na
191 .B O_DIRECTORY
192 .ad
193 .sp .6
194 .RS 4n
195 Indicates that attempts to open
196 .I path
197 should fail unless
198 .I path
199 is a directory.
200 If both
201 .B O_CREAT
202 and
203 .B O_DIRECTORY
204 are specified then the call will fail if it would result in a file being
205 created.
206 If a directory already exists at
207 .I path
208 then it will behave as if the
209 .B O_DIRECTORY
210 flag had not been present.
211 If the
212 .B O_EXCL
213 and
214 .B O_CREAT
215 flags are specified, then the call will always fail as they imply a file
216 should always be created.
217 .RE
218
219 .sp
220 .ne 2
221 .na
222 \fB\fBO_DSYNC\fR\fR
223 .ad
224 .sp .6
225 .RS 4n
226 Write I/O operations on the file descriptor complete as defined by synchronized
227 I/O data integrity completion.
228 .RE
229
230 .sp
231 .ne 2
232 .na
233 \fB\fBO_EXCL\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 If \fBO_CREAT\fR and \fBO_EXCL\fR are set, \fBopen()\fR fails if the file
238 exists. The check for the existence of the file and the creation of the file if
239 it does not exist is atomic with respect to other threads executing
240 \fBopen()\fR naming the same filename in the same directory with \fBO_EXCL\fR
241 and \fBO_CREAT\fR set. If \fBO_EXCL\fR and \fBO_CREAT\fR are set, and path
242 names a symbolic link, \fBopen()\fR fails and sets \fBerrno\fR to \fBEEXIST\fR,
243 regardless of the contents of the symbolic link. If \fBO_EXCL\fR is set and
244 \fBO_CREAT\fR is not set, the result is undefined.
245 .RE
246
247 .sp
248 .ne 2
249 .na
250 .B O_EXEC
251 .na
252 .ad
253 .sp .6
254 .RS 4n
255 If set, indicates that the file should be opened for execute permission.
256 This option is only valid for regular files, an error will be returned
257 if it is not.
258 .RE
259
260 .sp
261 .ne 2
262 .na
263 \fB\fBO_LARGEFILE\fR\fR
264 .ad
265 .sp .6
266 .RS 4n
267 If set, the offset maximum in the open file description is the largest value
268 that can be represented correctly in an object of type \fBoff64_t\fR.
269 .RE
270
271 .sp
272 .ne 2
273 .na
274 \fB\fBO_NOCTTY\fR\fR
275 .ad
276 .sp .6
277 .RS 4n
278 If set and \fIpath\fR identifies a terminal device, \fBopen()\fR does not cause
279 the terminal device to become the controlling terminal for the process.
280 .RE
281
282 .sp
283 .ne 2
284 .na
285 \fB\fBO_NOFOLLOW\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 If the path names a symbolic link, \fBopen()\fR fails and sets \fBerrno\fR to
290 \fBELOOP\fR.
291 .RE
292
293 .sp
294 .ne 2
295 .na
296 \fB\fBO_NOLINKS\fR\fR
297 .ad
298 .sp .6
299 .RS 4n
300 If the link count of the named file is greater than 1, \fBopen()\fR fails and
301 sets \fBerrno\fR to \fBEMLINK\fR.
302 .RE
303
304 .sp
305 .ne 2
306 .na
307 \fB\fBO_CLOEXEC\fR\fR
308 .ad
309 .sp .6
310 .RS 4n
311 If set, the file descriptor returned will be closed prior to any future
312 \fBexec()\fR calls.
313 .RE
314
315 .sp
316 .ne 2
317 .na
318 \fB\fBO_NONBLOCK\fR or \fBO_NDELAY\fR\fR
319 .ad
320 .sp .6
321 .RS 4n
322 These flags can affect subsequent reads and writes (see \fBread\fR(2) and
323 \fBwrite\fR(2)). If both \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are set,
324 \fBO_NONBLOCK\fR takes precedence.
325 .sp
326 When opening a \fBFIFO\fR with \fBO_RDONLY\fR or \fBO_WRONLY\fR set:
327 .RS +4
328 .TP
329 .ie t \(bu
330 .el o
331 If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, an \fBopen()\fR for reading only
332 returns without delay. An \fBopen()\fR for writing only returns an error if no
333 process currently has the file open for reading.
334 .RE
335 .RS +4
336 .TP
337 .ie t \(bu
338 .el o
339 If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, an \fBopen()\fR for reading
340 only blocks until a thread opens the file for writing. An \fBopen()\fR for
341 writing only blocks the calling thread until a thread opens the file for
342 reading.
343 .RE
344 After both ends of a \fBFIFO\fR have been opened, there is no guarantee that
345 further calls to \fBopen()\fR \fBO_RDONLY\fR (\fBO_WRONLY\fR) will synchronize
346 with later calls to \fBopen()\fR \fBO_WRONLY\fR (\fBO_RDONLY\fR) until both
347 ends of the \fBFIFO\fR have been closed by all readers and writers. Any data
348 written into a \fBFIFO\fR will be lost if both ends of the \fBFIFO\fR are
349 closed before the data is read.
350 .sp
351 When opening a block special or character special file that supports
352 non-blocking opens:
353 .RS +4
354 .TP
355 .ie t \(bu
356 .el o
357 If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, the \fBopen()\fR function returns
358 without blocking for the device to be ready or available. Subsequent behavior
359 of the device is device-specific.
360 .RE
361 .RS +4
362 .TP
363 .ie t \(bu
364 .el o
365 If \fBO_NONBLOCK\fR and \fBO_NDELAY\fR are clear, the \fBopen()\fR function
366 blocks the calling thread until the device is ready or available before
367 returning.
368 .RE
369 Otherwise, the behavior of \fBO_NONBLOCK\fR and \fBO_NDELAY\fR is unspecified.
370 .RE
371
372 .sp
373 .ne 2
374 .na
375 \fB\fBO_RSYNC\fR\fR
376 .ad
377 .sp .6
378 .RS 4n
379 Read I/O operations on the file descriptor complete at the same level of
380 integrity as specified by the \fBO_DSYNC\fR and \fBO_SYNC\fR flags. If both
381 \fBO_DSYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all I/O operations on
382 the file descriptor complete as defined by synchronized I/O data integrity
383 completion. If both \fBO_SYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all
384 I/O operations on the file descriptor complete as defined by synchronized I/O
385 file integrity completion.
386 .RE
387
388 .sp
389 .ne 2
390 .na
391 .B O_SEARCH
392 .ad
393 .sp .6
394 .RS 4n
395 If set, indicates that the directory should be opened for searching.
396 This option is only valid for a directory, an error will be returned if
397 it is not.
398 .RE
399
400 .sp
401 .ne 2
402 .na
403 \fB\fBO_SYNC\fR\fR
404 .ad
405 .sp .6
406 .RS 4n
407 Write I/O operations on the file descriptor complete as defined by synchronized
408 I/O file integrity completion (see \fBfcntl.h\fR(3HEAD) definition of
409 \fBO_SYNC\fR).
410 .RE
411
412 .sp
413 .ne 2
414 .na
415 \fB\fBO_TRUNC\fR\fR
416 .ad
417 .sp .6
418 .RS 4n
419 If the file exists and is a regular file, and the file is successfully opened
420 \fBO_RDWR\fR or \fBO_WRONLY\fR, its length is truncated to 0 and the mode and
421 owner are unchanged. It has no effect on \fBFIFO\fR special files or terminal
422 device files. Its effect on other file types is implementation-dependent. The
423 result of using \fBO_TRUNC\fR with \fBO_RDONLY\fR is undefined.
424 .RE
425
426 .sp
427 .ne 2
428 .na
429 \fB\fBO_XATTR\fR\fR
430 .ad
431 .sp .6
432 .RS 4n
433 If set in \fBopenat()\fR, a relative path argument is interpreted as a
434 reference to an extended attribute of the file associated with the supplied
435 file descriptor. This flag therefore requires the presence of a legal
436 \fIfildes\fR argument. If set in \fBopen()\fR, the implied file descriptor is
437 that for the current working directory. Extended attributes must be referenced
438 with a relative path; providing an absolute path results in a normal file
439 reference.
440 .RE
441
442 .sp
443 .LP
444 If \fBO_CREAT\fR is set and the file did not previously exist, upon successful
445 completion, \fBopen()\fR marks for update the \fBst_atime\fR, \fBst_ctime\fR,
446 and \fBst_mtime\fR fields of the file and the \fBst_ctime\fR and \fBst_mtime\fR
447 fields of the parent directory.
448 .sp
449 .LP
450 If \fBO_TRUNC\fR is set and the file did previously exist, upon successful
451 completion, \fBopen()\fR marks for update the \fBst_ctime\fR and \fBst_mtime\fR
452 fields of the file.
453 .sp
454 .LP
455 If both the \fBO_SYNC\fR and \fBO_DSYNC\fR flags are set, the effect is as if
456 only the \fBO_SYNC\fR flag was set.
457 .sp
458 .LP
459 If \fIpath\fR refers to a \fBSTREAMS\fR file, \fIoflag\fR may be constructed
460 from \fBO_NONBLOCK\fR or \fBO_NODELAY\fR OR-ed with either \fBO_RDONLY\fR,
461 \fBO_WRONLY\fR, or \fBO_RDWR\fR. Other flag values are not applicable to
462 \fBSTREAMS\fR devices and have no effect on them. The values \fBO_NONBLOCK\fR
463 and \fBO_NODELAY\fR affect the operation of \fBSTREAMS\fR drivers and certain
464 functions (see \fBread\fR(2), \fBgetmsg\fR(2), \fBputmsg\fR(2), and
465 \fBwrite\fR(2)) applied to file descriptors associated with \fBSTREAMS\fR
466 files. For \fBSTREAMS\fR drivers, the implementation of \fBO_NONBLOCK\fR and
467 \fBO_NODELAY\fR is device-specific.
468 .sp
469 .LP
470 When \fBopen()\fR is invoked to open a named stream, and the \fBconnld\fR
471 module (see \fBconnld\fR(7M)) has been pushed on the pipe, \fBopen()\fR blocks
472 until the server process has issued an \fBI_RECVFD\fR \fBioctl()\fR (see
473 \fBstreamio\fR(7I)) to receive the file descriptor.
474 .sp
475 .LP
476 If \fIpath\fR names the master side of a pseudo-terminal device, then it is
477 unspecified whether \fBopen()\fR locks the slave side so that it cannot be
478 opened. Portable applications must call \fBunlockpt\fR(3C) before opening the
479 slave side.
480 .sp
481 .LP
482 If the file is a regular file and the local file system is mounted with the
483 \fBnbmand\fR mount option, then a mandatory share reservation is automatically
484 obtained on the file. The share reservation is obtained as if \fBfcntl\fR(2)
485 were called with \fIcmd\fR \fBF_SHARE_NBMAND\fR and the \fBfshare_t\fR values
486 set as follows:
487 .sp
488 .ne 2
489 .na
490 \fB\fBf_access\fR\fR
491 .ad
492 .RS 12n
493 Set to the type of read/write access for which the file is opened.
494 .RE
495
496 .sp
497 .ne 2
498 .na
499 \fB\fBf_deny\fR\fR
500 .ad
501 .RS 12n
502 \fBF_NODNY\fR
503 .RE
504
505 .sp
506 .ne 2
507 .na
508 \fB\fBf_id\fR\fR
509 .ad
510 .RS 12n
511 The file descriptor value returned from \fBopen()\fR.
512 .RE
513
514 .sp
515 .LP
516 If \fIpath\fR is a symbolic link and \fBO_CREAT\fR and \fBO_EXCL\fR are set,
517 the link is not followed.
518 .sp
519 .LP
520 Certain flag values can be set following \fBopen()\fR as described in
521 \fBfcntl\fR(2).
522 .sp
523 .LP
524 The largest value that can be represented correctly in an object of type
525 \fBoff_t\fR is established as the offset maximum in the open file description.
526 .SH RETURN VALUES
527 Upon successful completion, both \fBopen()\fR and \fBopenat()\fR functions open
528 the file and return a non-negative integer representing the lowest numbered
529 unused file descriptor. Otherwise, \fB\(mi1\fR is returned, \fBerrno\fR is set
530 to indicate the error, and no files are created or modified.
531 .SH ERRORS
532 The \fBopen()\fR and \fBopenat()\fR functions will fail if:
533 .sp
534 .ne 2
535 .na
536 \fB\fBEACCES\fR\fR
537 .ad
538 .RS 16n
539 Search permission is denied on a component of the path prefix.
540 .sp
541 The file exists and the permissions specified by \fIoflag\fR are denied.
542 .sp
543 The file does not exist and write permission is denied for the parent directory
544 of the file to be created.
545 .sp
546 \fBO_TRUNC\fR is specified and write permission is denied.
547 .sp
548 The {\fBPRIV_FILE_DAC_SEARCH\fR} privilege allows processes to search
549 directories regardless of permission bits. The {\fBPRIV_FILE_DAC_WRITE\fR}
550 privilege allows processes to open files for writing regardless of permission
551 bits. See \fBprivileges\fR(5) for special considerations when opening files
552 owned by UID 0 for writing. The {\fBPRIV_FILE_DAC_READ\fR} privilege allows
553 processes to open files for reading regardless of permission bits.
554 .RE
555
556 .sp
557 .ne 2
558 .na
559 \fB\fBEAGAIN\fR\fR
560 .ad
561 .RS 16n
562 A mandatory share reservation could not be obtained because the desired access
563 conflicts with an existing \fBf_deny\fR share reservation.
564 .RE
565
566 .sp
567 .ne 2
568 .na
569 \fB\fBEDQUOT\fR\fR
570 .ad
571 .RS 16n
572 The file does not exist, \fBO_CREAT\fR is specified, and either the directory
573 where the new file entry is being placed cannot be extended because the user's
574 quota of disk blocks on that file system has been exhausted, or the user's
575 quota of inodes on the file system where the file is being created has been
576 exhausted.
577 .RE
578
579 .sp
580 .ne 2
581 .na
582 \fB\fBEEXIST\fR\fR
583 .ad
584 .RS 16n
585 The \fBO_CREAT\fR and \fBO_EXCL\fR flags are set and the named file exists.
586 .RE
587
588 .sp
589 .ne 2
590 .na
591 \fB\fBEILSEQ\fR\fR
592 .ad
593 .RS 16n
594 The \fIpath\fR argument includes non-UTF8 characters and the file system
595 accepts only file names where all characters are part of the UTF-8 character
596 codeset.
597 .RE
598
599 .sp
600 .ne 2
601 .na
602 \fB\fBEINTR\fR\fR
603 .ad
604 .RS 16n
605 A signal was caught during \fBopen()\fR.
606 .RE
607
608 .sp
609 .ne 2
610 .na
611 \fB\fBEFAULT\fR\fR
612 .ad
613 .RS 16n
614 The \fIpath\fR argument points to an illegal address.
615 .RE
616
617 .sp
618 .ne 2
619 .na
620 \fB\fBEINVAL\fR\fR
621 .ad
622 .RS 16n
623 The system does not support synchronized or direct I/O for this file, or the
624 \fBO_XATTR\fR flag was supplied and the underlying file system does not support
625 extended file attributes.
626 .RE
627
628 .sp
629 .ne 2
630 .na
631 \fB\fBEIO\fR\fR
632 .ad
633 .RS 16n
634 The \fIpath\fR argument names a \fBSTREAMS\fR file and a hangup or error
635 occurred during the \fBopen()\fR.
636 .RE
637
638 .sp
639 .ne 2
640 .na
641 \fB\fBEISDIR\fR\fR
642 .ad
643 .RS 16n
644 The named file is a directory and \fIoflag\fR includes \fBO_WRONLY\fR or
645 \fBO_RDWR\fR.
646 .RE
647
648 .sp
649 .ne 2
650 .na
651 \fB\fBELOOP\fR\fR
652 .ad
653 .RS 16n
654 Too many symbolic links were encountered in resolving \fIpath\fR.
655 .sp
656 A loop exists in symbolic links encountered during resolution of the \fIpath\fR
657 argument.
658 .sp
659 The \fBO_NOFOLLOW\fR flag is set and the final component of path is a symbolic
660 link.
661 .RE
662
663 .sp
664 .ne 2
665 .na
666 \fB\fBEMFILE\fR\fR
667 .ad
668 .RS 16n
669 There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
670 process.
671 .RE
672
673 .sp
674 .ne 2
675 .na
676 \fB\fBEMLINK\fR\fR
677 .ad
678 .RS 16n
679 The \fBO_NOLINKS\fR flag is set and the named file has a link count greater
680 than 1.
681 .RE
682
683 .sp
684 .ne 2
685 .na
686 \fB\fBEMULTIHOP\fR\fR
687 .ad
688 .RS 16n
689 Components of \fIpath\fR require hopping to multiple remote machines and the
690 file system does not allow it.
691 .RE
692
693 .sp
694 .ne 2
695 .na
696 \fB\fBENAMETOOLONG\fR\fR
697 .ad
698 .RS 16n
699 The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR} or a pathname
700 component is longer than {\fBNAME_MAX\fR}.
701 .RE
702
703 .sp
704 .ne 2
705 .na
706 \fB\fBENFILE\fR\fR
707 .ad
708 .RS 16n
709 The maximum allowable number of files is currently open in the system.
710 .RE
711
712 .sp
713 .ne 2
714 .na
715 \fB\fBENOENT\fR\fR
716 .ad
717 .RS 16n
718 The \fBO_CREAT\fR flag is not set and the named file does not exist; or the
719 \fBO_CREAT\fR flag is set and either the path prefix does not exist or the
720 \fIpath\fR argument points to an empty string.
721 .sp
722 The
723 .B O_CREAT
724 and
725 .B O_DIRECTORY
726 flags were both set and
727 .I path
728 did not point to a file.
729 .RE
730
731 .sp
732 .ne 2
733 .na
734 .B ENOEXEC
735 .ad
736 .RS 16n
737 The \fBO_EXEC\fR flag is set and \fIpath\fR does not point to a regular
738 file.
739 .RE
740
741 .sp
742 .ne 2
743 .na
744 \fB\fBENOLINK\fR\fR
745 .ad
746 .RS 16n
747 The \fIpath\fR argument points to a remote machine, and the link to that
748 machine is no longer active.
749 .RE
750
751 .sp
752 .ne 2
753 .na
754 \fB\fBENOSR\fR\fR
755 .ad
756 .RS 16n
757 The \fIpath\fR argument names a STREAMS-based file and the system is unable to
758 allocate a STREAM.
759 .RE
760
761 .sp
762 .ne 2
763 .na
764 \fB\fBENOSPC\fR\fR
765 .ad
766 .RS 16n
767 The directory or file system that would contain the new file cannot be
768 expanded, the file does not exist, and \fBO_CREAT\fR is specified.
769 .RE
770
771 .sp
772 .ne 2
773 .na
774 \fB\fBENOSYS\fR\fR
775 .ad
776 .RS 16n
777 The device specified by \fIpath\fR does not support the open operation.
778 .RE
779
780 .sp
781 .ne 2
782 .na
783 \fB\fBENOTDIR\fR\fR
784 .ad
785 .RS 16n
786 A component of the path prefix is not a directory or a relative path was
787 supplied to \fBopenat()\fR, the \fBO_XATTR\fR flag was not supplied, and the
788 file descriptor does not refer to a directory. The \fBO_SEARCH\fR flag
789 was passed and \fIpath\fR does not refer to a directory.
790 .sp
791 The
792 .B O_DIRECTORY
793 flag was set and the file was not a directory.
794 .RE
795
796 .sp
797 .ne 2
798 .na
799 \fB\fBENXIO\fR\fR
800 .ad
801 .RS 16n
802 The \fBO_NONBLOCK\fR flag is set, the named file is a FIFO, the \fBO_WRONLY\fR
803 flag is set, and no process has the file open for reading; or the named file is
804 a character special or block special file and the device associated with this
805 special file does not exist or has been retired by the fault management
806 framework .
807 .RE
808
809 .sp
810 .ne 2
811 .na
812 \fB\fBEOPNOTSUPP\fR\fR
813 .ad
814 .RS 16n
815 An attempt was made to open a path that corresponds to a \fBAF_UNIX\fR socket.
816 .RE
817
818 .sp
819 .ne 2
820 .na
821 \fB\fBEOVERFLOW\fR\fR
822 .ad
823 .RS 16n
824 The named file is a regular file and either \fBO_LARGEFILE\fR is not set and
825 the size of the file cannot be represented correctly in an object of type
826 \fBoff_t\fR or \fBO_LARGEFILE\fR is set and the size of the file cannot be
827 represented correctly in an object of type \fBoff64_t\fR.
828 .RE
829
830 .sp
831 .ne 2
832 .na
833 \fB\fBEROFS\fR\fR
834 .ad
835 .RS 16n
836 The named file resides on a read-only file system and either \fBO_WRONLY\fR,
837 \fBO_RDWR\fR, \fBO_CREAT\fR (if file does not exist), or \fBO_TRUNC\fR is set
838 in the \fIoflag\fR argument.
839 .RE
840
841 .sp
842 .LP
843 The \fBopenat()\fR function will fail if:
844 .sp
845 .ne 2
846 .na
847 \fB\fBEBADF\fR\fR
848 .ad
849 .RS 9n
850 The \fIfildes\fR argument is not a valid open file descriptor or is not
851 \fBAT_FTCWD\fR.
852 .RE
853
854 .sp
855 .LP
856 The \fBopen()\fR function may fail if:
857 .sp
858 .ne 2
859 .na
860 \fB\fBEAGAIN\fR\fR
861 .ad
862 .RS 16n
863 The \fIpath\fR argument names the slave side of a pseudo-terminal device that
864 is locked.
865 .RE
866
867 .sp
868 .ne 2
869 .na
870 \fB\fBEINVAL\fR\fR
871 .ad
872 .RS 16n
873 The value of the \fIoflag\fR argument is not valid.
874 .RE
875
876 .sp
877 .ne 2
878 .na
879 \fB\fBENAMETOOLONG\fR\fR
880 .ad
881 .RS 16n
882 Pathname resolution of a symbolic link produced an intermediate result whose
883 length exceeds {\fBPATH_MAX\fR}.
884 .RE
885
886 .sp
887 .ne 2
888 .na
889 \fB\fBENOMEM\fR\fR
890 .ad
891 .RS 16n
892 The \fIpath\fR argument names a \fBSTREAMS\fR file and the system is unable to
893 allocate resources.
894 .RE
895
896 .sp
897 .ne 2
898 .na
899 \fB\fBETXTBSY\fR\fR
900 .ad
901 .RS 16n
902 The file is a pure procedure (shared text) file that is being executed and
903 \fIoflag\fR is \fBO_WRONLY\fR or \fBO_RDWR\fR.
904 .RE
905
906 .SH EXAMPLES
907 \fBExample 1 \fROpen a file for writing by the owner.
908 .sp
909 .LP
910 The following example opens the file \fB/tmp/file\fR, either by creating it if
911 it does not already exist, or by truncating its length to 0 if it does exist.
912 If the call creates a new file, the access permission bits in the file mode of
913 the file are set to permit reading and writing by the owner, and to permit
914 reading only by group members and others.
915
916 .sp
917 .LP
918 If the call to \fBopen()\fR is successful, the file is opened for writing.
919
920 .sp
921 .in +2
922 .nf
923 #include <fcntl.h>
924 \&...
925 int fd;
926 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
927 char *filename = "/tmp/file";
928 \&...
929 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
930 \&...
931 .fi
932 .in -2
933
934 .LP
935 \fBExample 2 \fROpen a file using an existence check.
936 .sp
937 .LP
938 The following example uses the \fBopen()\fR function to try to create the
939 \fBLOCKFILE\fR file and open it for writing. Since the \fBopen()\fR function
940 specifies the \fBO_EXCL\fR flag, the call fails if the file already exists. In
941 that case, the application assumes that someone else is updating the password
942 file and exits.
943
944 .sp
945 .in +2
946 .nf
947 #include <fcntl.h>
948 #include <stdio.h>
949 #include <stdlib.h>
950 #define LOCKFILE "/etc/ptmp"
951 \&...
952 int pfd; /* Integer for file descriptor returned by open() call. */
953 \&...
954 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
955 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
956 {
957 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en");
958 exit(1);
959 }
960 \&...
961 .fi
962 .in -2
963
964 .LP
965 \fBExample 3 \fROpen a file for writing.
966 .sp
967 .LP
968 The following example opens a file for writing, creating the file if it does
969 not already exist. If the file does exist, the system truncates the file to
970 zero bytes.
971
972 .sp
973 .in +2
974 .nf
975 #include <fcntl.h>
976 #include <stdio.h>
977 #include <stdlib.h>
978 #define LOCKFILE "/etc/ptmp"
979 \&...
980 int pfd;
981 char filename[PATH_MAX+1];
982 \&...
983 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
984 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
985 {
986 perror("Cannot open output file\en"); exit(1);
987 }
988 \&...
989 .fi
990 .in -2
991
992 .SH USAGE
993 The \fBopen()\fR function has a transitional interface for 64-bit file offsets.
994 See \fBlf64\fR(5). Note that using \fBopen64()\fR is equivalent to using
995 \fBopen()\fR with \fBO_LARGEFILE\fR set in \fIoflag\fR.
996 .SH ATTRIBUTES
997 See \fBattributes\fR(5) for descriptions of the following attributes:
998 .sp
999
1000 .sp
1001 .TS
1002 box;
1003 c | c
1004 l | l .
1005 ATTRIBUTE TYPE ATTRIBUTE VALUE
1006 _
1007 Interface Stability Committed
1008 _
1009 MT-Level Async-Signal-Safe
1010 _
1011 Standard For \fBopen()\fR, see \fBstandards\fR(5).
1012 .TE
1013
1014 .SH SEE ALSO
1015 \fBIntro\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
1016 \fBexec\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2), \fBgetrlimit\fR(2),
1017 \fBlseek\fR(2), \fBputmsg\fR(2), \fBread\fR(2), \fBstat\fR(2), \fBumask\fR(2),
1018 \fBwrite\fR(2), \fBattropen\fR(3C), \fBdirectio\fR(3C),
1019 \fBfcntl.h\fR(3HEAD), \fBstat.h\fR(3HEAD),
1020 \fBunlockpt\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBprivileges\fR(5),
1021 \fBstandards\fR(5), \fBconnld\fR(7M), \fBstreamio\fR(7I)
1022 .SH NOTES
1023 Hierarchical Storage Management (HSM) file systems can sometimes cause long
1024 delays when opening a file, since HSM files must be recalled from secondary
1025 storage.
|
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.
|