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