1.\" Copyright (c) 1983 The Regents of the University of California. 2.\" 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 6.7 (Berkeley) 3/10/91 33.\" 34.Dd March 10, 1991 35.Dt FCNTL 2 36.Os BSD 4.2 37.Sh NAME 38.Nm fcntl 39.Nd file control 40.Sh SYNOPSIS 41.Fd #include <sys/fcntl.h> 42.Ft int 43.Fn fcntl "int fd" "int cmd" "int arg" 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 follows: 52.Bl -tag -width F_GETOWNX 53.It Dv F_DUPFD 54Return a new descriptor as follows: 55.Pp 56.Bl -bullet -compact -offset 4n 57.It 58Lowest numbered available descriptor greater than or equal to 59.Fa arg . 60.It 61Same object references as the original descriptor. 62.It 63New descriptor shares the same file offset if the object 64was a file. 65.It 66Same access mode (read, write or read/write). 67.It 68Same file status flags (i.e., both file descriptors 69share the same file status flags). 70.It 71The close-on-exec flag associated with the new file descriptor 72is set to remain open across 73.Xr execv 2 74system calls. 75.El 76.It Dv F_GETFD 77Get the close-on-exec flag associated with the file descriptor 78.Fa fd . 79If the low-order bit of the returned value is 0, 80the file will remain open across 81.Fn exec , 82otherwise the file will be closed upon execution of 83.Fn exec 84.Fa ( arg 85is ignored). 86.It Dv F_SETFD 87Set the close-on-exec flag associated with 88.Fa fd 89to the low order bit of 90.Fa arg 91(0 or 1 as above). 92.It Dv F_GETFL 93Get descriptor status flags, as described below 94.Fa ( arg 95is ignored). 96.It Dv F_SETFL 97Set descriptor status flags to 98.Fa arg . 99.It Dv F_GETOWN 100Get the process ID or process group 101currently receiving 102.Dv SIGIO 103and 104.Dv SIGURG 105signals; process groups are returned 106as negative values 107.Fa ( arg 108is ignored). 109.It Dv F_SETOWN 110Set the process or process group 111to receive 112.Dv SIGIO 113and 114.Dv SIGURG 115signals; 116process groups are specified by supplying 117.Fa arg 118as negative, otherwise 119.Fa arg 120is interpreted as a process ID. 121.El 122.Pp 123The flags for the 124.Dv F_GETFL 125and 126.Dv F_SETFL 127flags are as follows: 128.Bl -tag -width F_GETOWNX 129.It Dv O_NDELAY 130Non-blocking I/O; if no data is available to a 131.Xr read 132call, or if a 133.Xr write 134operation would block, 135the read or write call returns -1 with the error 136.Er EWOULDBLOCK . 137.It Dv O_APPEND 138Force each write to append at the end of file; 139corresponds to the 140.Dv O_APPEND 141flag of 142.Xr open 2 . 143.It Dv O_ASYNC 144Enable the 145.Dv SIGIO 146signal to be sent to the process group 147when I/O is possible, e.g., 148upon availability of data to be read. 149.El 150.Sh RETURN VALUES 151Upon successful completion, the value returned depends on 152.Fa cmd 153as follows: 154.Bl -tag -width F_GETOWNX -offset indent 155.It Dv F_DUPFD 156A new file descriptor. 157.It Dv F_GETFD 158Value of flag (only the low-order bit is defined). 159.It Dv F_GETFL 160Value of flags. 161.It Dv F_GETOWN 162Value of file descriptor owner. 163.It other 164Value other than -1. 165.El 166.Pp 167Otherwise, a value of -1 is returned and 168.Va errno 169is set to indicate the error. 170.Sh ERRORS 171.Fn Fcntl 172will fail if: 173.Bl -tag -width Er 174.It Bq Er EBADF 175.Fa Fildes 176is not a valid open file descriptor. 177.It Bq Er EMFILE 178.Fa Cmd 179is 180.Dv F_DUPFD 181and the maximum allowed number of file descriptors are currently 182open. 183.It Bq Er EINVAL 184.Fa Cmd 185is 186.Dv F_DUPFD 187and 188.Fa arg 189is negative or greater than the maximum allowable number 190(see 191.Xr getdtablesize 2 ) . 192.It Bq Er ESRCH 193.Fa Cmd 194is 195.Dv F_SETOWN 196and 197the process ID given as argument is not in use. 198.El 199.Sh SEE ALSO 200.Xr close 2 , 201.Xr execve 2 , 202.Xr getdtablesize 2 , 203.Xr open 2 , 204.Xr sigvec 2 205.Sh BUGS 206The asynchronous I/O facilities of 207.Dv FNDELAY 208and 209.Dv FASYNC 210are currently available only for tty and socket operations. 211.Sh HISTORY 212The 213.Nm 214function call appeared in 215.Bx 4.2 . 216