bsd/man/man2/fcntl.2

   1 .\"     $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
  35 .\"
  36 .Dd January 12, 1994
  37 .Dt FCNTL 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm fcntl
  41 .Nd file control
  42 .Sh SYNOPSIS
  43 .Fd #include <fcntl.h>
  44 .Ft int
  45 .Fn fcntl "int fd" "int cmd" "int arg"
  46 .Sh DESCRIPTION
  47 .Fn Fcntl
  48 provides for control over descriptors.
  49 The argument
  50 .Fa fd
  51 is a descriptor to be operated on by
  52 .Fa cmd
  53 as follows:
  54 .Bl -tag -width F_WRITEBOOTSTRAPX
  55 .It Dv F_DUPFD
  56 Return a new descriptor as follows:
  57 .Pp
  58 .Bl -bullet -compact -offset 4n
  59 .It
  60 Lowest numbered available descriptor greater than or equal to
  61 .Fa arg .
  62 .It
  63 Same object references as the original descriptor.
  64 .It
  65 New descriptor shares the same file offset if the object
  66 was a file.
  67 .It
  68 Same access mode (read, write or read/write).
  69 .It
  70 Same file status flags (i.e., both file descriptors
  71 share the same file status flags).
  72 .It
  73 The close-on-exec flag associated with the new file descriptor
  74 is set to remain open across
  75 .Xr execv 2
  76 system calls.
  77 .El
  78 .It Dv F_GETFD
  79 Get the close-on-exec flag associated with the file descriptor
  80 .Fa fd .
  81 If the low-order bit of the returned value is 0,
  82 the file will remain open across
  83 .Fn exec ,
  84 otherwise the file will be closed upon execution of
  85 .Fn exec
  86 .Fa ( arg
  87 is ignored).
  88 .It Dv F_SETFD
  89 Set the close-on-exec flag associated with
  90 .Fa fd
  91 to the low order bit of
  92 .Fa arg
  93 (0 or 1 as above).
  94 .It Dv F_GETFL
  95 Get descriptor status flags, as described below
  96 .Fa ( arg
  97 is ignored).
  98 .It Dv F_SETFL
  99 Set descriptor status flags to
 100 .Fa arg .
 101 .It Dv F_GETOWN
 102 Get the process ID or process group
 103 currently receiving
 104 .Dv SIGIO
 105 and
 106 .Dv SIGURG
 107 signals; process groups are returned
 108 as negative values
 109 .Fa ( arg
 110 is ignored).
 111 .It Dv F_SETOWN
 112 Set the process or process group
 113 to receive
 114 .Dv SIGIO
 115 and
 116 .Dv SIGURG
 117 signals;
 118 process groups are specified by supplying
 119 .Fa arg
 120 as negative, otherwise
 121 .Fa arg
 122 is interpreted as a process ID.
 123 .It Dv F_PREALLOCATE
 124 Preallocate file storage space.
 125 .It Dv F_SETSIZE
 126 Truncate a file without zeroing space.
 127 The calling process must have root privileges.
 128 .It Dv F_RDADVISE
 129 Issue an advisory read async with no copy to user.
 130 .It Dv F_RDAHEAD
 131 Turn read ahead off/on.
 132 A zero value in
 133 .Fa arg
 134 disables read ahead.
 135 A non-zero value in
 136 .Fa arg
 137 turns read ahead on.
 138 .It Dv F_READBOOTSTRAP
 139 Read bootstrap from disk.
 140 .It Dv F_WRITEBOOTSTRAP
 141 Write bootstrap on disk.
 142 The calling process must have root privileges.
 143 .It Dv F_NOCACHE
 144 Turns data caching off/on. A non-zero value in
 145 .Fa arg
 146 turns data caching off.
 147 A value of zero in
 148 .Fa arg
 149 turns data caching on.
 150 .It Dv F_LOG2PHYS
 151 Get disk device information.
 152 Currently this only includes the
 153 disk device address that corresponds
 154 to the current file offset.
 155 .It Dv F_FULLFSYNC
 156 Does the same thing as
 157 .Xr fsync 2
 158 then asks the drive to
 159 flush all buffered data to
 160 the permanent storage device
 161 .Fa ( arg
 162 is ignored).
 163 This is currently
 164 only implemented on HFS filesystems and
 165 the operation may take quite a while to
 166 complete.  Certain FireWire drives have
 167 also been known to ignore this request.
 168 .El
 169 .Pp
 170 The flags for the
 171 .Dv F_GETFL
 172 and
 173 .Dv F_SETFL
 174 commands are as follows:
 175 .Bl -tag -width O_NONBLOCKX -offset indent
 176 .It Dv O_NONBLOCK
 177 Non-blocking I/O; if no data is available to a
 178 .Xr read
 179 call, or if a
 180 .Xr write
 181 operation would block,
 182 the read or write call returns -1 with the error
 183 .Er EAGAIN .
 184 .It Dv O_APPEND
 185 Force each write to append at the end of file;
 186 corresponds to the
 187 .Dv O_APPEND
 188 flag of
 189 .Xr open 2 .
 190 .It Dv O_ASYNC
 191 Enable the
 192 .Dv SIGIO
 193 signal to be sent to the process group
 194 when I/O is possible, e.g.,
 195 upon availability of data to be read.
 196 .El
 197 .Pp
 198 Several commands are available for doing advisory file locking;
 199 they all operate on the following structure:
 200 .ne 7v
 201 .Bd -literal
 202         struct flock {
 203             off_t       l_start;    /* starting offset */
 204             off_t       l_len;      /* len = 0 means until end of file */
 205             pid_t       l_pid;      /* lock owner */
 206             short       l_type;     /* lock type: read/write, etc. */
 207             short       l_whence;   /* type of l_start */
 208         };
 209 .Ed
 210 .Pp
 211 The commands available for advisory record locking are as follows:
 212 .Bl -tag -width F_SETLKWX
 213 .It Dv F_GETLK
 214 Get the first lock that blocks the lock description pointed to by the
 215 third argument,
 216 .Fa arg ,
 217 taken as a pointer to a
 218 .Fa "struct flock"
 219 (see above).
 220 The information retrieved overwrites the information passed to
 221 .Nm fcntl
 222 in the
 223 .Fa flock
 224 structure.
 225 If no lock is found that would prevent this lock from being created,
 226 the structure is left unchanged by this function call except for the
 227 lock type which is set to
 228 .Dv F_UNLCK .
 229 .It Dv F_SETLK
 230 Set or clear a file segment lock according to the lock description
 231 pointed to by the third argument,
 232 .Fa arg ,
 233 taken as a pointer to a
 234 .Fa "struct flock"
 235 (see above).
 236 .Dv F_SETLK
 237 is used to establish shared (or read) locks
 238 .Dv (F_RDLCK)
 239 or exclusive (or write) locks,
 240 .Dv (F_WRLCK) ,
 241 as well as remove either type of lock
 242 .Dv (F_UNLCK) .
 243 If a shared or exclusive lock cannot be set,
 244 .Nm fcntl
 245 returns immediately with
 246 .Er EACCES .
 247 .It Dv F_SETLKW
 248 This command is the same as
 249 .Dv F_SETLK
 250 except that if a shared or exclusive lock is blocked by other locks,
 251 the process waits until the request can be satisfied.
 252 If a signal that is to be caught is received while
 253 .Nm fcntl
 254 is waiting for a region, the
 255 .Nm fcntl
 256 will be interrupted if the signal handler has not specified the
 257 .Dv SA_RESTART
 258 (see
 259 .Xr sigaction 2 ) .
 260 .El
 261 .Pp
 262 When a shared lock has been set on a segment of a file,
 263 other processes can set shared locks on that segment
 264 or a portion of it.
 265 A shared lock prevents any other process from setting an exclusive
 266 lock on any portion of the protected area.
 267 A request for a shared lock fails if the file descriptor was not
 268 opened with read access.
 269 .Pp
 270 An exclusive lock prevents any other process from setting a shared lock or
 271 an exclusive lock on any portion of the protected area.
 272 A request for an exclusive lock fails if the file was not
 273 opened with write access.
 274 .Pp
 275 The value of
 276 .Fa l_whence
 277 is
 278 .Dv SEEK_SET ,
 279 .Dv SEEK_CUR ,
 280 or
 281 .Dv SEEK_END
 282 to indicate that the relative offset,
 283 .Fa l_start
 284 bytes, will be measured from the start of the file,
 285 current position, or end of the file, respectively.
 286 The value of
 287 .Fa l_len
 288 is the number of consecutive bytes to be locked.
 289 If
 290 .Fa l_len
 291 is negative, the result is undefined.
 292 The
 293 .Fa l_pid
 294 field is only used with
 295 .Dv F_GETLK
 296 to return the process ID of the process holding a blocking lock.
 297 After a successful
 298 .Dv F_GETLK
 299 request, the value of
 300 .Fa l_whence
 301 is
 302 .Dv SEEK_SET .
 303 .Pp
 304 Locks may start and extend beyond the current end of a file,
 305 but may not start or extend before the beginning of the file.
 306 A lock is set to extend to the largest possible value of the
 307 file offset for that file if
 308 .Fa l_len
 309 is set to zero. If
 310 .Fa l_whence
 311 and
 312 .Fa l_start
 313 point to the beginning of the file, and
 314 .Fa l_len
 315 is zero, the entire file is locked.
 316 If an application wishes only to do entire file locking, the
 317 .Xr flock 2
 318 system call is much more efficient.
 319 .Pp
 320 There is at most one type of lock set for each byte in the file.
 321 Before a successful return from an
 322 .Dv F_SETLK
 323 or an
 324 .Dv F_SETLKW
 325 request when the calling process has previously existing locks
 326 on bytes in the region specified by the request,
 327 the previous lock type for each byte in the specified
 328 region is replaced by the new lock type.
 329 As specified above under the descriptions
 330 of shared locks and exclusive locks, an
 331 .Dv F_SETLK
 332 or an
 333 .Dv F_SETLKW
 334 request fails or blocks respectively when another process has existing
 335 locks on bytes in the specified region and the type of any of those
 336 locks conflicts with the type specified in the request.
 337 .Pp
 338 This interface follows the completely stupid semantics of System V and
 339 .St -p1003.1-88
 340 that require that all locks associated with a file for a given process are
 341 removed when \fIany\fP file descriptor for that file is closed by that process.
 342 This semantic means that applications must be aware of any files that
 343 a subroutine library may access.
 344 For example if an application for updating the password file locks the
 345 password file database while making the update, and then calls
 346 .Xr getpwname 3
 347 to retrieve a record,
 348 the lock will be lost because
 349 .Xr getpwname 3
 350 opens, reads, and closes the password database.
 351 The database close will release all locks that the process has
 352 associated with the database, even if the library routine never
 353 requested a lock on the database.
 354 Another minor semantic problem with this interface is that
 355 locks are not inherited by a child process created using the
 356 .Xr fork 2
 357 function.
 358 The
 359 .Xr flock 2
 360 interface has much more rational last close semantics and
 361 allows locks to be inherited by child processes.
 362 .Xr Flock 2
 363 is recommended for applications that want to ensure the integrity
 364 of their locks when using library routines or wish to pass locks
 365 to their children.
 366 Note that
 367 .Xr flock 2
 368 and
 369 .Xr fcntl 2
 370 locks may be safely used concurrently.
 371 .Pp
 372 All locks associated with a file for a given process are
 373 removed when the process terminates.
 374 .Pp
 375 A potential for deadlock occurs if a process controlling a locked region
 376 is put to sleep by attempting to lock the locked region of another process.
 377 This implementation detects that sleeping until a locked region is unlocked
 378 would cause a deadlock and fails with an
 379 .Er EDEADLK
 380 error.
 381 .Pp
 382 The
 383 .Dv F_PREALLOCATE
 384 command operates on the following structure:
 385 .ne 7v
 386 .Bd -literal
 387         typedef struct fstore {
 388             u_int32_t fst_flags;      /* IN: flags word */
 389             int       fst_posmode;    /* IN: indicates offset field */
 390             off_t     fst_offset;     /* IN: start of the region */
 391             off_t     fst_length;     /* IN: size of the region */
 392             off_t     fst_bytesalloc; /* OUT: number of bytes allocated */
 393         } fstore_t;
 394 .Ed
 395 .Pp
 396 The flags (fst_flags) for the
 397 .Dv F_PREALLOCATE
 398 command are as follows:
 399 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
 400 .It Dv F_ALLOCATECONTIG
 401 Allocate contiguous space.
 402 .It Dv F_ALLOCATEALL
 403 Allocate all requested space or no space at all.
 404 .El
 405 .Pp
 406 The position modes (fst_posmode) for the
 407 .Dv F_PREALLOCATE
 408 command indicate how to use the offset field.
 409 The modes are as follows:
 410 .Bl -tag -width F_PEOFPOSMODEX -offset indent
 411 .It Dv F_PEOFPOSMODE
 412 Allocate from the physical end of file.
 413 .It Dv F_VOLPOSMODE
 414 Allocate from the volume offset.
 415 .El
 416 .Pp
 417 The
 418 .Dv F_RDADVISE
 419 command operates on the following structure
 420 which holds information passed from the
 421 user to the system:
 422 .ne 7v
 423 .Bd -literal
 424         struct radvisory {
 425            off_t   ra_offset;  /* offset into the file */
 426            int     ra_count;   /* size of the read     */
 427         };
 428 .Ed
 429 .Pp
 430 The
 431 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
 432 commands operate on the following structure.
 433 .ne 7v
 434 .Bd -literal
 435         typedef struct fbootstraptransfer {
 436             off_t fbt_offset;       /* IN: offset to start read/write */
 437             size_t fbt_length;      /* IN: number of bytes to transfer */
 438             void *fbt_buffer;       /* IN: buffer to be read/written */
 439         } fbootstraptransfer_t;
 440 .Ed
 441 .Pp
 442 The
 443 .Dv F_LOG2PHYS
 444 command operates on the following structure.
 445 .ne 7v
 446 .Bd -literal
 447         struct log2phys {
 448             u_int32_t   l2p_flags;              /* unused so far */
 449             off_t       l2p_contigbytes;        /* unused so far */
 450             off_t       l2p_devoffset;      /* bytes into device */
 451         };
 452 .Ed
 453 .Sh RETURN VALUES
 454 Upon successful completion, the value returned depends on
 455 .Fa cmd
 456 as follows:
 457 .Bl -tag -width F_GETOWNX -offset indent
 458 .It Dv F_DUPFD
 459 A new file descriptor.
 460 .It Dv F_GETFD
 461 Value of flag (only the low-order bit is defined).
 462 .It Dv F_GETFL
 463 Value of flags.
 464 .It Dv F_GETOWN
 465 Value of file descriptor owner.
 466 .It other
 467 Value other than -1.
 468 .El
 469 .Pp
 470 Otherwise, a value of -1 is returned and
 471 .Va errno
 472 is set to indicate the error.
 473 .Sh ERRORS
 474 .Fn Fcntl
 475 will fail if:
 476 .Bl -tag -width Er
 477 .It Bq Er EACCES
 478 The argument
 479 .Fa cmd
 480 is
 481 .Dv F_SETLK ,
 482 the type of lock
 483 .Fa (l_type)
 484 is a shared lock
 485 .Dv (F_RDLCK)
 486 or exclusive lock
 487 .Dv (F_WRLCK) ,
 488 and the segment of a file to be locked is already
 489 exclusive-locked by another process;
 490 or the type is an exclusive lock and some portion of the
 491 segment of a file to be locked is already shared-locked or
 492 exclusive-locked by another process.
 493 .Pp
 494 The argument
 495 .Fa cmd
 496 is either
 497 .Dv F_SETSIZE
 498 or
 499 .Dv F_WRITEBOOTSTRAP
 500 and the calling process does not have root privileges.
 501 .It Bq Er EBADF
 502 .Fa Fildes
 503 is not a valid open file descriptor.
 504 .Pp
 505 The argument
 506 .Fa cmd
 507 is
 508 .Dv F_SETLK
 509 or
 510 .Dv F_SETLKW ,
 511 the type of lock
 512 .Fa (l_type)
 513 is a shared lock
 514 .Dv (F_RDLCK) ,
 515 and
 516 .Fa fildes
 517 is not a valid file descriptor open for reading.
 518 .Pp
 519 The argument
 520 .Fa cmd
 521 is
 522 .Dv F_SETLK
 523 or
 524 .Dv F_SETLKW ,
 525 the type of lock
 526 .Fa (l_type)
 527 is an exclusive lock
 528 .Dv (F_WRLCK) ,
 529 and
 530 .Fa fildes
 531 is not a valid file descriptor open for writing.
 532 .Pp
 533 The argument
 534 .Fa cmd
 535 is
 536 .Dv F_PREALLOCATE
 537 and the calling process does not have
 538 file write permission.
 539 .Pp
 540 The argument
 541 .Fa cmd
 542 is
 543 .Dv F_LOG2PHYS
 544 and
 545 .Fa fildes
 546 is not a valid file descriptor open for reading.
 547 .It Bq Er EMFILE
 548 .Fa Cmd
 549 is
 550 .Dv F_DUPFD
 551 and the maximum allowed number of file descriptors are currently
 552 open.
 553 .It Bq Er EDEADLK
 554 The argument
 555 .Fa cmd
 556 is
 557 .Dv F_SETLKW ,
 558 and a deadlock condition was detected.
 559 .It Bq Er EINTR
 560 The argument
 561 .Fa cmd
 562 is
 563 .Dv F_SETLKW ,
 564 and the function was interrupted by a signal.
 565 .It Bq Er EINVAL
 566 .Fa Cmd
 567 is
 568 .Dv F_DUPFD
 569 and
 570 .Fa arg
 571 is negative or greater than the maximum allowable number
 572 (see
 573 .Xr getdtablesize 2 ) .
 574 .Pp
 575 The argument
 576 .Fa cmd
 577 is
 578 .Dv F_GETLK ,
 579 .Dv F_SETLK ,
 580 or
 581 .Dv F_SETLKW
 582 and the data to which
 583 .Fa arg
 584 points is not valid, or
 585 .Fa fildes
 586 refers to a file that does not support locking.
 587 .Pp
 588 The argument
 589 .Fa cmd
 590 is
 591 .Dv F_PREALLOCATE
 592 and the
 593 .Fa fst_posmode
 594 is not a valid mode,
 595 or when
 596 .Dv F_PEOFPOSMODE
 597 is set and
 598 .Fa fst_offset
 599 is a non-zero value,
 600 or when
 601 .Dv F_VOLPOSMODE
 602 is set and
 603 .Fa fst_offset
 604 is a negative or zero value.
 605 .Pp
 606 The argument
 607 .Fa cmd
 608 is either
 609 .Dv F_READBOOTSTRAP
 610 or
 611 .Dv F_WRITEBOOTSTRAP
 612 and the operation was attempted on a non-HFS disk type.
 613 .It Bq Er EMFILE
 614 The argument
 615 .Fa cmd
 616 is
 617 .Dv F_DUPED
 618 and the maximum number of file descriptors permitted for the
 619 process are already in use,
 620 or no file descriptors greater than or equal to
 621 .Fa arg
 622 are available.
 623 .It Bq Er ENOLCK
 624 The argument
 625 .Fa cmd
 626 is
 627 .Dv F_SETLK
 628 or
 629 .Dv F_SETLKW ,
 630 and satisfying the lock or unlock request would result in the
 631 number of locked regions in the system exceeding a system-imposed limit.
 632 .It Bq Er ESRCH
 633 .Fa Cmd
 634 is
 635 .Dv F_SETOWN
 636 and
 637 the process ID given as argument is not in use.
 638 .El
 639 .Sh SEE ALSO
 640 .Xr close 2 ,
 641 .Xr execve 2 ,
 642 .Xr flock 2 ,
 643 .Xr getdtablesize 2 ,
 644 .Xr open 2 ,
 645 .Xr sigaction 3
 646 .Sh HISTORY
 647 The
 648 .Fn fcntl
 649 function call appeared in
 650 .Bx 4.2 .