lib/libc/sys/fcntl.2

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd December 7, 2021
  29 .Dt FCNTL 2
  30 .Os
  31 .Sh NAME
  32 .Nm fcntl
  33 .Nd file control
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In fcntl.h
  38 .Ft int
  39 .Fn fcntl "int fd" "int cmd" "..."
  40 .Sh DESCRIPTION
  41 The
  42 .Fn fcntl
  43 system call provides for control over descriptors.
  44 The argument
  45 .Fa fd
  46 is a descriptor to be operated on by
  47 .Fa cmd
  48 as described below.
  49 Depending on the value of
  50 .Fa cmd ,
  51 .Fn fcntl
  52 can take an additional third argument
  53 .Fa arg .
  54 Unless otherwise noted below for a specific operation,
  55 .Fa arg
  56 has type
  57 .Vt int .
  58 .Bl -tag -width F_DUP2FD_CLOEXEC
  59 .It Dv F_DUPFD
  60 Return a new descriptor as follows:
  61 .Pp
  62 .Bl -bullet -compact -offset 4n
  63 .It
  64 Lowest numbered available descriptor greater than or equal to
  65 .Fa arg .
  66 .It
  67 Same object references as the original descriptor.
  68 .It
  69 New descriptor shares the same file offset if the object
  70 was a file.
  71 .It
  72 Same access mode (read, write or read/write).
  73 .It
  74 Same file status flags (i.e., both file descriptors
  75 share the same file status flags).
  76 .It
  77 The close-on-exec flag
  78 .Dv FD_CLOEXEC
  79 associated with the new file descriptor is cleared, so the file descriptor is
  80 to remain open across
  81 .Xr execve 2
  82 system calls.
  83 .El
  84 .It Dv F_DUPFD_CLOEXEC
  85 Like
  86 .Dv F_DUPFD ,
  87 but the
  88 .Dv FD_CLOEXEC
  89 flag associated with the new file descriptor is set, so the file descriptor
  90 is closed when
  91 .Xr execve 2
  92 system call executes.
  93 .It Dv F_DUP2FD
  94 It is functionally equivalent to
  95 .Bd -literal -offset indent
  96 dup2(fd, arg)
  97 .Ed
  98 .It Dv F_DUP2FD_CLOEXEC
  99 Like
 100 .Dv F_DUP2FD ,
 101 but the
 102 .Dv FD_CLOEXEC
 103 flag associated with the new file descriptor is set.
 104 .Pp
 105 The
 106 .Dv F_DUP2FD
 107 and
 108 .Dv F_DUP2FD_CLOEXEC
 109 constants are not portable, so they should not be used if
 110 portability is needed.
 111 Use
 112 .Fn dup2
 113 instead of
 114 .Dv F_DUP2FD .
 115 .It Dv F_GETFD
 116 Get the close-on-exec flag associated with the file descriptor
 117 .Fa fd
 118 as
 119 .Dv FD_CLOEXEC .
 120 If the returned value ANDed with
 121 .Dv FD_CLOEXEC
 122 is 0,
 123 the file will remain open across
 124 .Fn exec ,
 125 otherwise the file will be closed upon execution of
 126 .Fn exec
 127 .Fa ( arg
 128 is ignored).
 129 .It Dv F_SETFD
 130 Set the close-on-exec flag associated with
 131 .Fa fd
 132 to
 133 .Fa arg ,
 134 where
 135 .Fa arg
 136 is either 0 or
 137 .Dv FD_CLOEXEC ,
 138 as described above.
 139 .It Dv F_GETFL
 140 Get descriptor status flags, as described below
 141 .Fa ( arg
 142 is ignored).
 143 .It Dv F_SETFL
 144 Set descriptor status flags to
 145 .Fa arg .
 146 .It Dv F_GETOWN
 147 Get the process ID or process group
 148 currently receiving
 149 .Dv SIGIO
 150 and
 151 .Dv SIGURG
 152 signals; process groups are returned
 153 as negative values
 154 .Fa ( arg
 155 is ignored).
 156 .It Dv F_SETOWN
 157 Set the process or process group
 158 to receive
 159 .Dv SIGIO
 160 and
 161 .Dv SIGURG
 162 signals;
 163 process groups are specified by supplying
 164 .Fa arg
 165 as negative, otherwise
 166 .Fa arg
 167 is interpreted as a process ID.
 168 .It Dv F_READAHEAD
 169 Set or clear the read ahead amount for sequential access to the third
 170 argument,
 171 .Fa arg ,
 172 which is rounded up to the nearest block size.
 173 A zero value in
 174 .Fa arg
 175 turns off read ahead, a negative value restores the system default.
 176 .It Dv F_RDAHEAD
 177 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
 178 when the third argument,
 179 .Fa arg
 180 is non-zero.
 181 A zero value in
 182 .Fa arg
 183 turns off read ahead.
 184 .It Dv F_ADD_SEALS
 185 Add seals to the file as described below, if the underlying filesystem supports
 186 seals.
 187 .It Dv F_GET_SEALS
 188 Get seals associated with the file, if the underlying filesystem supports seals.
 189 .It Dv F_ISUNIONSTACK
 190 Check if the vnode is part of a union stack (either the "union" flag from
 191 .Xr mount 2
 192 or unionfs).
 193 This is a hack not intended to be used outside of libc.
 194 .It Dv F_KINFO
 195 Fills a
 196 .Vt struct kinfo_file
 197 for the file referenced by the specified file descriptor.
 198 The
 199 .Fa arg
 200 argument should point to the storage for
 201 .Vt struct kinfo_file .
 202 The
 203 .Va kf_structsize
 204 member of the passed structure must be initialized with the sizeof of
 205 .Vt struct kinfo_file ,
 206 to allow for the interface versioning and evolution.
 207 .El
 208 .Pp
 209 The flags for the
 210 .Dv F_GETFL
 211 and
 212 .Dv F_SETFL
 213 commands are as follows:
 214 .Bl -tag -width O_NONBLOCKX
 215 .It Dv O_NONBLOCK
 216 Non-blocking I/O; if no data is available to a
 217 .Xr read 2
 218 system call, or if a
 219 .Xr write 2
 220 operation would block,
 221 the read or write call returns -1 with the error
 222 .Er EAGAIN .
 223 .It Dv O_APPEND
 224 Force each write to append at the end of file;
 225 corresponds to the
 226 .Dv O_APPEND
 227 flag of
 228 .Xr open 2 .
 229 .It Dv O_DIRECT
 230 Minimize or eliminate the cache effects of reading and writing.
 231 The system
 232 will attempt to avoid caching the data you read or write.
 233 If it cannot
 234 avoid caching the data, it will minimize the impact the data has on the cache.
 235 Use of this flag can drastically reduce performance if not used with care.
 236 .It Dv O_ASYNC
 237 Enable the
 238 .Dv SIGIO
 239 signal to be sent to the process group
 240 when I/O is possible, e.g.,
 241 upon availability of data to be read.
 242 .It Dv O_SYNC
 243 Enable synchronous writes.
 244 Corresponds to the
 245 .Dv O_SYNC
 246 flag of
 247 .Xr open 2 .
 248 .Dv O_FSYNC
 249 is an historical synonym for
 250 .Dv O_SYNC .
 251 .It Dv O_DSYNC
 252 Enable synchronous data writes.
 253 Corresponds to the
 254 .Dv O_DSYNC
 255 flag of
 256 .Xr open 2 .
 257 .El
 258 .Pp
 259 The seals that may be applied with
 260 .Dv F_ADD_SEALS
 261 are as follows:
 262 .Bl -tag -width F_SEAL_SHRINK
 263 .It Dv F_SEAL_SEAL
 264 Prevent any further seals from being applied to the file.
 265 .It Dv F_SEAL_SHRINK
 266 Prevent the file from being shrunk with
 267 .Xr ftruncate 2 .
 268 .It Dv F_SEAL_GROW
 269 Prevent the file from being enlarged with
 270 .Xr ftruncate 2 .
 271 .It Dv F_SEAL_WRITE
 272 Prevent any further
 273 .Xr write 2
 274 calls to the file.
 275 Any writes in progress will finish before
 276 .Fn fcntl
 277 returns.
 278 If any writeable mappings exist, F_ADD_SEALS will fail and return
 279 .Dv EBUSY .
 280 .El
 281 .Pp
 282 Seals are on a per-inode basis and require support by the underlying filesystem.
 283 If the underlying filesystem does not support seals,
 284 .Dv F_ADD_SEALS
 285 and
 286 .Dv F_GET_SEALS
 287 will fail and return
 288 .Dv EINVAL .
 289 .Pp
 290 Several operations are available for doing advisory file locking;
 291 they all operate on the following structure:
 292 .Bd -literal
 293 struct flock {
 294         off_t   l_start;        /* starting offset */
 295         off_t   l_len;          /* len = 0 means until end of file */
 296         pid_t   l_pid;          /* lock owner */
 297         short   l_type;         /* lock type: read/write, etc. */
 298         short   l_whence;       /* type of l_start */
 299         int     l_sysid;        /* remote system id or zero for local */
 300 };
 301 .Ed
 302 These advisory file locking operations take a pointer to
 303 .Vt struct flock
 304 as the third argument
 305 .Fa arg .
 306 The commands available for advisory record locking are as follows:
 307 .Bl -tag -width F_SETLKWX
 308 .It Dv F_GETLK
 309 Get the first lock that blocks the lock description pointed to by the
 310 third argument,
 311 .Fa arg ,
 312 taken as a pointer to a
 313 .Fa "struct flock"
 314 (see above).
 315 The information retrieved overwrites the information passed to
 316 .Fn fcntl
 317 in the
 318 .Fa flock
 319 structure.
 320 If no lock is found that would prevent this lock from being created,
 321 the structure is left unchanged by this system call except for the
 322 lock type which is set to
 323 .Dv F_UNLCK .
 324 .It Dv F_SETLK
 325 Set or clear a file segment lock according to the lock description
 326 pointed to by the third argument,
 327 .Fa arg ,
 328 taken as a pointer to a
 329 .Fa "struct flock"
 330 (see above).
 331 .Dv F_SETLK
 332 is used to establish shared (or read) locks
 333 .Pq Dv F_RDLCK
 334 or exclusive (or write) locks,
 335 .Pq Dv F_WRLCK ,
 336 as well as remove either type of lock
 337 .Pq Dv F_UNLCK .
 338 If a shared or exclusive lock cannot be set,
 339 .Fn fcntl
 340 returns immediately with
 341 .Er EAGAIN .
 342 .It Dv F_SETLKW
 343 This command is the same as
 344 .Dv F_SETLK
 345 except that if a shared or exclusive lock is blocked by other locks,
 346 the process waits until the request can be satisfied.
 347 If a signal that is to be caught is received while
 348 .Fn fcntl
 349 is waiting for a region, the
 350 .Fn fcntl
 351 will be interrupted if the signal handler has not specified the
 352 .Dv SA_RESTART
 353 (see
 354 .Xr sigaction 2 ) .
 355 .El
 356 .Pp
 357 When a shared lock has been set on a segment of a file,
 358 other processes can set shared locks on that segment
 359 or a portion of it.
 360 A shared lock prevents any other process from setting an exclusive
 361 lock on any portion of the protected area.
 362 A request for a shared lock fails if the file descriptor was not
 363 opened with read access.
 364 .Pp
 365 An exclusive lock prevents any other process from setting a shared lock or
 366 an exclusive lock on any portion of the protected area.
 367 A request for an exclusive lock fails if the file was not
 368 opened with write access.
 369 .Pp
 370 The value of
 371 .Fa l_whence
 372 is
 373 .Dv SEEK_SET ,
 374 .Dv SEEK_CUR ,
 375 or
 376 .Dv SEEK_END
 377 to indicate that the relative offset,
 378 .Fa l_start
 379 bytes, will be measured from the start of the file,
 380 current position, or end of the file, respectively.
 381 The value of
 382 .Fa l_len
 383 is the number of consecutive bytes to be locked.
 384 If
 385 .Fa l_len
 386 is negative,
 387 .Fa l_start
 388 means end edge of the region.
 389 The
 390 .Fa l_pid
 391 and
 392 .Fa l_sysid
 393 fields are only used with
 394 .Dv F_GETLK
 395 to return the process ID of the process holding a blocking lock and
 396 the system ID of the system that owns that process.
 397 Locks created by the local system will have a system ID of zero.
 398 After a successful
 399 .Dv F_GETLK
 400 request, the value of
 401 .Fa l_whence
 402 is
 403 .Dv SEEK_SET .
 404 .Pp
 405 Locks may start and extend beyond the current end of a file,
 406 but may not start or extend before the beginning of the file.
 407 A lock is set to extend to the largest possible value of the
 408 file offset for that file if
 409 .Fa l_len
 410 is set to zero.
 411 If
 412 .Fa l_whence
 413 and
 414 .Fa l_start
 415 point to the beginning of the file, and
 416 .Fa l_len
 417 is zero, the entire file is locked.
 418 If an application wishes only to do entire file locking, the
 419 .Xr flock 2
 420 system call is much more efficient.
 421 .Pp
 422 There is at most one type of lock set for each byte in the file.
 423 Before a successful return from an
 424 .Dv F_SETLK
 425 or an
 426 .Dv F_SETLKW
 427 request when the calling process has previously existing locks
 428 on bytes in the region specified by the request,
 429 the previous lock type for each byte in the specified
 430 region is replaced by the new lock type.
 431 As specified above under the descriptions
 432 of shared locks and exclusive locks, an
 433 .Dv F_SETLK
 434 or an
 435 .Dv F_SETLKW
 436 request fails or blocks respectively when another process has existing
 437 locks on bytes in the specified region and the type of any of those
 438 locks conflicts with the type specified in the request.
 439 .Pp
 440 The queuing for
 441 .Dv F_SETLKW
 442 requests on local files is fair;
 443 that is, while the thread is blocked,
 444 subsequent requests conflicting with its requests will not be granted,
 445 even if these requests do not conflict with existing locks.
 446 .Pp
 447 This interface follows the completely stupid semantics of System V and
 448 .St -p1003.1-88
 449 that require that all locks associated with a file for a given process are
 450 removed when
 451 .Em any
 452 file descriptor for that file is closed by that process.
 453 This semantic means that applications must be aware of any files that
 454 a subroutine library may access.
 455 For example if an application for updating the password file locks the
 456 password file database while making the update, and then calls
 457 .Xr getpwnam 3
 458 to retrieve a record,
 459 the lock will be lost because
 460 .Xr getpwnam 3
 461 opens, reads, and closes the password database.
 462 The database close will release all locks that the process has
 463 associated with the database, even if the library routine never
 464 requested a lock on the database.
 465 Another minor semantic problem with this interface is that
 466 locks are not inherited by a child process created using the
 467 .Xr fork 2
 468 system call.
 469 The
 470 .Xr flock 2
 471 interface has much more rational last close semantics and
 472 allows locks to be inherited by child processes.
 473 The
 474 .Xr flock 2
 475 system call is recommended for applications that want to ensure the integrity
 476 of their locks when using library routines or wish to pass locks
 477 to their children.
 478 .Pp
 479 The
 480 .Fn fcntl ,
 481 .Xr flock 2 ,
 482 and
 483 .Xr lockf 3
 484 locks are compatible.
 485 Processes using different locking interfaces can cooperate
 486 over the same file safely.
 487 However, only one of such interfaces should be used within
 488 the same process.
 489 If a file is locked by a process through
 490 .Xr flock 2 ,
 491 any record within the file will be seen as locked
 492 from the viewpoint of another process using
 493 .Fn fcntl
 494 or
 495 .Xr lockf 3 ,
 496 and vice versa.
 497 Note that
 498 .Fn fcntl F_GETLK
 499 returns \-1 in
 500 .Fa l_pid
 501 if the process holding a blocking lock previously locked the
 502 file descriptor by
 503 .Xr flock 2 .
 504 .Pp
 505 All locks associated with a file for a given process are
 506 removed when the process terminates.
 507 .Pp
 508 All locks obtained before a call to
 509 .Xr execve 2
 510 remain in effect until the new program releases them.
 511 If the new program does not know about the locks, they will not be
 512 released until the program exits.
 513 .Pp
 514 A potential for deadlock occurs if a process controlling a locked region
 515 is put to sleep by attempting to lock the locked region of another process.
 516 This implementation detects that sleeping until a locked region is unlocked
 517 would cause a deadlock and fails with an
 518 .Er EDEADLK
 519 error.
 520 .Sh RETURN VALUES
 521 Upon successful completion, the value returned depends on
 522 .Fa cmd
 523 as follows:
 524 .Bl -tag -width F_GETOWNX -offset indent
 525 .It Dv F_DUPFD
 526 A new file descriptor.
 527 .It Dv F_DUP2FD
 528 A file descriptor equal to
 529 .Fa arg .
 530 .It Dv F_GETFD
 531 Value of flag (only the low-order bit is defined).
 532 .It Dv F_GETFL
 533 Value of flags.
 534 .It Dv F_GETOWN
 535 Value of file descriptor owner.
 536 .It other
 537 Value other than -1.
 538 .El
 539 .Pp
 540 Otherwise, a value of -1 is returned and
 541 .Va errno
 542 is set to indicate the error.
 543 .Sh ERRORS
 544 The
 545 .Fn fcntl
 546 system call will fail if:
 547 .Bl -tag -width Er
 548 .It Bq Er EAGAIN
 549 The argument
 550 .Fa cmd
 551 is
 552 .Dv F_SETLK ,
 553 the type of lock
 554 .Pq Fa l_type
 555 is a shared lock
 556 .Pq Dv F_RDLCK
 557 or exclusive lock
 558 .Pq Dv F_WRLCK ,
 559 and the segment of a file to be locked is already
 560 exclusive-locked by another process;
 561 or the type is an exclusive lock and some portion of the
 562 segment of a file to be locked is already shared-locked or
 563 exclusive-locked by another process.
 564 .It Bq Er EBADF
 565 The
 566 .Fa fd
 567 argument
 568 is not a valid open file descriptor.
 569 .Pp
 570 The argument
 571 .Fa cmd
 572 is
 573 .Dv F_DUP2FD ,
 574 and
 575 .Fa arg
 576 is not a valid file descriptor.
 577 .Pp
 578 The argument
 579 .Fa cmd
 580 is
 581 .Dv F_SETLK
 582 or
 583 .Dv F_SETLKW ,
 584 the type of lock
 585 .Pq Fa l_type
 586 is a shared lock
 587 .Pq Dv F_RDLCK ,
 588 and
 589 .Fa fd
 590 is not a valid file descriptor open for reading.
 591 .Pp
 592 The argument
 593 .Fa cmd
 594 is
 595 .Dv F_SETLK
 596 or
 597 .Dv F_SETLKW ,
 598 the type of lock
 599 .Pq Fa l_type
 600 is an exclusive lock
 601 .Pq Dv F_WRLCK ,
 602 and
 603 .Fa fd
 604 is not a valid file descriptor open for writing.
 605 .It Bq Er EBUSY
 606 The argument
 607 .Fa cmd
 608 is
 609 .Dv F_ADD_SEALS ,
 610 attempting to set
 611 .Dv F_SEAL_WRITE ,
 612 and writeable mappings of the file exist.
 613 .It Bq Er EDEADLK
 614 The argument
 615 .Fa cmd
 616 is
 617 .Dv F_SETLKW ,
 618 and a deadlock condition was detected.
 619 .It Bq Er EINTR
 620 The argument
 621 .Fa cmd
 622 is
 623 .Dv F_SETLKW ,
 624 and the system call was interrupted by a signal.
 625 .It Bq Er EINVAL
 626 The
 627 .Fa cmd
 628 argument
 629 is
 630 .Dv F_DUPFD
 631 and
 632 .Fa arg
 633 is negative or greater than the maximum allowable number
 634 (see
 635 .Xr getdtablesize 2 ) .
 636 .Pp
 637 The argument
 638 .Fa cmd
 639 is
 640 .Dv F_GETLK ,
 641 .Dv F_SETLK
 642 or
 643 .Dv F_SETLKW
 644 and the data to which
 645 .Fa arg
 646 points is not valid.
 647 .Pp
 648 The argument
 649 .Fa cmd
 650 is
 651 .Dv F_ADD_SEALS
 652 or
 653 .Dv F_GET_SEALS ,
 654 and the underlying filesystem does not support sealing.
 655 .Pp
 656 The argument
 657 .Fa cmd
 658 is invalid.
 659 .It Bq Er EMFILE
 660 The argument
 661 .Fa cmd
 662 is
 663 .Dv F_DUPFD
 664 and the maximum number of file descriptors permitted for the
 665 process are already in use,
 666 or no file descriptors greater than or equal to
 667 .Fa arg
 668 are available.
 669 .It Bq Er ENOTTY
 670 The
 671 .Fa fd
 672 argument is not a valid file descriptor for the requested operation.
 673 This may be the case if
 674 .Fa fd
 675 is a device node, or a descriptor returned by
 676 .Xr kqueue 2 .
 677 .It Bq Er ENOLCK
 678 The argument
 679 .Fa cmd
 680 is
 681 .Dv F_SETLK
 682 or
 683 .Dv F_SETLKW ,
 684 and satisfying the lock or unlock request would result in the
 685 number of locked regions in the system exceeding a system-imposed limit.
 686 .It Bq Er EOPNOTSUPP
 687 The argument
 688 .Fa cmd
 689 is
 690 .Dv F_GETLK ,
 691 .Dv F_SETLK
 692 or
 693 .Dv F_SETLKW
 694 and
 695 .Fa fd
 696 refers to a file for which locking is not supported.
 697 .It Bq Er EOVERFLOW
 698 The argument
 699 .Fa cmd
 700 is
 701 .Dv F_GETLK ,
 702 .Dv F_SETLK
 703 or
 704 .Dv F_SETLKW
 705 and an
 706 .Fa off_t
 707 calculation overflowed.
 708 .It Bq Er EPERM
 709 The
 710 .Fa cmd
 711 argument
 712 is
 713 .Dv F_SETOWN
 714 and
 715 the process ID or process group given as an argument is in a
 716 different session than the caller.
 717 .Pp
 718 The
 719 .Fa cmd
 720 argument
 721 is
 722 .Dv F_ADD_SEALS
 723 and the
 724 .Dv F_SEAL_SEAL
 725 seal has already been set.
 726 .It Bq Er ESRCH
 727 The
 728 .Fa cmd
 729 argument
 730 is
 731 .Dv F_SETOWN
 732 and
 733 the process ID given as argument is not in use.
 734 .El
 735 .Pp
 736 In addition, if
 737 .Fa fd
 738 refers to a descriptor open on a terminal device (as opposed to a
 739 descriptor open on a socket), a
 740 .Fa cmd
 741 of
 742 .Dv F_SETOWN
 743 can fail for the same reasons as in
 744 .Xr tcsetpgrp 3 ,
 745 and a
 746 .Fa cmd
 747 of
 748 .Dv F_GETOWN
 749 for the reasons as stated in
 750 .Xr tcgetpgrp 3 .
 751 .Sh SEE ALSO
 752 .Xr close 2 ,
 753 .Xr dup2 2 ,
 754 .Xr execve 2 ,
 755 .Xr flock 2 ,
 756 .Xr getdtablesize 2 ,
 757 .Xr open 2 ,
 758 .Xr sigaction 2 ,
 759 .Xr lockf 3 ,
 760 .Xr tcgetpgrp 3 ,
 761 .Xr tcsetpgrp 3
 762 .Sh STANDARDS
 763 The
 764 .Dv F_DUP2FD
 765 constant is non portable.
 766 It is provided for compatibility with AIX and Solaris.
 767 .Pp
 768 Per
 769 .St -susv4 ,
 770 a call with
 771 .Dv F_SETLKW
 772 should fail with
 773 .Bq Er EINTR
 774 after any caught signal
 775 and should continue waiting during thread suspension such as a stop signal.
 776 However, in this implementation a call with
 777 .Dv F_SETLKW
 778 is restarted after catching a signal with a
 779 .Dv SA_RESTART
 780 handler or a thread suspension such as a stop signal.
 781 .Sh HISTORY
 782 The
 783 .Fn fcntl
 784 system call appeared in
 785 .Bx 4.2 .
 786 .Pp
 787 The
 788 .Dv F_DUP2FD
 789 constant first appeared in
 790 .Fx 7.1 .