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