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