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