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