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