bsd/man/man2/fcntl.2

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