1.\" $NetBSD: fs.5,v 1.14 2003/08/07 10:31:16 agc Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)fs.5 8.2 (Berkeley) 4/19/94 31.\" 32.Dd July 27, 2001 33.Dt FS 5 34.Os 35.Sh NAME 36.Nm fs , 37.Nm inode 38.Nd format of file system volume 39.Sh SYNOPSIS 40.In sys/param.h 41.In ufs/ffs/fs.h 42.In ufs/ufs/inode.h 43.Sh DESCRIPTION 44The files 45.Aq Pa ufs/ffs/fs.h 46and 47.Aq Pa ufs/ufs/inode.h 48declare several structures, defined variables and macros 49which are used to create and manage the underlying format of 50file system objects on random access devices (disks). 51.Pp 52The block size and number of blocks which 53comprise a file system are parameters of the file system. 54Sectors beginning at 55.Dv BBLOCK 56and continuing for 57.Dv BBSIZE 58are used 59for a disklabel and for some hardware primary 60and secondary bootstrapping programs. 61.Pp 62The actual file system begins at sector 63.Dv SBLOCK 64with the 65.Em super-block 66that is of size 67.Dv SBSIZE . 68The following structure described the super-block and is 69from the file 70.Aq Pa ufs/ffs/fs.h : 71.Bd -literal 72#define FS_MAGIC 0x011954 73struct fs { 74 int32_t fs_firstfield; /* historic file system linked list, */ 75 int32_t fs_unused_1; /* used for incore super blocks */ 76 ufs_daddr_t fs_sblkno; /* addr of super-block in filesys */ 77 ufs_daddr_t fs_cblkno; /* offset of cyl-block in filesys */ 78 ufs_daddr_t fs_iblkno; /* offset of inode-blocks in filesys */ 79 ufs_daddr_t fs_dblkno; /* offset of first data after cg */ 80 int32_t fs_cgoffset; /* cylinder group offset in cylinder */ 81 int32_t fs_cgmask; /* used to calc mod fs_ntrak */ 82 int32_t fs_time; /* last time written */ 83 int32_t fs_size; /* number of blocks in fs */ 84 int32_t fs_dsize; /* number of data blocks in fs */ 85 int32_t fs_ncg; /* number of cylinder groups */ 86 int32_t fs_bsize; /* size of basic blocks in fs */ 87 int32_t fs_fsize; /* size of frag blocks in fs */ 88 int32_t fs_frag; /* number of frags in a block in fs */ 89/* these are configuration parameters */ 90 int32_t fs_minfree; /* minimum percentage of free blocks */ 91 int32_t fs_rotdelay; /* num of ms for optimal next block */ 92 int32_t fs_rps; /* disk revolutions per second */ 93/* these fields can be computed from the others */ 94 int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ 95 int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ 96 int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ 97 int32_t fs_fshift; /* ``numfrags'' calc number of frags */ 98/* these are configuration parameters */ 99 int32_t fs_maxcontig; /* max number of contiguous blks */ 100 int32_t fs_maxbpg; /* max number of blks per cyl group */ 101/* these fields can be computed from the others */ 102 int32_t fs_fragshift; /* block to frag shift */ 103 int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ 104 int32_t fs_sbsize; /* actual size of super block */ 105 int32_t fs_csmask; /* csum block offset */ 106 int32_t fs_csshift; /* csum block number */ 107 int32_t fs_nindir; /* value of NINDIR */ 108 int32_t fs_inopb; /* value of INOPB */ 109 int32_t fs_nspf; /* value of NSPF */ 110/* yet another configuration parameter */ 111 int32_t fs_optim; /* optimization preference, see below */ 112/* these fields are derived from the hardware */ 113 int32_t fs_npsect; /* # sectors/track including spares */ 114 int32_t fs_interleave; /* hardware sector interleave */ 115 int32_t fs_trackskew; /* sector 0 skew, per track */ 116 int32_t fs_headswitch; /* head switch time, usec (UNUSED) */ 117 int32_t fs_trkseek; /* track-to-track seek, usec (UNUSED) */ 118/* sizes determined by number of cylinder groups and their sizes */ 119 ufs_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ 120 int32_t fs_cssize; /* size of cyl grp summary area */ 121 int32_t fs_cgsize; /* cylinder group size */ 122/* these fields are derived from the hardware */ 123 int32_t fs_ntrak; /* tracks per cylinder */ 124 int32_t fs_nsect; /* sectors per track */ 125 int32_t fs_spc; /* sectors per cylinder */ 126/* this comes from the disk driver partitioning */ 127 int32_t fs_ncyl; /* cylinders in file system */ 128/* these fields can be computed from the others */ 129 int32_t fs_cpg; /* cylinders per group */ 130 int32_t fs_ipg; /* inodes per group */ 131 int32_t fs_fpg; /* blocks per group * fs_frag */ 132/* this data must be re-computed after crashes */ 133 struct csum fs_cstotal; /* cylinder summary information */ 134/* these fields are cleared at mount time */ 135 int8_t fs_fmod; /* super block modified flag */ 136 int8_t fs_clean; /* file system is clean flag */ 137 int8_t fs_ronly; /* mounted read-only flag */ 138 int8_t fs_flags; /* see FS_ flags below */ 139 u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ 140/* these fields retain the current block allocation info */ 141 int32_t fs_cgrotor; /* last cg searched */ 142 struct csum *fs_csp[MAXCSBUFS];/* list of fs_cs info buffers */ 143 int32_t *fs_maxcluster; /* max cluster in each cyl group */ 144 int32_t fs_cpc; /* cyl per cycle in postbl */ 145 int16_t fs_opostbl[16][8]; /* old rotation block list head */ 146 int32_t fs_sparecon[49]; /* reserved for future constants */ 147 int32_t fs_fscktime; /* last time fsck(8)ed */ 148 int32_t fs_contigsumsize; /* size of cluster summary array */ 149 int32_t fs_maxsymlinklen; /* max len of internal symlink */ 150 int32_t fs_inodefmt; /* format of on-disk inodes */ 151 u_int64_t fs_maxfilesize; /* maximum file size */ 152 int64_t fs_qbmask; /* ~fs_bmask - for use with quad size */ 153 int64_t fs_qfmask; /* ~fs_fmask - for use with quad size */ 154 int32_t fs_state; /* validate fs_clean field (UNUSED) */ 155 int32_t fs_postblformat; /* format of positional layout tables */ 156 int32_t fs_nrpos; /* number of rotational positions */ 157 int32_t fs_postbloff; /* (u_int16) rotation block list head */ 158 int32_t fs_rotbloff; /* (u_int8) blocks for each rotation */ 159 int32_t fs_magic; /* magic number */ 160 u_int8_t fs_space[1]; /* list of blocks for each rotation */ 161/* actually longer */ 162}; 163.Ed 164.Pp 165Each disk drive contains some number of file systems. 166A file system consists of a number of cylinder groups. 167Each cylinder group has inodes and data. 168.Pp 169A file system is described by its super-block, which in turn 170describes the cylinder groups. 171The super-block is critical data and is replicated in each cylinder 172group to protect against catastrophic loss. 173This is done at file system creation time and the critical super-block 174data does not change, so the copies need not be referenced further 175unless disaster strikes. 176.Pp 177Addresses stored in inodes are capable of addressing fragments 178of `blocks'. 179File system blocks of at most size 180.Dv MAXBSIZE 181can 182be optionally broken into 2, 4, or 8 pieces, each of which is 183addressable; these pieces may be 184.Dv DEV_BSIZE , 185or some multiple of 186a 187.Dv DEV_BSIZE 188unit. 189.Pp 190Large files consist of exclusively large data blocks. 191To avoid undue wasted disk space, the last data block of a small 192file is allocated as only as many fragments of a large block as 193are necessary. 194The file system format retains only a single pointer to such a 195fragment, which is a piece of a single large block that has been divided. 196The size of such a fragment is determinable from 197information in the inode, using the 198.Fn blksize fs ip lbn 199macro. 200.Pp 201The file system records space availability at the fragment level; 202to determine block availability, aligned fragments are examined. 203.Pp 204The root inode is the root of the file system. 205Inode 0 can't be used for normal purposes and 206historically bad blocks were linked to inode 1, 207thus the root inode is 2 (inode 1 is no longer used for 208this purpose, however numerous dump tapes make this 209assumption, so we are stuck with it). 210.Pp 211The 212.Fa fs_minfree 213element gives the minimum acceptable percentage of file system 214blocks that may be free. 215If the freelist drops below this level 216only the super-user may continue to allocate blocks. 217The 218.Fa fs_minfree 219element 220may be set to 0 if no reserve of free blocks is deemed necessary, 221however severe performance degradations will be observed if the 222file system is run at greater than 90% full; thus the default 223value of 224.Fa fs_minfree 225is 10%. 226.Pp 227Empirically the best trade-off between block fragmentation and 228overall disk utilization at a loading of 90% comes with a 229fragmentation of 8, thus the default fragment size is an eighth 230of the block size. 231.Pp 232The element 233.Fa fs_optim 234specifies whether the file system should try to minimize the time spent 235allocating blocks, or if it should attempt to minimize the space 236fragmentation on the disk. 237If the value of fs_minfree (see above) is less than 10%, 238then the file system defaults to optimizing for space to avoid 239running out of full sized blocks. 240If the value of minfree is greater than or equal to 10%, 241fragmentation is unlikely to be problematical, and 242the file system defaults to optimizing for time. 243.Pp 244.Em Cylinder group related limits : 245Each cylinder keeps track of the availability of blocks at different 246rotational positions, so that sequential blocks can be laid out 247with minimum rotational latency. 248With the default of 8 distinguished 249rotational positions, the resolution of the 250summary information is 2ms for a typical 3600 rpm drive. 251.Pp 252The element 253.Fa fs_rotdelay 254gives the minimum number of milliseconds to initiate 255another disk transfer on the same cylinder. 256It is used in determining the rotationally optimal 257layout for disk blocks within a file; 258the default value for 259.Fa fs_rotdelay 260is 2ms. 261.Pp 262Each file system has a statically allocated number of inodes, 263determined by its size and the desired number of file data bytes per 264inode at the time it was created. See 265.Xr newfs 8 266for details on how to set this (and other) filesystem parameters. 267By default, the inode allocation strategy is extremely conservative. 268.Pp 269.Dv MINBSIZE 270is the smallest allowable block size. 271With a 272.Dv MINBSIZE 273of 4096 274it is possible to create files of size 2752^32 with only two levels of indirection. 276.Dv MINBSIZE 277must be big enough to hold a cylinder group block, 278thus changes to 279.Pq Fa struct cg 280must keep its size within 281.Dv MINBSIZE . 282Note that super-blocks are never more than size 283.Dv SBSIZE . 284.Pp 285The path name on which the file system is mounted is maintained in 286.Fa fs_fsmnt . 287.Dv MAXMNTLEN 288defines the amount of space allocated in 289the super-block for this name. 290The limit on the amount of summary information per file system 291is defined by 292.Dv MAXCSBUFS . 293For a 4096 byte block size, it is currently parameterized for a 294maximum of two million cylinders. 295.Pp 296Per cylinder group information is summarized in blocks allocated 297from the first cylinder group's data blocks. 298These blocks are read in from 299.Fa fs_csaddr 300(size 301.Fa fs_cssize ) 302in addition to the super-block. 303.Pp 304.Sy N.B.: 305.Fn sizeof "struct csum" 306must be a power of two in order for 307the 308.Fn fs_cs 309macro to work. 310.Pp 311The 312.Em "Super-block for a file system" : 313The size of the rotational layout tables 314is limited by the fact that the super-block is of size 315.Dv SBSIZE . 316The size of these tables is 317.Em inversely 318proportional to the block size of the file system. 319The size of the tables is increased when sector sizes are not powers 320of two, as this increases the number of cylinders included before 321the rotational pattern repeats 322.Pq Fa fs_cpc . 323The size of the rotational layout 324tables is derived from the number of bytes remaining in 325.Pq Fa struct fs . 326.Pp 327The number of blocks of data per cylinder group 328is limited because cylinder groups are at most one block. 329The inode and free block tables 330must fit into a single block after deducting space for 331the cylinder group structure 332.Pq Fa struct cg . 333.Pp 334The 335.Em Inode : 336The inode is the focus of all file activity in the 337.Ux 338file system. 339There is a unique inode allocated 340for each active file, 341each current directory, each mounted-on file, 342text file, and the root. 343An inode is `named' by its device/i-number pair. 344For further information, see the include file 345.Aq Pa ufs/ufs/inode.h . 346.Sh SEE ALSO 347.Xr newfs 8 348.Sh HISTORY 349A super-block structure named filsys appeared in 350.At v6 . 351The file system described in this manual appeared 352in 353.Bx 4.2 . 354