NAME
falloc, fdrelease,
FREF, FRELE,
fd_getfile, fd_getfile_mode,
fd_checkclosed, getsock,
getvnode —
an overview of file descriptor
handling
SYNOPSIS
#include
<sys/file.h>
#include <sys/filedesc.h>
int
falloc(struct
proc *p, struct file
**resultfp, int
*resultfd);
int
fdrelease(struct
proc *p, int
fd);
void
FREF(struct
file *fp);
int
FRELE(struct
file *fp, struct proc
*p);
struct file *
fd_getfile(struct
filedesc *fdp, int
fd);
struct file *
fd_getfile_mode(struct
filedesc *fdp, int
fd, int mode);
int
fd_checkclosed(struct
filedesc *fdp, int
fd, struct file
*fp);
int
getsock(struct
proc *p, int fd,
struct file **fpp);
#include
<sys/file.h>
#include <sys/filedesc.h>
#include <sys/vnode.h>
int
getvnode(struct
proc *p, int fd,
struct file **fpp);
DESCRIPTION
These functions provide the interface for the UNIX file descriptors. File descriptors can be used to access vnodes (see vnode(9)), sockets (see socket(2)), pipes (see pipe(2)), kqueues (see kqueue(2)), and various special purpose communication endpoints.
A new file and a file descriptor for it are allocated
with the function
falloc().
The larval file and fd are returned via resultfp and
resultfd, which must not be
NULL. falloc() initializes
the new file to have a reference count of two: one for the reference from
the file descriptor table and one for the caller to release with
FRELE()
when it's done initializing it.
A file descriptor is freed with
fdrelease().
This releases the reference that it holds to the underlying file; if that's
the last reference then the file will be freed. The file descriptor table
has to be locked on entry. fdrelease() unlocks the
table on return.
The files are extracted from the file descriptor
table using the function
fd_getfile().
fd_getfile() performs all necessary checks to see if
the file descriptor number is within the range of file descriptor table, and
if the descriptor is valid. It also increases the descriptor's use count
with
FREF().
fd_getfile_mode()
is like fd_getfile() but also checks if the file has
been opened with the given mode.
fd_checkclosed()
checks if file descriptor fd has been closed and no
longer points to file fp. The file must have been
retrieved from the descriptor previously.
The files are extracted from the process context
using the function
getsock()
and
getvnode().
These functions are special cases that besides doing
fd_getfile() also check if the descriptor is a
socket or a vnode respectively, and return the proper errno on error.
CONCURRENT ACCESS
Since multiple processes can share the same file descriptor table,
it's important that the file is not freed in one process while some other
process is still accessing it. To solve that problem a special use count is
kept with the functions FREF() and
FRELE(). The function FREF()
increases the use count of a file descriptor. The function
FRELE() decreases the use count, and releases the
file descriptor if the use count becomes zero.
CODE REFERENCES
The majority of those functions are implemented in sys/kern/kern_descrip.c. The function prototypes and the macros are located in sys/sys/file.h and sys/sys/filedesc.h.