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