1.\" $OpenBSD: file.9,v 1.19 2018/05/17 15:21:06 visa 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: May 17 2018 $ 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 97function 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. 103It also increases the descriptor's use count with 104.Fn FREF . 105.Pp 106The files are extracted from the process context using the 107function 108.Fn getsock 109and 110.Fn getvnode . 111These functions are special cases that besides doing 112.Fn fd_getfile 113also check if the descriptor is a socket or a vnode respectively, 114and return the proper errno on error. 115.Sh CONCURRENT ACCESS 116Since multiple processes can share the same file descriptor table, 117it's important that the file is not freed in one process while some 118other process is still accessing it. 119To solve that problem a special use count is kept with the functions 120.Fn FREF 121and 122.Fn FRELE . 123The function 124.Fn FREF 125increases the use count of a file descriptor. 126The function 127.Fn FRELE 128decreases the use count, and releases the file descriptor if the use count 129becomes zero. 130.Sh CODE REFERENCES 131The majority of those functions are implemented in 132.Pa sys/kern/kern_descrip.c . 133The function prototypes and the macros are located in 134.Pa sys/sys/file.h 135and 136.Pa sys/sys/filedesc.h . 137.Sh SEE ALSO 138.Xr vnode 9 139