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