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