1.\" $NetBSD: file.9,v 1.4 2002/10/20 20:21:07 gmcgarry Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 12, 2002 38.Dt FILE 9 39.Os 40.Sh NAME 41.Nm file , 42.Nm closef , 43.Nm ffree , 44.Nm FILE_IS_USABLE , 45.Nm FILE_USE , 46.Nm FILE_UNUSE , 47.Nm FILE_SET_MATURE 48.Nd operations on file entries 49.Sh SYNOPSIS 50.Fd #include \*[Lt]sys/file.h\*[Gt] 51.Ft int 52.Fn closef "struct file *fp" "struct proc *p" 53.Ft void 54.Fn ffree "struct file *fp" 55.Ft int 56.Fn FILE_IS_USABLE "struct file *fp" 57.Ft void 58.Fn FILE_USE "struct file *fp" 59.Ft void 60.Fn FILE_UNUSE "struct file *fp" "struct proc *p" 61.Ft void 62.Fn FILE_SET_MATURE "struct file *fp" 63.Sh DESCRIPTION 64The file descriptor table of a process references a file entry for 65each file used by the kernel. 66See 67.Xr filedesc 9 68for details of the file descriptor table. 69Each file entry is given by: 70.Pp 71.Bd -literal 72struct file { 73 LIST_ENTRY(file) f_list; /* list of active files */ 74 int f_flag; 75 int f_iflags; /* internal flags */ 76 int f_type; /* descriptor type */ 77 u_int f_count; /* reference count */ 78 u_int f_msgcount; /* message queue references */ 79 int f_usecount; /* number active users */ 80 struct ucred *f_cred; /* associated creds */ 81 struct fileops { 82 int (*fo_read)(struct file *fp, off_t *offset, 83 struct uio *uio, struct ucred *cred, int flags); 84 int (*fo_write)(struct file *fp, off_t *offset, 85 struct uio *uio, struct ucred *cred, int flags); 86 int (*fo_ioctl)(struct file *fp, u_long com, caddr_t data, 87 struct proc *p); 88 int (*fo_fcntl)(struct file *fp, u_int com, caddr_t data, 89 struct proc *p); 90 int (*fo_poll)(struct file *fp, int events, 91 struct proc *p); 92 int (*fo_stat)(struct file *fp, struct stat *sp, 93 struct proc *p); 94 int (*fo_close)(struct file *fp, struct proc *p); 95 } *f_ops; 96 off_t f_offset; 97 caddr_t f_data; /* descriptor data */ 98}; 99.Ed 100.Pp 101.Nx 102treats file entries in an object-oriented fashion after they are created. 103Each entry specifies the object type, 104.Em f_type , 105which can have the values 106.Dv DTYPE_VNODE , 107.Dv DTYPE_SOCKET , 108.Dv DTYPE_PIPE 109and 110.Dv DTYPE_MISC . 111The file entry also has a pointer to a data structure, 112.Em f_data , 113that contains information specific to the instance of the underlying object. 114The data structure is opaque to the routines that manipulate the file entry. 115Each entry also contains an array of function pointers, 116.Em f_ops , 117that translate the generic operations on a file descriptor into the 118specific action associated with its type. 119A reference to the data structure is passed as the first parameter to a 120function that implements a file operation. 121The operations that must be implemented for each descriptor type are 122read, write, ioctl, fcntl, poll, stat, and close. 123See 124.Xr vnfileops 9 125for an overview of the vnode file operations. 126All state associated with an instance of an object must be stored in 127that instance's data structure; the underlying objects are not permitted 128to manipulate the file entry themselves. 129.Pp 130For data files, the file entry points to a 131.Xr vnode 9 132structure. 133Pipes and sockets do not have data blocks allocated on the disk and 134are handled by the special-device filesystem that calls appropriate 135drivers to handle I/O for them. 136For pipes, the file entry points to a system block that is used during 137data transfer. 138For sockets, the file entry points to a system block that is used in 139doing interprocess communications. 140.Pp 141The descriptor table of a process (and thus access to the objects to 142which the descriptors refer) is inherited from its parent, so several 143different processes may reference the same file entry. 144Thus, each file entry has a reference count, 145.Em f_count . 146Each time a new reference is created, the reference count is incremented. 147When a descriptor is closed, the reference count is decremented. 148When the reference count drops to zero, the file entry is freed. 149.Pp 150Some file descriptor semantics can be altered through the 151.Ar flags 152argument to the 153.Xr open 2 154system call. 155These flags are recorded in 156.Em f_flags 157member of the file entry. 158For example, the flags record whether the descriptor is open for 159reading, writing, or both reading and writing. 160The following flags and their corresponding 161.Xr open 2 162flags are: 163.Pp 164.Bl -tag -offset indent -width FNONBLOCK -compact 165.It FAPPEND 166.Dv O_APPEND 167.It FASYNC 168.Dv O_ASYNC 169.It O_FSYNC 170.Dv O_SYNC 171.It FNDELAY 172.Dv O_NONBLOCK 173.It O_NDELAY 174.Dv O_NONBLOCK 175.It FNONBLOCK 176.Dv O_NONBLOCK 177.It FFSYNC 178.Dv O_SYNC 179.It FDSYNC 180.Dv O_DSYNC 181.It FRSYNC 182.Dv O_RSYNC 183.It FALTIO 184.Dv O_ALT_IO 185.El 186.Pp 187Some additional state-specific flags are recorded in the 188.Em f_iflags 189member. 190Valid values include: 191.Pp 192.Bl -tag -offset indent -width FIF_WANTCLOSE -compact 193.It FIF_WANTCLOSE 194If set, then the reference count on the file is zero, but there were 195multiple users of the file. 196This can happen if a file descriptor table is shared by multiple processes. 197This flag notifies potential users that the file is closing and will 198prevent them from adding additional uses to the file. 199.It FIF_LARVAL 200The file entry is not fully constructed (mature) and should not be used. 201.El 202.Pp 203The 204.Xr read 2 205and 206.Xr write 2 207system calls do not take an offset in the file as an argument. 208Instead, each read or write updates the current file offset, 209.Em f_offset 210in the file according to the number of bytes transferred. 211Since more than one process may open the same file and each needs its 212own offset in the file, the offset cannot be stored in the per-object 213data structure. 214.Sh FUNCTIONS 215.Bl -tag -width compact 216.It Fn closef "fp" "p" 217The internal form of 218.Xr close 2 219which decrements the reference count on file entry 220.Fa fp . 221The 222.Fn closef 223function release all locks on the file owned by process 224.Fa p , 225decrements the reference count on the file entry, and invokes 226.Fn ffree 227to free the file entry. 228.It Fn ffree "struct file *fp" 229Free file entry 230.Fa fp . 231The file entry was created in 232.Xr falloc 9 . 233.It Fn FILE_IS_USABLE "fp" 234Ensure that the file entry is useable by ensuring that neither the 235FIF_WANTCLOSE and FIF_LARVAL flags are not set in 236.Em f_iflags . 237.It Fn FILE_USE "fp" 238Increment the reference count on file entry 239.Fa fp . 240.It Fn FILE_UNUSE "fp" "p" 241Decrement the reference count on file entry 242.Fa fp . 243If the FIF_WANTCLOSE 244flag is set in 245.Em f_iflags , 246the file entry is freed. 247.It Fn FILE_SET_MATURE "fp" 248Mark the file entry as being fully constructed (mature) by clearing 249the FIF_LARVAL flag in 250.Em f_iflags . 251.El 252.Sh CODE REFERENCES 253This section describes places within the 254.Nx 255source tree where actual code implementing or utilising file entries 256can be found. 257All pathnames are relative to 258.Pa /usr/src . 259.Pp 260The framework for file entry handling is implemented within the file 261.Pa sys/kern/kern_descrip.c . 262.Sh SEE ALSO 263.Xr dofileread 9 , 264.Xr filedesc 9 , 265.Xr vnfileops 9 , 266.Xr vnode 9 267