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