filedesc(9)
- NetBSD Manual Pages
FILEDESC(9) NetBSD Kernel Developer's Manual FILEDESC(9)
NAME
filedesc, dupfdopen, falloc, fd_getfile, fdalloc, fdavail, fdcheckstd,
fdclear, fdcloseexec, fdcopy, fdexpand, fdfree, fdinit, fdrelease,
fdremove, fdshare, fdunshare - file descriptor tables and operations
SYNOPSIS
#include <sys/file.h>
#include <sys/filedesc.h>
int
falloc(struct proc *p, struct file **resultfp, int *resultfd);
struct file *
fd_getfile(struct filedesc *fdp, int fd);
int
dupfdopen(struct proc *p, int indx, int dfd, int mode, int error);
int
fdalloc(struct proc *p, int want, int *result);
int
fdavail(struct proc *p, int n);
int
fdcheckstd(struct proc *p);
void
fdclear(struct proc *p);
void
fdcloseexec(struct proc *p);
struct filedesc *
fdcopy(struct proc *p);
void
fdexpand(struct proc *p);
void
fdfree(struct proc *p);
struct filedesc *
fdinit(struct proc *p);
int
fdrelease(struct proc *p, int fd);
void
fdremove(struct filedesc *fdp, int fd);
void
fdshare(struct proc *p1, struct proc *p2);
void
fdunshare(struct proc *p);
DESCRIPTION
For user processes, all I/O is done through file descriptors. These file
descriptors represent underlying objects supported by the kernel and are
created by system calls specific to the type of object. In NetBSD, three
type of objects can be represented by file descriptors: data files,
pipes, and sockets.
The kernel maintains a descriptor table for each process which is used to
translate the external representation of a file descriptor into an inter-
nal representation. The file descriptor is merely an index into this ta-
ble. The file descriptor table maintains the following information:
· the number of descriptors allocated in the file descriptor table;
· approximate next free descriptor;
· a reference count on the file descriptor table; and
· an array of open file entries.
On creation of the file descriptor table, a fixed number of file entries
are created. It is the responsibility of the file descriptor operations
to expand the available number of entries if more are required. Each
file entry in the descriptor table contains the information necessary to
access the underlying object and to maintain common information. See
file(9) for details of operations on the file entries.
New file descriptors are generally allocated by falloc() and freed by
fdrelease(). File entries are extracted from the file descriptor table
by fd_getfile(). Most of the remaining functions in the interface are
purpose specific and perform lower-level file descriptor operations.
FUNCTIONS
The following functions are high-level interface routines to access the
file descriptor table for a process and its file entries.
falloc(p, *resultfp, *resultfd)
Create a new open file entry and allocate a file descriptor for
process p. This operation is performed by invoking fdalloc() to
allocate the new file descriptor. The credential on the file
entry are inherited from process p. The falloc() function is
responsible for expanding the file descriptor table when neces-
sary.
A pointer to the file entry is returned in *resultfp and the
file descriptor is returned in *resultfd. The falloc() function
returns zero on success, otherwise an appropriate error is
returned.
fd_getfile(fdp, fd)
Get the file entry for file descriptor fd in the file descriptor
table fdp. The file entry is returned if it is valid and use-
able, otherwise NULL is returned.
dupfdopen(p, indx, dfd, mode, error)
Duplicate file descriptor dfd for process p.
The following functions operate on the file descriptor table for a
process.
fdalloc(p, want, *result)
Allocate a file descriptor want
for process p. The resultant file descriptor is returned in
*result. The fdalloc() function returns zero on success, other-
wise an appropriate error is returned.
fdavail(p, n)
Check to see whether n file descriptors are available to process
p. Returns zero on success, or 1 on failure.
fdcheckstd(p)
Check the standard file descriptors 0, 1, 2 and ensure they are
referencing valid file descriptors. If they are not, create
references to /dev/null. This operation is necessary as these
file descriptors are given implicit significance in the Standard
C Library and it is unsafe for setuid(2) and setgid(2) processes
to be started with these file descriptors closed.
fdclear(p)
Clear the descriptor table for process p. This operation is
performed by invoking fdinit() to initialise a new file descrip-
tor table to replace the old file descriptor table and invoking
fdfree() to release the old one.
fdcloseexec(p)
Close any files for process p that are marked ``close on exec''.
This operation is performed by invoking fdunshare() for the
process and invoking fdrelease() on the appropriate file
descriptor.
fdcopy(p)
Copy the file descriptor table from process p and return a
pointer to the copy. The returned file descriptor is guaranteed
to have a reference count of one. All file descriptor state is
maintained. The reference counts on each file entry referenced
by the file descriptor table is incremented accordingly.
fdexpand(p)
Expand the file descriptor table for process p by allocating
memory for additional file descriptors.
fdfree(p)
Decrement the reference count on the file descriptor table for
process p and release the file descriptor table if the reference
count drops to zero.
fdinit(p)
Create a file descriptor table using the same current and root
directories of process p. The returned file descriptor table is
guaranteed to have a reference count of one.
fdrelease(p, fd)
Remove file descriptor fd from the file descriptor table of
process p. The operation is performed by invoking closef().
fdremove(fdp, fd)
Unconditionally remove the file descriptor fd from file descrip-
tor table fdp.
fdshare(p1, p2)
Share the file descriptor table belonging to process p1 with
process p2. Process p2 is assumed not to have a file descriptor
table already allocated. The reference count on the file
descriptor table is incremented. This function is used by
fork1(9).
fdunshare(p)
Ensure that process p does not share its file descriptor table.
If its file descriptor table has more than one reference, the
file descriptor table is copied by invoking fdcopy(). The ref-
erence count on the original file descriptor table is decre-
mented.
RETURN VALUES
Successful operations return zero. A failed operation will return a non-
zero return value. Possible values include:
[EBADF] Bad file descriptor specified.
[EMFILE] Cannot exceed file descriptor limit.
[ENOSPC] No space left in file descriptor table.
CODE REFERENCES
This section describes places within the NetBSD source tree where actual
code implementing or using file descriptors can be found. All pathnames
are relative to /usr/src.
The framework for file descriptor handling is implemented within the file
sys/kern/kern_descrip.c.
SEE ALSO
file(9)
NetBSD 2.0.2 October 12, 2002 NetBSD 2.0.2
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.