1.\" $OpenBSD: fcntl.2,v 1.31 2014/12/16 00:06:49 schwarze 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: December 16 2014 $ 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 result is undefined. 290The 291.Fa l_pid 292field is only used with 293.Dv F_GETLK 294to return the process ID of the process holding a blocking lock. 295After a successful 296.Dv F_GETLK 297request, the value of 298.Fa l_whence 299is 300.Dv SEEK_SET . 301.Pp 302Locks may start and extend beyond the current end of a file, 303but may not start or extend before the beginning of the file. 304A lock is set to extend to the largest possible value of the 305file offset for that file if 306.Fa l_len 307is set to zero. 308If 309.Fa l_whence 310and 311.Fa l_start 312point to the beginning of the file, and 313.Fa l_len 314is zero, the entire file is locked. 315If an application wishes only to do entire file locking, the 316.Xr flock 2 317system call is much more efficient. 318.Pp 319There is at most one type of lock set for each byte in the file. 320Before a successful return from an 321.Dv F_SETLK 322or an 323.Dv F_SETLKW 324request when the calling process has previously existing locks 325on bytes in the region specified by the request, 326the previous lock type for each byte in the specified 327region is replaced by the new lock type. 328As specified above under the descriptions 329of shared locks and exclusive locks, an 330.Dv F_SETLK 331or an 332.Dv F_SETLKW 333request fails or blocks respectively when another process has existing 334locks on bytes in the specified region and the type of any of those 335locks conflicts with the type specified in the request. 336.Pp 337This interface follows the completely stupid semantics of System V and 338.St -p1003.1-88 339that require that all locks associated with a file for a given process are 340removed when 341.Em any 342file descriptor for that file is closed by that process. 343This semantic means that applications must be aware of any files that 344a subroutine library may access. 345For example if an application for updating the password file locks the 346password file database while making the update, and then calls 347.Xr getpwnam 3 348to retrieve a record, 349the lock will be lost because 350.Xr getpwnam 3 351opens, reads, and closes the password database. 352The database close will release all locks that the process has 353associated with the database, even if the library routine never 354requested a lock on the database. 355Another minor semantic problem with this interface is that 356locks are not inherited by a child process created using the 357.Xr fork 2 358function. 359The 360.Xr flock 2 361interface has much more rational last close semantics and 362allows locks to be inherited by child processes. 363.Xr flock 2 364is recommended for applications that want to ensure the integrity 365of their locks when using library routines or wish to pass locks 366to their children. 367Note that 368.Xr flock 2 369and 370.Fn fcntl 371locks may be safely used concurrently. 372.Pp 373All locks associated with a file for a given process are 374removed when the process terminates. 375.Pp 376A potential for deadlock occurs if a process controlling a locked region 377is put to sleep by attempting to lock the locked region of another process. 378This implementation detects that sleeping until a locked region is unlocked 379would cause a deadlock and fails with an 380.Er EDEADLK 381error. 382.Sh RETURN VALUES 383Upon successful completion, the value returned depends on 384.Fa cmd 385as follows: 386.Bl -tag -width F_DUPFD_CLOEXEC -offset indent 387.It Dv F_DUPFD 388A new file descriptor. 389.It Dv F_DUPFD_CLOEXEC 390A new file descriptor. 391.It Dv F_GETFD 392Value of flag (only the low-order bit is defined). 393.It Dv F_GETFL 394Value of flags. 395.It Dv F_GETOWN 396Value of file descriptor owner. 397.It other 398Value other than \-1. 399.El 400.Pp 401Otherwise, a value of \-1 is returned and 402.Va errno 403is set to indicate the error. 404.Sh ERRORS 405.Fn fcntl 406will fail if: 407.Bl -tag -width Er 408.It Bq Er EAGAIN 409The argument 410.Fa cmd 411is 412.Dv F_SETLK , 413the type of lock 414.Pq Fa l_type 415is a shared lock 416.Pq Dv F_RDLCK 417or exclusive lock 418.Pq Dv F_WRLCK , 419and the segment of a file to be locked is already 420exclusive-locked by another process; 421or the type is an exclusive lock and some portion of the 422segment of a file to be locked is already shared-locked or 423exclusive-locked by another process. 424.It Bq Er EBADF 425.Fa fd 426is not a valid open file descriptor. 427.Pp 428The argument 429.Fa cmd 430is 431.Dv F_SETLK 432or 433.Dv F_SETLKW , 434the type of lock 435.Pq Fa l_type 436is a shared lock 437.Pq Dv F_RDLCK , 438and 439.Fa fd 440is not a valid file descriptor open for reading. 441.Pp 442The argument 443.Fa cmd 444is 445.Dv F_SETLK 446or 447.Dv F_SETLKW , 448the type of lock 449.Pq Fa l_type 450is an exclusive lock 451.Pq Dv F_WRLCK , 452and 453.Fa fd 454is not a valid file descriptor open for writing. 455.It Bq Er EDEADLK 456The argument 457.Fa cmd 458is 459.Dv F_SETLKW , 460and a deadlock condition was detected. 461.It Bq Er EINTR 462The argument 463.Fa cmd 464is invalid. 465.Pp 466The argument 467.Fa cmd 468is 469.Dv F_SETLKW , 470and the function was interrupted by a signal. 471.It Bq Er EINVAL 472.Fa cmd 473is 474.Dv F_DUPFD 475and 476.Fa arg 477is negative or greater than the maximum allowable number 478(see 479.Xr getdtablesize 3 ) . 480.Pp 481The argument 482.Fa cmd 483is 484.Dv F_GETLK , 485.Dv F_SETLK , 486or 487.Dv F_SETLKW 488and the data to which 489.Fa arg 490points is not valid, or 491.Fa fd 492refers to a file that does not support locking. 493.It Bq Er EMFILE 494The argument 495.Fa cmd 496is 497.Dv F_DUPFD 498and the maximum number of open file descriptors permitted for the 499process are already in use, 500or no file descriptors greater than or equal to 501.Fa arg 502are available. 503.It Bq Er ENOLCK 504The argument 505.Fa cmd 506is 507.Dv F_SETLK 508or 509.Dv F_SETLKW , 510and satisfying the lock or unlock request would result in the 511number of locked regions in the system exceeding a system-imposed limit. 512.It Bq Er ESRCH 513.Fa cmd 514is 515.Dv F_SETOWN 516and the process ID given in 517.Fa arg 518is not in use. 519.El 520.Sh SEE ALSO 521.Xr close 2 , 522.Xr execve 2 , 523.Xr flock 2 , 524.Xr open 2 , 525.Xr sigaction 2 , 526.Xr getdtablesize 3 527.Sh STANDARDS 528The 529.Fn fcntl 530function conforms to 531.St -p1003.1-2008 . 532.Sh HISTORY 533The 534.Fn fcntl 535function call appeared in 536.Bx 4.2 . 537