1.\" $OpenBSD: fcntl.2,v 1.30 2013/03/31 08:35:46 guenther 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: March 31 2013 $ 34.Dt FCNTL 2 35.Os 36.Sh NAME 37.Nm fcntl 38.Nd file control 39.Sh SYNOPSIS 40.Fd #include <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 171.Tn I/O ; 172if no data is available to a 173.Xr read 2 174call, or if a 175.Xr write 2 176operation would block, 177the read or write call returns \-1 with the error 178.Er EAGAIN . 179.It Dv O_APPEND 180Force each write to append at the end of file; 181corresponds to the 182.Dv O_APPEND 183flag of 184.Xr open 2 . 185.It Dv O_ASYNC 186Enable the 187.Dv SIGIO 188signal to be sent to the process group 189when 190.Tn I/O 191is possible, e.g., 192upon availability of data to be read. 193.It Dv O_SYNC 194Cause writes to be synchronous. 195Data will be written to the physical device instead of 196just being stored in the buffer cache; corresponds to the 197.Dv O_SYNC 198flag of 199.Xr open 2 . 200.El 201.Pp 202Several commands are available for doing advisory file locking; 203they all operate on the following structure: 204.Bd -literal 205struct flock { 206 off_t l_start; /* starting offset */ 207 off_t l_len; /* len = 0 means until end of file */ 208 pid_t l_pid; /* lock owner */ 209 short l_type; /* lock type: read/write, etc. */ 210 short l_whence; /* type of l_start */ 211}; 212.Ed 213.Pp 214The commands available for advisory record locking are as follows: 215.Bl -tag -width F_SETLKWX 216.It Dv F_GETLK 217Get the first lock that blocks the lock description pointed to by the 218third argument, 219.Fa arg , 220taken as a pointer to a 221.Fa "struct flock" 222(see above). 223The information retrieved overwrites the information passed to 224.Fn fcntl 225in the 226.Fa flock 227structure. 228If no lock is found that would prevent this lock from being created, 229the structure is left unchanged by this function call except for the 230lock type which is set to 231.Dv F_UNLCK . 232.It Dv F_SETLK 233Set or clear a file segment lock according to the lock description 234pointed to by the third argument, 235.Fa arg , 236taken as a pointer to a 237.Fa "struct flock" 238(see above). 239.Dv F_SETLK 240is used to establish shared (or read) locks 241.Pq Dv F_RDLCK 242or exclusive (or write) locks 243.Pq Dv F_WRLCK , 244as well as remove either type of lock 245.Pq Dv F_UNLCK . 246If a shared or exclusive lock cannot be set, 247.Fn fcntl 248returns immediately with 249.Er EAGAIN . 250.It Dv F_SETLKW 251This command is the same as 252.Dv F_SETLK 253except that if a shared or exclusive lock is blocked by other locks, 254the process waits until the request can be satisfied. 255If a signal that is to be caught is received while 256.Fn fcntl 257is waiting for a region, the 258.Fn fcntl 259will be interrupted if the signal handler has not specified the 260.Dv SA_RESTART 261(see 262.Xr sigaction 2 ) . 263.El 264.Pp 265When a shared lock has been set on a segment of a file, 266other processes can set shared locks on that segment 267or a portion of it. 268A shared lock prevents any other process from setting an exclusive 269lock on any portion of the protected area. 270A request for a shared lock fails if the file descriptor was not 271opened with read access. 272.Pp 273An exclusive lock prevents any other process from setting a shared lock or 274an exclusive lock on any portion of the protected area. 275A request for an exclusive lock fails if the file was not 276opened with write access. 277.Pp 278The value of 279.Fa l_whence 280is 281.Dv SEEK_SET , 282.Dv SEEK_CUR , 283or 284.Dv SEEK_END 285to indicate that the relative offset, 286.Fa l_start 287bytes, will be measured from the start of the file, 288current position, or end of the file, respectively. 289The value of 290.Fa l_len 291is the number of consecutive bytes to be locked. 292If 293.Fa l_len 294is negative, the result is undefined. 295The 296.Fa l_pid 297field is only used with 298.Dv F_GETLK 299to return the process ID of the process holding a blocking lock. 300After a successful 301.Dv F_GETLK 302request, the value of 303.Fa l_whence 304is 305.Dv SEEK_SET . 306.Pp 307Locks may start and extend beyond the current end of a file, 308but may not start or extend before the beginning of the file. 309A lock is set to extend to the largest possible value of the 310file offset for that file if 311.Fa l_len 312is set to zero. 313If 314.Fa l_whence 315and 316.Fa l_start 317point to the beginning of the file, and 318.Fa l_len 319is zero, the entire file is locked. 320If an application wishes only to do entire file locking, the 321.Xr flock 2 322system call is much more efficient. 323.Pp 324There is at most one type of lock set for each byte in the file. 325Before a successful return from an 326.Dv F_SETLK 327or an 328.Dv F_SETLKW 329request when the calling process has previously existing locks 330on bytes in the region specified by the request, 331the previous lock type for each byte in the specified 332region is replaced by the new lock type. 333As specified above under the descriptions 334of shared locks and exclusive locks, an 335.Dv F_SETLK 336or an 337.Dv F_SETLKW 338request fails or blocks respectively when another process has existing 339locks on bytes in the specified region and the type of any of those 340locks conflicts with the type specified in the request. 341.Pp 342This interface follows the completely stupid semantics of System V and 343.St -p1003.1-88 344that require that all locks associated with a file for a given process are 345removed when 346.Em any 347file descriptor for that file is closed by that process. 348This semantic means that applications must be aware of any files that 349a subroutine library may access. 350For example if an application for updating the password file locks the 351password file database while making the update, and then calls 352.Xr getpwnam 3 353to retrieve a record, 354the lock will be lost because 355.Xr getpwnam 3 356opens, reads, and closes the password database. 357The database close will release all locks that the process has 358associated with the database, even if the library routine never 359requested a lock on the database. 360Another minor semantic problem with this interface is that 361locks are not inherited by a child process created using the 362.Xr fork 2 363function. 364The 365.Xr flock 2 366interface has much more rational last close semantics and 367allows locks to be inherited by child processes. 368.Xr flock 2 369is recommended for applications that want to ensure the integrity 370of their locks when using library routines or wish to pass locks 371to their children. 372Note that 373.Xr flock 2 374and 375.Fn fcntl 376locks may be safely used concurrently. 377.Pp 378All locks associated with a file for a given process are 379removed when the process terminates. 380.Pp 381A potential for deadlock occurs if a process controlling a locked region 382is put to sleep by attempting to lock the locked region of another process. 383This implementation detects that sleeping until a locked region is unlocked 384would cause a deadlock and fails with an 385.Er EDEADLK 386error. 387.Sh RETURN VALUES 388Upon successful completion, the value returned depends on 389.Fa cmd 390as follows: 391.Bl -tag -width F_DUPFD_CLOEXEC -offset indent 392.It Dv F_DUPFD 393A new file descriptor. 394.It Dv F_DUPFD_CLOEXEC 395A new file descriptor. 396.It Dv F_GETFD 397Value of flag (only the low-order bit is defined). 398.It Dv F_GETFL 399Value of flags. 400.It Dv F_GETOWN 401Value of file descriptor owner. 402.It other 403Value other than \-1. 404.El 405.Pp 406Otherwise, a value of \-1 is returned and 407.Va errno 408is set to indicate the error. 409.Sh ERRORS 410.Fn fcntl 411will fail if: 412.Bl -tag -width Er 413.It Bq Er EAGAIN 414The argument 415.Fa cmd 416is 417.Dv F_SETLK , 418the type of lock 419.Pq Fa l_type 420is a shared lock 421.Pq Dv F_RDLCK 422or exclusive lock 423.Pq Dv F_WRLCK , 424and the segment of a file to be locked is already 425exclusive-locked by another process; 426or the type is an exclusive lock and some portion of the 427segment of a file to be locked is already shared-locked or 428exclusive-locked by another process. 429.It Bq Er EBADF 430.Fa fd 431is not a valid open file descriptor. 432.Pp 433The argument 434.Fa cmd 435is 436.Dv F_SETLK 437or 438.Dv F_SETLKW , 439the type of lock 440.Pq Fa l_type 441is a shared lock 442.Pq Dv F_RDLCK , 443and 444.Fa fd 445is not a valid file descriptor open for reading. 446.Pp 447The argument 448.Fa cmd 449is 450.Dv F_SETLK 451or 452.Dv F_SETLKW , 453the type of lock 454.Pq Fa l_type 455is an exclusive lock 456.Pq Dv F_WRLCK , 457and 458.Fa fd 459is not a valid file descriptor open for writing. 460.It Bq Er EDEADLK 461The argument 462.Fa cmd 463is 464.Dv F_SETLKW , 465and a deadlock condition was detected. 466.It Bq Er EINTR 467The argument 468.Fa cmd 469is invalid. 470.Pp 471The argument 472.Fa cmd 473is 474.Dv F_SETLKW , 475and the function was interrupted by a signal. 476.It Bq Er EINVAL 477.Fa cmd 478is 479.Dv F_DUPFD 480and 481.Fa arg 482is negative or greater than the maximum allowable number 483(see 484.Xr getdtablesize 3 ) . 485.Pp 486The argument 487.Fa cmd 488is 489.Dv F_GETLK , 490.Dv F_SETLK , 491or 492.Dv F_SETLKW 493and the data to which 494.Fa arg 495points is not valid, or 496.Fa fd 497refers to a file that does not support locking. 498.It Bq Er EMFILE 499The argument 500.Fa cmd 501is 502.Dv F_DUPFD 503and the maximum number of open file descriptors permitted for the 504process are already in use, 505or no file descriptors greater than or equal to 506.Fa arg 507are available. 508.It Bq Er ENOLCK 509The argument 510.Fa cmd 511is 512.Dv F_SETLK 513or 514.Dv F_SETLKW , 515and satisfying the lock or unlock request would result in the 516number of locked regions in the system exceeding a system-imposed limit. 517.It Bq Er ESRCH 518.Fa cmd 519is 520.Dv F_SETOWN 521and the process ID given in 522.Fa arg 523is not in use. 524.El 525.Sh SEE ALSO 526.Xr close 2 , 527.Xr execve 2 , 528.Xr flock 2 , 529.Xr open 2 , 530.Xr sigaction 2 , 531.Xr getdtablesize 3 532.Sh STANDARDS 533The 534.Fn fcntl 535function conforms to 536.St -p1003.1-2008 . 537.Sh HISTORY 538The 539.Fn fcntl 540function call appeared in 541.Bx 4.2 . 542