diff options
Diffstat (limited to 'static/netbsd/man9/file.9')
| -rw-r--r-- | static/netbsd/man9/file.9 | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/static/netbsd/man9/file.9 b/static/netbsd/man9/file.9 new file mode 100644 index 00000000..a4e08ada --- /dev/null +++ b/static/netbsd/man9/file.9 @@ -0,0 +1,256 @@ +.\" $NetBSD: file.9,v 1.19 2017/04/23 11:37:29 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 17, 2009 +.Dt FILE 9 +.Os +.Sh NAME +.Nm file , +.Nm closef , +.Nm ffree , +.Nm FILE_IS_USABLE , +.Nm FILE_USE , +.Nm FILE_UNUSE , +.Nm FILE_SET_MATURE +.Nd operations on file entries +.Sh SYNOPSIS +.In sys/file.h +.Ft int +.Fn closef "struct file *fp" "struct lwp *l" +.Ft void +.Fn ffree "struct file *fp" +.Ft int +.Fn FILE_IS_USABLE "struct file *fp" +.Ft void +.Fn FILE_USE "struct file *fp" +.Ft void +.Fn FILE_UNUSE "struct file *fp" "struct lwp *l" +.Ft void +.Fn FILE_SET_MATURE "struct file *fp" +.Sh DESCRIPTION +The file descriptor table of a process references a file entry for +each file used by the kernel. +See +.Xr filedesc 9 +for details of the file descriptor table. +Each file entry is given by: +.Bd -literal +struct file { + LIST_ENTRY(file) f_list; /* list of active files */ + int f_flag; + int f_iflags; /* internal flags */ + int f_type; /* descriptor type */ + u_int f_count; /* reference count */ + u_int f_msgcount; /* message queue references */ + int f_usecount; /* number active users */ + kauth_cred_t f_cred; /* creds associated with descriptor */ + struct fileops { + int (*fo_read)(struct file *fp, off_t *offset, + struct uio *uio, kauth_cred_t cred, int flags); + int (*fo_write)(struct file *fp, off_t *offset, + struct uio *uio, kauth_cred_t cred, int flags); + int (*fo_ioctl)(struct file *fp, u_long com, void *data, + struct lwp *l); + int (*fo_fcntl)(struct file *fp, u_int com, void *data, + struct lwp *l); + int (*fo_poll)(struct file *fp, int events, + struct lwp *l); + int (*fo_stat)(struct file *fp, struct stat *sp, + struct lwp *l); + int (*fo_close)(struct file *fp, struct lwp *l); + } *f_ops; + off_t f_offset; + void *f_data; /* descriptor data */ +}; +.Ed +.Pp +.Nx +treats file entries in an object-oriented fashion after they are created. +Each entry specifies the object type, +.Em f_type , +which can have the values +.Dv DTYPE_VNODE , +.Dv DTYPE_SOCKET , +.Dv DTYPE_PIPE +and +.Dv DTYPE_MISC . +The file entry also has a pointer to a data structure, +.Em f_data , +that contains information specific to the instance of the underlying object. +The data structure is opaque to the routines that manipulate the file entry. +Each entry also contains an array of function pointers, +.Em f_ops , +that translate the generic operations on a file descriptor into the +specific action associated with its type. +A reference to the data structure is passed as the first parameter to a +function that implements a file operation. +The operations that must be implemented for each descriptor type are +read, write, ioctl, fcntl, poll, stat, and close. +See +.Xr vnfileops 9 +for an overview of the vnode file operations. +All state associated with an instance of an object must be stored in +that instance's data structure; the underlying objects are not permitted +to manipulate the file entry themselves. +.Pp +For data files, the file entry points to a +.Xr vnode 9 +structure. +Pipes and sockets do not have data blocks allocated on the disk and +are handled by the special-device filesystem that calls appropriate +drivers to handle I/O for them. +For pipes, the file entry points to a system block that is used during +data transfer. +For sockets, the file entry points to a system block that is used in +doing interprocess communications. +.Pp +The descriptor table of a process (and thus access to the objects to +which the descriptors refer) is inherited from its parent, so several +different processes may reference the same file entry. +Thus, each file entry has a reference count, +.Em f_count . +Each time a new reference is created, the reference count is incremented. +When a descriptor is closed, the reference count is decremented. +When the reference count drops to zero, the file entry is freed. +.Pp +Some file descriptor semantics can be altered through the +.Ar flags +argument to the +.Xr open 2 +system call. +These flags are recorded in +.Em f_flags +member of the file entry. +For example, the flags record whether the descriptor is open for +reading, writing, or both reading and writing. +The following flags and their corresponding +.Xr open 2 +flags are: +.Pp +.Bl -tag -offset indent -width FNONBLOCK -compact +.It FAPPEND +.Dv O_APPEND +.It FASYNC +.Dv O_ASYNC +.It O_FSYNC +.Dv O_SYNC +.It FNDELAY +.Dv O_NONBLOCK +.It O_NDELAY +.Dv O_NONBLOCK +.It FNONBLOCK +.Dv O_NONBLOCK +.It FFSYNC +.Dv O_SYNC +.It FDSYNC +.Dv O_DSYNC +.It FRSYNC +.Dv O_RSYNC +.It FALTIO +.Dv O_ALT_IO +.El +.Pp +Some additional state-specific flags are recorded in the +.Em f_iflags +member. +Valid values include: +.Pp +.Bl -tag -offset indent -width FIF_WANTCLOSE -compact +.It Dv FIF_WANTCLOSE +If set, then the reference count on the file is zero, but there were +multiple users of the file. +This can happen if a file descriptor table is shared by multiple processes. +This flag notifies potential users that the file is closing and will +prevent them from adding additional uses to the file. +.It Dv FIF_LARVAL +The file entry is not fully constructed (mature) and should not be used. +.El +.Pp +The +.Xr read 2 +and +.Xr write 2 +system calls do not take an offset in the file as an argument. +Instead, each read or write updates the current file offset, +.Em f_offset +in the file according to the number of bytes transferred. +Since more than one process may open the same file and each needs its +own offset in the file, the offset cannot be stored in the per-object +data structure. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn closef "fp" "l" +The internal form of +.Xr close 2 +which decrements the reference count on file entry +.Fa fp . +The +.Fn closef +function release all locks on the file owned by lwp +.Fa l , +decrements the reference count on the file entry, and invokes +.Fn ffree +to free the file entry. +.It Fn ffree "struct file *fp" +Free file entry +.Fa fp . +The file entry was created in +.Xr falloc 9 . +.It Fn FILE_IS_USABLE "fp" +Ensure that the file entry is usable by ensuring that neither the +.Dv FIF_WANTCLOSE +flag nor the +.Dv FIF_LARVAL +flag is set in +.Em f_iflags . +.It Fn FILE_USE "fp" +Increment the reference count on file entry +.Fa fp . +.It Fn FILE_UNUSE "fp" "l" +Decrement the reference count on file entry +.Fa fp . +If the +.Dv FIF_WANTCLOSE +flag is set in +.Em f_iflags , +the file entry is freed. +.It Fn FILE_SET_MATURE "fp" +Mark the file entry as being fully constructed (mature) by clearing the +.Dv FIF_LARVAL +flag in +.Em f_iflags . +.El +.Sh CODE REFERENCES +The framework for file entry handling is implemented within the file +.Pa sys/kern/kern_descrip.c . +.Sh SEE ALSO +.Xr dofileread 9 , +.Xr filedesc 9 , +.Xr vnfileops 9 , +.Xr vnode 9 |