filedesc(9)
- NetBSD Manual Pages
FILEDESC(9) NetBSD Kernel Developer's Manual FILEDESC(9)
NAME
filedesc, fd_alloc, fd_checkstd, fd_clone, fd_closeexec, fd_copy, fd_dup,
fd_dup2, fd_dupopen, fd_free, fd_init, fd_getfile, fd_share, fd_tryexpand
-- file descriptor tables and operations
SYNOPSIS
#include <sys/file.h>
#include <sys/filedesc.h>
int
fd_alloc(proc_t *p, int want, int *result);
int
fd_checkstd(void);
int
fd_clone(file_t *fp, int fd, int flag, const struct fileops *fops,
void *data);
filedesc_t *
fd_copy(void);
void
fd_closeexec(void);
int
fd_dup(file_t *fp, int minfd, int *newp, bool exclose);
int
fd_dup2(file_t *fp, unsigned newfd, int flags);
int
fd_dupopen(int old, int *newp, int error);
void
fd_free(void);
filedesc_t *
fd_init(filedesc_t *fdp);
file_t *
fd_getfile(unsigned fd);
void
fd_share(proc_t *p);
void
fd_tryexpand(proc_t *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, six
types of objects can be represented by file descriptors: data files,
pipes, sockets, event queues, crypto, and miscellaneous.
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 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 needed 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 fd_alloc() and freed by
fd_free(). File entries are extracted from the file descriptor table by
fd_getfile(). Most of the remaining functions in the interface are pur-
pose-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.
fd_alloc(p, want, *result)
Create a new open file entry in the file descriptor table and
allocate a file descriptor for the process p. The credential on
the file entry are inherited from process p. Calling the
fd_alloc() function expands the file descriptor table when nec-
essary.
The index of the file entry is returned in *result. The
fd_alloc() function returns zero on success, or an appropriate
error value otherwise.
fd_getfile(fd)
Get the file entry for file descriptor . fd The file entry is
returned if it is valid and usable, otherwise NULL is returned.
fd_dup(fp, minfd, *newp, exclose)
Duplicate file descriptor fp for the current process. The fd
picked will be at least minfd. The resulting descriptor is
given in newp.
fd_dup2(fp, newfd, flags)
Duplicate file descriptor fp in fd number newfd. If newfd is
already in use by an open file, close it (See dup2(2)).
fd_dupopen(old, *newp, error)
Duplicate file descriptor specified in old for the current lwp.
The following functions operate on the file descriptor table for a
process.
fd_alloc(p, want, *result)
Allocate a file descriptor want for process p. The resultant
file descriptor is returned in *result. The fd_alloc() function
returns zero on success, otherwise an appropriate error is
returned.
fd_clone(fp, fd, flag, fops, data)
This function is meant to be used by devices which allocate a
file entry upon open. fd_clone() fills fp with the given param-
eters. It always returns the in-kernel errno EMOVEFD. This
special return value is interpreted by the caller of the device
open routine.
fd_closeexec(void)
Close any files for the current process that are marked ``close
on exec''. This operation is performed by invoking fd_close()
on the appropriate file descriptor.
fd_copy(void)
Copy the file descriptor table from the current process and
return a pointer to the copy. The returned file descriptor is
guaranteed to have a reference count of one. All file descrip-
tor state is maintained. The reference counts on each file
entry referenced by the file descriptor table is incremented
accordingly.
fd_tryexpand(p)
Expand the file descriptor table for process p by allocating
memory for additional file descriptors.
fd_free(void)
Decrement the reference count on the file descriptor table for
the current lwp and release the file descriptor table if the
reference count drops to zero.
fd_share(p)
Make process p share the current process's filedesc structure.
fd_checkstd(l)
Check the standard file descriptors 0, 1, and 2 and ensure they
are referencing valid file descriptors. If they are not, create
references to /dev/null. This is done to setuid/setgid executa-
bles, as file descriptors 0, 1, 2 are implicitly used by the
Standard C Library.
fd_init(fdp)
Create a file descriptor table using the same current and root
directories of the current process. The returned file descrip-
tor table is guaranteed to have a reference count of one.
RETURN VALUES
Successful operations return zero. A failed operation will return a non-
zero 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
The framework for file descriptor handling is implemented within the file
sys/kern/kern_descrip.c.
SEE ALSO
file(9)
NetBSD 10.99 April 8, 2019 NetBSD 10.99
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.