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