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