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