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 .\"
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.