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: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $ 30.\" 31.Dd March 30, 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 ".Dv 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_GETPATH 168Get the filesystem path associated with 169.Fa fd . 170At most 171.Dv MAXPATHLEN 172bytes will be written to the buffer provided in 173.Fa arg . 174.El 175.Pp 176The flags for the 177.Dv F_GETFL 178and 179.Dv F_SETFL 180flags are as follows: 181.Bl -tag -width O_NONBLOCKX 182.It Dv O_NONBLOCK 183Non-blocking I/O; if no data is available to a 184.Xr read 2 185system call, or if a 186.Xr write 2 187operation would block, 188the read or write call returns -1 with the error 189.Er EAGAIN . 190.It Dv O_APPEND 191Force each write to append at the end of file; 192corresponds to the 193.Dv O_APPEND 194flag of 195.Xr open 2 . 196.It Dv O_DIRECT 197Minimize or eliminate the cache effects of reading and writing. 198The system 199will attempt to avoid caching the data you read or write. 200If it cannot 201avoid caching the data, it will minimize the impact the data has on the cache. 202Use of this flag can drastically reduce performance if not used with care. 203.It Dv O_ASYNC 204Enable the 205.Dv SIGIO 206signal to be sent to the process group 207when I/O is possible, e.g., 208upon availability of data to be read. 209.El 210.Pp 211Several commands are available for doing advisory file locking; 212they all operate on the following structure: 213.Bd -literal 214struct flock { 215 off_t l_start; /* starting offset */ 216 off_t l_len; /* len = 0 means until end of file */ 217 pid_t l_pid; /* lock owner */ 218 short l_type; /* lock type: read/write, etc. */ 219 short l_whence; /* type of l_start */ 220}; 221.Ed 222The commands available for advisory record locking are as follows: 223.Bl -tag -width F_SETLKWX 224.It Dv F_GETLK 225Get the first lock that blocks the lock description pointed to by the 226third argument, 227.Fa arg , 228taken as a pointer to a 229.Fa "struct flock" 230(see above). 231The information retrieved overwrites the information passed to 232.Fn fcntl 233in the 234.Fa flock 235structure. 236If no lock is found that would prevent this lock from being created, 237the structure is left unchanged by this system call except for the 238lock type which is set to 239.Dv F_UNLCK . 240.It Dv F_SETLK 241Set or clear a file segment lock according to the lock description 242pointed to by the third argument, 243.Fa arg , 244taken as a pointer to a 245.Fa "struct flock" 246(see above). 247.Dv F_SETLK 248is used to establish shared (or read) locks 249.Pq Dv F_RDLCK 250or exclusive (or write) locks, 251.Pq Dv F_WRLCK , 252as well as remove either type of lock 253.Pq Dv F_UNLCK . 254If a shared or exclusive lock cannot be set, 255.Fn fcntl 256returns immediately with 257.Er EAGAIN . 258.It Dv F_SETLKW 259This command is the same as 260.Dv F_SETLK 261except that if a shared or exclusive lock is blocked by other locks, 262the process waits until the request can be satisfied. 263If a signal that is to be caught is received while 264.Fn fcntl 265is waiting for a region, the 266.Fn fcntl 267will be interrupted if the signal handler has not specified the 268.Dv SA_RESTART 269(see 270.Xr sigaction 2 ) . 271.El 272.Pp 273When a shared lock has been set on a segment of a file, 274other processes can set shared locks on that segment 275or a portion of it. 276A shared lock prevents any other process from setting an exclusive 277lock on any portion of the protected area. 278A request for a shared lock fails if the file descriptor was not 279opened with read access. 280.Pp 281An exclusive lock prevents any other process from setting a shared lock or 282an exclusive lock on any portion of the protected area. 283A request for an exclusive lock fails if the file was not 284opened with write access. 285.Pp 286The value of 287.Fa l_whence 288is 289.Dv SEEK_SET , 290.Dv SEEK_CUR , 291or 292.Dv SEEK_END 293to indicate that the relative offset, 294.Fa l_start 295bytes, will be measured from the start of the file, 296current position, or end of the file, respectively. 297The value of 298.Fa l_len 299is the number of consecutive bytes to be locked. 300If 301.Fa l_len 302is negative, the result is undefined. 303The 304.Fa l_pid 305field is only used with 306.Dv F_GETLK 307to return the process ID of the process holding a blocking lock. 308After a successful 309.Dv F_GETLK 310request, the value of 311.Fa l_whence 312is 313.Dv SEEK_SET . 314.Pp 315Locks may start and extend beyond the current end of a file, 316but may not start or extend before the beginning of the file. 317A lock is set to extend to the largest possible value of the 318file offset for that file if 319.Fa l_len 320is set to zero. 321If 322.Fa l_whence 323and 324.Fa l_start 325point to the beginning of the file, and 326.Fa l_len 327is zero, the entire file is locked. 328If an application wishes only to do entire file locking, the 329.Xr flock 2 330system call is much more efficient. 331.Pp 332There is at most one type of lock set for each byte in the file. 333Before a successful return from an 334.Dv F_SETLK 335or an 336.Dv F_SETLKW 337request when the calling process has previously existing locks 338on bytes in the region specified by the request, 339the previous lock type for each byte in the specified 340region is replaced by the new lock type. 341As specified above under the descriptions 342of shared locks and exclusive locks, an 343.Dv F_SETLK 344or an 345.Dv F_SETLKW 346request fails or blocks respectively when another process has existing 347locks on bytes in the specified region and the type of any of those 348locks conflicts with the type specified in the request. 349.Pp 350This interface follows the completely stupid semantics of System V and 351.St -p1003.1-88 352that require that all locks associated with a file for a given process are 353removed when 354.Em any 355file descriptor for that file is closed by that process. 356This semantic means that applications must be aware of any files that 357a subroutine library may access. 358For example if an application for updating the password file locks the 359password file database while making the update, and then calls 360.Xr getpwnam 3 361to retrieve a record, 362the lock will be lost because 363.Xr getpwnam 3 364opens, reads, and closes the password database. 365The database close will release all locks that the process has 366associated with the database, even if the library routine never 367requested a lock on the database. 368Another minor semantic problem with this interface is that 369locks are not inherited by a child process created using the 370.Xr fork 2 371system call. 372The 373.Xr flock 2 374interface has much more rational last close semantics and 375allows locks to be inherited by child processes. 376The 377.Xr flock 2 378system call is recommended for applications that want to ensure the integrity 379of their locks when using library routines or wish to pass locks 380to their children. 381.Pp 382The 383.Fn fcntl , 384.Xr flock 2 , 385and 386.Xr lockf 3 387locks are compatible. 388Processes using different locking interfaces can cooperate 389over the same file safely. 390However, only one of such interfaces should be used within 391the same process. 392If a file is locked by a process through 393.Xr flock 2 , 394any record within the file will be seen as locked 395from the viewpoint of another process using 396.Fn fcntl 397or 398.Xr lockf 3 , 399and vice versa. 400Note that 401.Fn fcntl F_GETLK 402returns \-1 in 403.Fa l_pid 404if the process holding a blocking lock previously locked the 405file descriptor by 406.Xr flock 2 . 407.Pp 408All locks associated with a file for a given process are 409removed when the process terminates. 410.Pp 411All locks obtained before a call to 412.Xr execve 2 413remain in effect until the new program releases them. 414If the new program does not know about the locks, they will not be 415released until the program exits. 416.Pp 417A potential for deadlock occurs if a process controlling a locked region 418is put to sleep by attempting to lock the locked region of another process. 419This implementation detects that sleeping until a locked region is unlocked 420would cause a deadlock and fails with an 421.Er EDEADLK 422error. 423.Sh RETURN VALUES 424Upon successful completion, the value returned depends on 425.Fa cmd 426as follows: 427.Bl -tag -width F_GETOWNX -offset indent 428.It Dv F_DUPFD 429A new file descriptor. 430.It Dv F_DUP2FD 431A file descriptor equal to 432.Fa arg . 433.It Dv F_GETFD 434Value of flag (only the low-order bit is defined). 435.It Dv F_GETFL 436Value of flags. 437.It Dv F_GETOWN 438Value of file descriptor owner. 439.It other 440Value other than -1. 441.El 442.Pp 443Otherwise, a value of -1 is returned and 444.Va errno 445is set to indicate the error. 446.Sh ERRORS 447The 448.Fn fcntl 449system call will fail if: 450.Bl -tag -width Er 451.It Bq Er EAGAIN 452The argument 453.Fa cmd 454is 455.Dv F_SETLK , 456the type of lock 457.Pq Fa l_type 458is a shared lock 459.Pq Dv F_RDLCK 460or exclusive lock 461.Pq Dv F_WRLCK , 462and the segment of a file to be locked is already 463exclusive-locked by another process; 464or the type is an exclusive lock and some portion of the 465segment of a file to be locked is already shared-locked or 466exclusive-locked by another process. 467.It Bq Er EBADF 468The 469.Fa fd 470argument 471is not a valid open file descriptor. 472.Pp 473The argument 474.Fa cmd 475is 476.Dv F_DUP2FD , 477and 478.Fa arg 479is not a valid file descriptor. 480.Pp 481The argument 482.Fa cmd 483is 484.Dv F_SETLK 485or 486.Dv F_SETLKW , 487the type of lock 488.Pq Fa l_type 489is a shared lock 490.Pq Dv F_RDLCK , 491and 492.Fa fd 493is not a valid file descriptor open for reading. 494.Pp 495The argument 496.Fa cmd 497is 498.Dv F_SETLK 499or 500.Dv F_SETLKW , 501the type of lock 502.Pq Fa l_type 503is an exclusive lock 504.Pq Dv F_WRLCK , 505and 506.Fa fd 507is not a valid file descriptor open for writing. 508.It Bq Er EDEADLK 509The argument 510.Fa cmd 511is 512.Dv F_SETLKW , 513and a deadlock condition was detected. 514.It Bq Er EINTR 515The argument 516.Fa cmd 517is 518.Dv F_SETLKW , 519and the system call was interrupted by a signal. 520.It Bq Er EINVAL 521The 522.Fa cmd 523argument 524is 525.Dv F_DUPFD 526and 527.Fa arg 528is negative or greater than the maximum allowable number 529(see 530.Xr getdtablesize 2 ) . 531.Pp 532The argument 533.Fa cmd 534is 535.Dv F_GETLK , 536.Dv F_SETLK 537or 538.Dv F_SETLKW 539and the data to which 540.Fa arg 541points is not valid. 542.It Bq Er EMFILE 543The argument 544.Fa cmd 545is 546.Dv F_DUPFD 547and the maximum number of file descriptors permitted for the 548process are already in use, 549or no file descriptors greater than or equal to 550.Fa arg 551are available. 552.It Bq Er ENOLCK 553The argument 554.Fa cmd 555is 556.Dv F_SETLK 557or 558.Dv F_SETLKW , 559and satisfying the lock or unlock request would result in the 560number of locked regions in the system exceeding a system-imposed limit. 561.It Bq Er EPERM 562The 563.Fa cmd 564argument 565is 566.Dv F_SETOWN 567and 568the process ID or process group given as an argument is in a 569different session than the caller. 570.It Bq Er ERANGE 571The 572.Fa cmd 573argument is 574.Dv F_GETPATH 575and the resulting path, inclusive of the terminator, would be greater than 576.Dv MAXPATHLEN . 577.It Bq Er ESRCH 578The 579.Fa cmd 580argument 581is 582.Dv F_SETOWN 583and 584the process ID given as argument is not in use. 585.El 586.Pp 587In addition, if 588.Fa fd 589refers to a descriptor open on a terminal device (as opposed to a 590descriptor open on a socket), a 591.Fa cmd 592of 593.Dv F_SETOWN 594can fail for the same reasons as in 595.Xr tcsetpgrp 3 , 596and a 597.Fa cmd 598of 599.Dv F_GETOWN 600for the reasons as stated in 601.Xr tcgetpgrp 3 . 602.Sh SEE ALSO 603.Xr close 2 , 604.Xr dup2 2 , 605.Xr execve 2 , 606.Xr flock 2 , 607.Xr getdtablesize 2 , 608.Xr open 2 , 609.Xr sigaction 2 , 610.Xr lockf 3 , 611.Xr tcgetpgrp 3 , 612.Xr tcsetpgrp 3 613.Sh STANDARDS 614The 615.Dv F_DUP2FD 616constant is non portable. 617It is provided for compatibility with AIX and Solaris. 618.Sh HISTORY 619The 620.Fn fcntl 621system call appeared in 622.Bx 4.2 . 623.Pp 624The 625.Dv F_DUPFD_CLOEXEC , 626.Dv F_DUP2FD 627and 628.Dv F_DUP2FD_CLOEXEC 629constants first appeared in 630.Dx 3.5 . 631.Pp 632The 633.Dv F_GETPATH 634constant was introduced in 635.Dx 5.9 . 636