1.\" $OpenBSD: file.9,v 1.16 2015/11/23 17:53:57 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: November 23 2015 $ 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" "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 descriptor is allocated with the function 70.Fn falloc 71and freed with 72.Fn fdrelease . 73.Fn falloc 74and 75.Fn fdrelease 76deal with allocating and freeing slots in the file descriptor table, 77expanding the table when necessary and initializing the descriptor. 78It's possible to do those things in smaller steps, but it's not 79recommended to make complicated kernel APIs that require it. 80.Pp 81The files are extracted from the file descriptor table using the 82functions 83.Fn fd_getfile 84.Fn fd_getfile 85performs all necessary checks to see if the file descriptor number is 86within the range of file descriptor table, and if the descriptor is 87valid. 88.Pp 89The files are extracted from the process context using the 90function 91.Fn getsock 92and 93.Fn getvnode . 94These functions are special cases that besides doing 95.Fn fd_getfile 96also check if the descriptor is a socket or a vnode respectively, 97return the proper errno on error and increase the use count with 98.Fn FREF . 99.Sh CONCURRENT ACCESS 100Since multiple processes can share the same file descriptor table, 101it's important that the file is not freed in one process while some 102other process is still accessing it. 103To solve that problem a special use count is kept with the functions 104.Fn FREF 105and 106.Fn FRELE . 107In most cases 108.Fn FREF 109should be used on a file after it has been extracted 110from the file descriptor table and 111.Fn FRELE 112should be called when the file won't be used anymore. 113There are cases when this isn't necessary, but since 114.Fn FREF 115and 116.Fn FRELE 117are cheap to use, there is no reason to risk introducing bugs by 118not using them. 119.Sh CODE REFERENCES 120The majority of those functions are implemented in 121.Pa sys/kern/kern_descrip.c . 122The function prototypes and the macros are located in 123.Pa sys/sys/file.h 124and 125.Pa sys/sys/filedesc.h . 126.Sh SEE ALSO 127.Xr vnode 9 128