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