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