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