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