1.\" $OpenBSD: file.9,v 1.10 2007/05/31 19:20:00 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: May 31 2007 $ 26.Dt FILE 9 27.Os 28.Sh NAME 29.Nm file 30.Nd an overview of file descriptor handling 31.Sh SYNOPSIS 32.Fd #include <sys/file.h> 33.Fd #include <sys/filedesc.h> 34.Ft int 35.Fn falloc "struct proc *p" "struct file **resultfp" "int *resultfd" 36.Ft int 37.Fn fdrelease "struct proc *p" "int fd" 38.Ft void 39.Fn FREF "struct file *fp" 40.Ft void 41.Fn FRELE "struct file *fp" 42.Ft struct file * 43.Fn fd_getfile "struct filedesc *fdp" "int fd" 44.Ft int 45.Fn getsock "struct filedesc *fdp" "int fd" "struct file **fpp" 46.Fd #include <sys/file.h> 47.Fd #include <sys/filedesc.h> 48.Fd #include <sys/vnode.h> 49.Ft int 50.Fn getvnode "struct filedesc *fdp" "int fd" "struct file **fpp" 51.Sh DESCRIPTION 52These functions provide the interface for the UNIX file descriptors. 53File descriptors can be used to access vnodes (see 54.Xr vnode 9 ) , 55sockets (see 56.Xr socket 2 ) , 57pipes (see 58.Xr pipe 2 ) , 59kqueues (see 60.Xr kqueue 2 ) , 61and various special purpose communication endpoints. 62.Pp 63A new file descriptor is allocated with the function 64.Fn falloc 65and freed with 66.Fn fdrelease . 67.Fn falloc 68and 69.Fn fdrelease 70deal with allocating and freeing slots in the file descriptor table, 71expanding the table when necessary and initializing the descriptor. 72It's possible to do those things in smaller steps, but it's not 73recommended to make complicated kernel APIs that require it. 74.Pp 75The files are extracted from the file descriptor table using the 76functions 77.Fn fd_getfile , 78.Fn getvnode 79and 80.Fn getsock . 81.Fn fd_getfile 82performs all necessary checks to see if the file descriptor number is 83within the range of file descriptor table, and if the descriptor is 84valid. 85.Fn getsock 86and 87.Fn getvnode 88are special cases that besides doing 89.Fn fd_getfile 90also check if the descriptor is a vnode or socket, return the proper 91errno on error and increase the use count with 92.Fn FREF . 93.Sh CONCURRENT ACCESS 94Since multiple processes can share the same file descriptor table, 95it's important that the file is not freed in one process while some 96other process is still accessing it. 97To solve that problem a special use count is kept with the functions 98.Fn FREF 99and 100.Fn FRELE . 101In most cases 102.Fn FREF 103should be used on a file after it has been extracted 104from the file descriptor table and 105.Fn FRELE 106should be called when the file won't be used anymore. 107There are cases when this isn't necessary, but since 108.Fn FREF 109and 110.Fn FRELE 111are cheap to use, there is no reason to risk introducing bugs by 112not using them. 113.Sh CODE REFERENCES 114The majority of those functions are implemented in 115.Pa sys/kern/kern_descrip.c . 116The function prototypes and the macros are located in 117.Pa sys/sys/file.h 118and 119.Pa sys/sys/filedesc.h . 120.Sh SEE ALSO 121.Xr vnode 9 122