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