1.\" $OpenBSD: file.9,v 1.18 2017/02/11 23:12:22 jmc Exp $ 2.\" 3.\" Copyright (c) 2002 Artur Grabowski <art@openbsd.org> 4.\" 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. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd $Mdocdate: February 11 2017 $ 26.Dt FALLOC 9 27.Os 28.Sh NAME 29.Nm falloc , 30.Nm fdrelease , 31.Nm FREF , 32.Nm FRELE , 33.Nm fd_getfile , 34.Nm getsock , 35.Nm getvnode 36.Nd an overview of file descriptor handling 37.Sh SYNOPSIS 38.In sys/file.h 39.In sys/filedesc.h 40.Ft int 41.Fn falloc "struct proc *p" "int flags" "struct file **resultfp" "int *resultfd" 42.Ft int 43.Fn fdrelease "struct proc *p" "int fd" 44.Ft void 45.Fn FREF "struct file *fp" 46.Ft int 47.Fn FRELE "struct file *fp" "struct proc *p" 48.Ft struct file * 49.Fn fd_getfile "struct filedesc *fdp" "int fd" 50.Ft int 51.Fn getsock "struct proc *p" "int fd" "struct file **fpp" 52.In sys/file.h 53.In sys/filedesc.h 54.In sys/vnode.h 55.Ft int 56.Fn getvnode "struct proc *p" "int fd" "struct file **fpp" 57.Sh DESCRIPTION 58These functions provide the interface for the UNIX file descriptors. 59File descriptors can be used to access vnodes (see 60.Xr vnode 9 ) , 61sockets (see 62.Xr socket 2 ) , 63pipes (see 64.Xr pipe 2 ) , 65kqueues (see 66.Xr kqueue 2 ) , 67and various special purpose communication endpoints. 68.Pp 69A new file and a file descriptor for it are allocated with the function 70.Fn falloc . 71The 72.Fa flags 73argument can be used to set the 74.Dv UF_EXCLOSE 75flag on the new descriptor. 76The larval file and fd are returned via 77.Fa resultfp 78and 79.Fa resultfd , 80which must not be 81.Dv NULL . 82.Fn falloc 83initializes the new file to have a reference count of two: 84one for the reference from the file descriptor table and one 85for the caller to release with 86.Fn FRELE 87when it's done initializing it. 88.Pp 89A file descriptor is freed with 90.Fn fdrelease . 91This releases the reference that it holds to the underlying file; 92if that's the last reference then the file will be freed. 93.\" with 94.\" .Xr closef 9 . 95.Pp 96The files are extracted from the file descriptor table using the 97functions 98.Fn fd_getfile 99.Fn fd_getfile 100performs all necessary checks to see if the file descriptor number is 101within the range of file descriptor table, and if the descriptor is 102valid. 103.Pp 104The files are extracted from the process context using the 105function 106.Fn getsock 107and 108.Fn getvnode . 109These functions are special cases that besides doing 110.Fn fd_getfile 111also check if the descriptor is a socket or a vnode respectively, 112return the proper errno on error and increase the use count with 113.Fn FREF . 114.Sh CONCURRENT ACCESS 115Since multiple processes can share the same file descriptor table, 116it's important that the file is not freed in one process while some 117other process is still accessing it. 118To solve that problem a special use count is kept with the functions 119.Fn FREF 120and 121.Fn FRELE . 122In most cases 123.Fn FREF 124should be used on a file after it has been extracted 125from the file descriptor table and 126.Fn FRELE 127should be called when the file won't be used anymore. 128There are cases when this isn't necessary, but since 129.Fn FREF 130and 131.Fn FRELE 132are cheap to use, there is no reason to risk introducing bugs by 133not using them. 134.Sh CODE REFERENCES 135The majority of those functions are implemented in 136.Pa sys/kern/kern_descrip.c . 137The function prototypes and the macros are located in 138.Pa sys/sys/file.h 139and 140.Pa sys/sys/filedesc.h . 141.Sh SEE ALSO 142.Xr vnode 9 143