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