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