1.\" $NetBSD: file.9,v 1.14 2010/12/02 12:54:13 wiz 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 17, 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.Nd operations on file entries 42.Sh SYNOPSIS 43.In sys/file.h 44.Ft int 45.Fn closef "struct file *fp" "struct lwp *l" 46.Ft void 47.Fn ffree "struct file *fp" 48.Ft int 49.Fn FILE_IS_USABLE "struct file *fp" 50.Ft void 51.Fn FILE_USE "struct file *fp" 52.Ft void 53.Fn FILE_UNUSE "struct file *fp" "struct lwp *l" 54.Ft void 55.Fn FILE_SET_MATURE "struct file *fp" 56.Sh DESCRIPTION 57The file descriptor table of a process references a file entry for 58each file used by the kernel. 59See 60.Xr filedesc 9 61for details of the file descriptor table. 62Each file entry is given by: 63.Pp 64.Bd -literal 65struct file { 66 LIST_ENTRY(file) f_list; /* list of active files */ 67 int f_flag; 68 int f_iflags; /* internal flags */ 69 int f_type; /* descriptor type */ 70 u_int f_count; /* reference count */ 71 u_int f_msgcount; /* message queue references */ 72 int f_usecount; /* number active users */ 73 kauth_cred_t f_cred; /* creds associated with descriptor */ 74 struct fileops { 75 int (*fo_read)(struct file *fp, off_t *offset, 76 struct uio *uio, kauth_cred_t cred, int flags); 77 int (*fo_write)(struct file *fp, off_t *offset, 78 struct uio *uio, kauth_cred_t cred, int flags); 79 int (*fo_ioctl)(struct file *fp, u_long com, void *data, 80 struct lwp *l); 81 int (*fo_fcntl)(struct file *fp, u_int com, void *data, 82 struct lwp *l); 83 int (*fo_poll)(struct file *fp, int events, 84 struct lwp *l); 85 int (*fo_stat)(struct file *fp, struct stat *sp, 86 struct lwp *l); 87 int (*fo_close)(struct file *fp, struct lwp *l); 88 } *f_ops; 89 off_t f_offset; 90 void *f_data; /* descriptor data */ 91}; 92.Ed 93.Pp 94.Nx 95treats file entries in an object-oriented fashion after they are created. 96Each entry specifies the object type, 97.Em f_type , 98which can have the values 99.Dv DTYPE_VNODE , 100.Dv DTYPE_SOCKET , 101.Dv DTYPE_PIPE 102and 103.Dv DTYPE_MISC . 104The file entry also has a pointer to a data structure, 105.Em f_data , 106that contains information specific to the instance of the underlying object. 107The data structure is opaque to the routines that manipulate the file entry. 108Each entry also contains an array of function pointers, 109.Em f_ops , 110that translate the generic operations on a file descriptor into the 111specific action associated with its type. 112A reference to the data structure is passed as the first parameter to a 113function that implements a file operation. 114The operations that must be implemented for each descriptor type are 115read, write, ioctl, fcntl, poll, stat, and close. 116See 117.Xr vnfileops 9 118for an overview of the vnode file operations. 119All state associated with an instance of an object must be stored in 120that instance's data structure; the underlying objects are not permitted 121to manipulate the file entry themselves. 122.Pp 123For data files, the file entry points to a 124.Xr vnode 9 125structure. 126Pipes and sockets do not have data blocks allocated on the disk and 127are handled by the special-device filesystem that calls appropriate 128drivers to handle I/O for them. 129For pipes, the file entry points to a system block that is used during 130data transfer. 131For sockets, the file entry points to a system block that is used in 132doing interprocess communications. 133.Pp 134The descriptor table of a process (and thus access to the objects to 135which the descriptors refer) is inherited from its parent, so several 136different processes may reference the same file entry. 137Thus, each file entry has a reference count, 138.Em f_count . 139Each time a new reference is created, the reference count is incremented. 140When a descriptor is closed, the reference count is decremented. 141When the reference count drops to zero, the file entry is freed. 142.Pp 143Some file descriptor semantics can be altered through the 144.Ar flags 145argument to the 146.Xr open 2 147system call. 148These flags are recorded in 149.Em f_flags 150member of the file entry. 151For example, the flags record whether the descriptor is open for 152reading, writing, or both reading and writing. 153The following flags and their corresponding 154.Xr open 2 155flags are: 156.Pp 157.Bl -tag -offset indent -width FNONBLOCK -compact 158.It FAPPEND 159.Dv O_APPEND 160.It FASYNC 161.Dv O_ASYNC 162.It O_FSYNC 163.Dv O_SYNC 164.It FNDELAY 165.Dv O_NONBLOCK 166.It O_NDELAY 167.Dv O_NONBLOCK 168.It FNONBLOCK 169.Dv O_NONBLOCK 170.It FFSYNC 171.Dv O_SYNC 172.It FDSYNC 173.Dv O_DSYNC 174.It FRSYNC 175.Dv O_RSYNC 176.It FALTIO 177.Dv O_ALT_IO 178.El 179.Pp 180Some additional state-specific flags are recorded in the 181.Em f_iflags 182member. 183Valid values include: 184.Pp 185.Bl -tag -offset indent -width FIF_WANTCLOSE -compact 186.It FIF_WANTCLOSE 187If set, then the reference count on the file is zero, but there were 188multiple users of the file. 189This can happen if a file descriptor table is shared by multiple processes. 190This flag notifies potential users that the file is closing and will 191prevent them from adding additional uses to the file. 192.It FIF_LARVAL 193The file entry is not fully constructed (mature) and should not be used. 194.El 195.Pp 196The 197.Xr read 2 198and 199.Xr write 2 200system calls do not take an offset in the file as an argument. 201Instead, each read or write updates the current file offset, 202.Em f_offset 203in the file according to the number of bytes transferred. 204Since more than one process may open the same file and each needs its 205own offset in the file, the offset cannot be stored in the per-object 206data structure. 207.Sh FUNCTIONS 208.Bl -tag -width compact 209.It Fn closef "fp" "l" 210The internal form of 211.Xr close 2 212which decrements the reference count on file entry 213.Fa fp . 214The 215.Fn closef 216function release all locks on the file owned by lwp 217.Fa l , 218decrements the reference count on the file entry, and invokes 219.Fn ffree 220to free the file entry. 221.It Fn ffree "struct file *fp" 222Free file entry 223.Fa fp . 224The file entry was created in 225.Xr falloc 9 . 226.It Fn FILE_IS_USABLE "fp" 227Ensure that the file entry is useable by ensuring that neither the 228FIF_WANTCLOSE and FIF_LARVAL flags are not set in 229.Em f_iflags . 230.It Fn FILE_USE "fp" 231Increment the reference count on file entry 232.Fa fp . 233.It Fn FILE_UNUSE "fp" "l" 234Decrement the reference count on file entry 235.Fa fp . 236If the FIF_WANTCLOSE 237flag is set in 238.Em f_iflags , 239the file entry is freed. 240.It Fn FILE_SET_MATURE "fp" 241Mark the file entry as being fully constructed (mature) by clearing 242the FIF_LARVAL flag in 243.Em f_iflags . 244.El 245.Sh CODE REFERENCES 246The framework for file entry handling is implemented within the file 247.Pa sys/kern/kern_descrip.c . 248.Sh SEE ALSO 249.Xr dofileread 9 , 250.Xr filedesc 9 , 251.Xr vnfileops 9 , 252.Xr vnode 9 253