FALLOC(9) | Kernel Developer's Manual | FALLOC(9)

# 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.

# SEE ALSO

vnode(9)

November 9, 2024 | Debian