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