1.\" $OpenBSD: fcntl.2,v 1.33 2019/09/06 08:39:27 asou Exp $ 2.\" $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 32.\" 33.Dd $Mdocdate: September 6 2019 $ 34.Dt FCNTL 2 35.Os 36.Sh NAME 37.Nm fcntl 38.Nd file control 39.Sh SYNOPSIS 40.In fcntl.h 41.Ft int 42.Fn fcntl "int fd" "int cmd" "..." 43.Sh DESCRIPTION 44The 45.Fn fcntl 46provides control over the properties of a file that is already open. 47The argument 48.Fa fd 49is a descriptor to be operated on by 50.Fa cmd 51as described below. 52The third parameter is called 53.Fa arg 54and is technically a pointer to 55.Fa void , 56but is interpreted as an 57.Li int 58by some commands, a pointer to a 59.Li struct flock 60by others (see below), and ignored by the rest. 61.Pp 62The commands are: 63.Bl -tag -width F_DUPFD_CLOEXEC 64.It Dv F_DUPFD 65Return a new descriptor as follows: 66.Pp 67.Bl -bullet -compact 68.It 69Lowest numbered available descriptor greater than or equal to 70.Fa arg 71(interpreted as an 72.Li int ) . 73.It 74Same object references as the original descriptor. 75.It 76New descriptor shares the same file offset if the object 77was a file. 78.It 79Same access mode (read, write or read/write). 80.It 81Same file status flags (i.e., both file descriptors 82share the same file status flags). 83.It 84The close-on-exec flag associated with the new file descriptor 85is set to remain open across 86.Xr execve 2 87calls. 88.El 89.It Dv F_DUPFD_CLOEXEC 90Like 91.Dv F_DUPFD , 92but the 93.Dv FD_CLOEXEC 94flag associated with the new file descriptor is set, so the file descriptor 95is closed when 96.Xr execve 2 97is called. 98.It Dv F_GETFD 99Get the close-on-exec flag associated with the file descriptor 100.Fa fd 101as 102.Dv FD_CLOEXEC . 103If the returned value ANDed with 104.Dv FD_CLOEXEC 105is 0, 106the file will remain open across 107.Fn exec , 108otherwise the file will be closed upon execution of 109.Fn exec 110.Fa ( arg 111is ignored). 112.It Dv F_SETFD 113Set the close-on-exec flag associated with 114.Fa fd 115to 116.Fa arg , 117where 118.Fa arg 119(interpreted as an 120.Li int ) 121is either 0 or 122.Dv FD_CLOEXEC , 123as described above. 124.It Dv F_GETFL 125Get file status flags associated with the file descriptor 126.Fa fd , 127as described below 128.Fa ( arg 129is ignored). 130.It Dv F_SETFL 131Set file status flags associated with the file descriptor 132.Fa fd 133to 134.Fa arg 135(interpreted as an 136.Li int ) . 137.It Dv F_GETOWN 138Get the process ID or process group 139currently receiving 140.Dv SIGIO 141and 142.Dv SIGURG 143signals; process groups are returned 144as negative values 145.Fa ( arg 146is ignored). 147.It Dv F_SETOWN 148Set the process or process group 149to receive 150.Dv SIGIO 151and 152.Dv SIGURG 153signals; 154process groups are specified by supplying 155.Fa arg 156(interpreted as an 157.Li int ) 158as negative, otherwise 159.Fa arg 160is taken as a process ID. 161.El 162.Pp 163The flags for the 164.Dv F_GETFL 165and 166.Dv F_SETFL 167commands are as follows: 168.Bl -tag -width O_NONBLOCKX 169.It Dv O_NONBLOCK 170Non-blocking I/O; if no data is available to a 171.Xr read 2 172call, or if a 173.Xr write 2 174operation would block, 175the read or write call returns \-1 with the error 176.Er EAGAIN . 177.It Dv O_APPEND 178Force each write to append at the end of file; 179corresponds to the 180.Dv O_APPEND 181flag of 182.Xr open 2 . 183.It Dv O_ASYNC 184Enable the 185.Dv SIGIO 186signal to be sent to the process group when I/O is possible, e.g., 187upon availability of data to be read. 188.It Dv O_SYNC 189Cause writes to be synchronous. 190Data will be written to the physical device instead of 191just being stored in the buffer cache; corresponds to the 192.Dv O_SYNC 193flag of 194.Xr open 2 . 195.El 196.Pp 197Several commands are available for doing advisory file locking; 198they all operate on the following structure: 199.Bd -literal 200struct flock { 201 off_t l_start; /* starting offset */ 202 off_t l_len; /* len = 0 means until end of file */ 203 pid_t l_pid; /* lock owner */ 204 short l_type; /* lock type: read/write, etc. */ 205 short l_whence; /* type of l_start */ 206}; 207.Ed 208.Pp 209The commands available for advisory record locking are as follows: 210.Bl -tag -width F_SETLKWX 211.It Dv F_GETLK 212Get the first lock that blocks the lock description pointed to by the 213third argument, 214.Fa arg , 215taken as a pointer to a 216.Fa "struct flock" 217(see above). 218The information retrieved overwrites the information passed to 219.Fn fcntl 220in the 221.Fa flock 222structure. 223If no lock is found that would prevent this lock from being created, 224the structure is left unchanged by this function call except for the 225lock type which is set to 226.Dv F_UNLCK . 227.It Dv F_SETLK 228Set or clear a file segment lock according to the lock description 229pointed to by the third argument, 230.Fa arg , 231taken as a pointer to a 232.Fa "struct flock" 233(see above). 234.Dv F_SETLK 235is used to establish shared (or read) locks 236.Pq Dv F_RDLCK 237or exclusive (or write) locks 238.Pq Dv F_WRLCK , 239as well as remove either type of lock 240.Pq Dv F_UNLCK . 241If a shared or exclusive lock cannot be set, 242.Fn fcntl 243returns immediately with 244.Er EAGAIN . 245.It Dv F_SETLKW 246This command is the same as 247.Dv F_SETLK 248except that if a shared or exclusive lock is blocked by other locks, 249the process waits until the request can be satisfied. 250If a signal that is to be caught is received while 251.Fn fcntl 252is waiting for a region, the 253.Fn fcntl 254will be interrupted if the signal handler has not specified the 255.Dv SA_RESTART 256(see 257.Xr sigaction 2 ) . 258.El 259.Pp 260When a shared lock has been set on a segment of a file, 261other processes can set shared locks on that segment 262or a portion of it. 263A shared lock prevents any other process from setting an exclusive 264lock on any portion of the protected area. 265A request for a shared lock fails if the file descriptor was not 266opened with read access. 267.Pp 268An exclusive lock prevents any other process from setting a shared lock or 269an exclusive lock on any portion of the protected area. 270A request for an exclusive lock fails if the file was not 271opened with write access. 272.Pp 273The value of 274.Fa l_whence 275is 276.Dv SEEK_SET , 277.Dv SEEK_CUR , 278or 279.Dv SEEK_END 280to indicate that the relative offset, 281.Fa l_start 282bytes, will be measured from the start of the file, 283current position, or end of the file, respectively. 284The value of 285.Fa l_len 286is the number of consecutive bytes to be locked. 287If 288.Fa l_len 289is negative, the area starting at 290.Fa l_start Ns + Ns Fa l_len 291and ending at 292.Fa l_start Ns -1 293is locked. 294The 295.Fa l_pid 296field is only used with 297.Dv F_GETLK 298to return the process ID of the process holding a blocking lock. 299After a successful 300.Dv F_GETLK 301request, the value of 302.Fa l_whence 303is 304.Dv SEEK_SET . 305.Pp 306Locks may start and extend beyond the current end of a file, 307but may not start or extend before the beginning of the file. 308A lock is set to extend to the largest possible value of the 309file offset for that file if 310.Fa l_len 311is set to zero. 312If 313.Fa l_whence 314and 315.Fa l_start 316point to the beginning of the file, and 317.Fa l_len 318is zero, the entire file is locked. 319If an application wishes only to do entire file locking, the 320.Xr flock 2 321system call is much more efficient. 322.Pp 323There is at most one type of lock set for each byte in the file. 324Before a successful return from an 325.Dv F_SETLK 326or an 327.Dv F_SETLKW 328request when the calling process has previously existing locks 329on bytes in the region specified by the request, 330the previous lock type for each byte in the specified 331region is replaced by the new lock type. 332As specified above under the descriptions 333of shared locks and exclusive locks, an 334.Dv F_SETLK 335or an 336.Dv F_SETLKW 337request fails or blocks respectively when another process has existing 338locks on bytes in the specified region and the type of any of those 339locks conflicts with the type specified in the request. 340.Pp 341This interface follows the completely stupid semantics of System V and 342.St -p1003.1-88 343that require that all locks associated with a file for a given process are 344removed when 345.Em any 346file descriptor for that file is closed by that process. 347This semantic means that applications must be aware of any files that 348a subroutine library may access. 349For example if an application for updating the password file locks the 350password file database while making the update, and then calls 351.Xr getpwnam 3 352to retrieve a record, 353the lock will be lost because 354.Xr getpwnam 3 355opens, reads, and closes the password database. 356The database close will release all locks that the process has 357associated with the database, even if the library routine never 358requested a lock on the database. 359Another minor semantic problem with this interface is that 360locks are not inherited by a child process created using the 361.Xr fork 2 362function. 363The 364.Xr flock 2 365interface has much more rational last close semantics and 366allows locks to be inherited by child processes. 367.Xr flock 2 368is recommended for applications that want to ensure the integrity 369of their locks when using library routines or wish to pass locks 370to their children. 371Note that 372.Xr flock 2 373and 374.Fn fcntl 375locks may be safely used concurrently. 376.Pp 377All locks associated with a file for a given process are 378removed when the process terminates. 379.Pp 380A potential for deadlock occurs if a process controlling a locked region 381is put to sleep by attempting to lock the locked region of another process. 382This implementation detects that sleeping until a locked region is unlocked 383would cause a deadlock and fails with an 384.Er EDEADLK 385error. 386.Sh RETURN VALUES 387Upon successful completion, the value returned depends on 388.Fa cmd 389as follows: 390.Bl -tag -width F_DUPFD_CLOEXEC -offset indent 391.It Dv F_DUPFD 392A new file descriptor. 393.It Dv F_DUPFD_CLOEXEC 394A new file descriptor. 395.It Dv F_GETFD 396Value of flag (only the low-order bit is defined). 397.It Dv F_GETFL 398Value of flags. 399.It Dv F_GETOWN 400Value of file descriptor owner. 401.It other 402Value other than \-1. 403.El 404.Pp 405Otherwise, a value of \-1 is returned and 406.Va errno 407is set to indicate the error. 408.Sh ERRORS 409.Fn fcntl 410will fail if: 411.Bl -tag -width Er 412.It Bq Er EAGAIN 413The argument 414.Fa cmd 415is 416.Dv F_SETLK , 417the type of lock 418.Pq Fa l_type 419is a shared lock 420.Pq Dv F_RDLCK 421or exclusive lock 422.Pq Dv F_WRLCK , 423and the segment of a file to be locked is already 424exclusive-locked by another process; 425or the type is an exclusive lock and some portion of the 426segment of a file to be locked is already shared-locked or 427exclusive-locked by another process. 428.It Bq Er EBADF 429.Fa fd 430is not a valid open file descriptor. 431.Pp 432The argument 433.Fa cmd 434is 435.Dv F_SETLK 436or 437.Dv F_SETLKW , 438the type of lock 439.Pq Fa l_type 440is a shared lock 441.Pq Dv F_RDLCK , 442and 443.Fa fd 444is not a valid file descriptor open for reading. 445.Pp 446The argument 447.Fa cmd 448is 449.Dv F_SETLK 450or 451.Dv F_SETLKW , 452the type of lock 453.Pq Fa l_type 454is an exclusive lock 455.Pq Dv F_WRLCK , 456and 457.Fa fd 458is not a valid file descriptor open for writing. 459.It Bq Er EDEADLK 460The argument 461.Fa cmd 462is 463.Dv F_SETLKW , 464and a deadlock condition was detected. 465.It Bq Er EINTR 466The argument 467.Fa cmd 468is 469.Dv F_SETLK 470or 471.Dv F_SETLKW , 472and the function was interrupted by a signal. 473.It Bq Er EINVAL 474The argument 475.Fa cmd 476is invalid. 477.Pp 478.Fa cmd 479is 480.Dv F_DUPFD 481and 482.Fa arg 483is negative or greater than the maximum allowable number 484(see 485.Xr getdtablesize 3 ) . 486.Pp 487The argument 488.Fa cmd 489is 490.Dv F_GETLK , 491.Dv F_SETLK , 492or 493.Dv F_SETLKW 494and the data to which 495.Fa arg 496points is not valid, or 497.Fa fd 498refers to a file that does not support locking. 499.It Bq Er EMFILE 500The argument 501.Fa cmd 502is 503.Dv F_DUPFD 504and the maximum number of open file descriptors permitted for the 505process are already in use, 506or no file descriptors greater than or equal to 507.Fa arg 508are available. 509.It Bq Er ENOLCK 510The argument 511.Fa cmd 512is 513.Dv F_SETLK 514or 515.Dv F_SETLKW , 516and satisfying the lock or unlock request would result in the 517number of locked regions in the system exceeding a system-imposed limit. 518.It Bq Er EOVERFLOW 519The argument 520.Fa cmd 521is 522.Dv F_GETLK , 523.Dv F_SETLK 524or 525.Dv F_SETLKW 526and the segment length of a file to be locked is too large to be represented by 527an 528.Vt off_t . 529.It Bq Er ESRCH 530.Fa cmd 531is 532.Dv F_SETOWN 533and the process ID given in 534.Fa arg 535is not in use. 536.El 537.Sh SEE ALSO 538.Xr close 2 , 539.Xr execve 2 , 540.Xr flock 2 , 541.Xr open 2 , 542.Xr sigaction 2 , 543.Xr getdtablesize 3 544.Sh STANDARDS 545The 546.Fn fcntl 547function conforms to 548.St -p1003.1-2008 . 549.Sh HISTORY 550The 551.Fn fcntl 552function call appeared in 553.Bx 4.2 . 554