1.\" $NetBSD: fs.5,v 1.18 2010/03/22 18:58:32 joerg 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.In ufs/ffs/fs.h 46and 47.In ufs/ufs/inode.h 48declare several structures and define 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.In 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 int32_t fs_sblkno; /* addr of super-block in filesys */ 77 int32_t fs_cblkno; /* offset of cyl-block in filesys */ 78 int32_t fs_iblkno; /* offset of inode-blocks in filesys */ 79 int32_t fs_dblkno; /* offset of first data after cg */ 80 int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ 81 int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ 82 int32_t fs_old_time; /* last time written */ 83 int32_t fs_old_size; /* number of blocks in fs */ 84 int32_t fs_old_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_old_rotdelay; /* num of ms for optimal next block */ 92 int32_t fs_old_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_spare1[2]; /* old fs_csmask */ 106 /* old fs_csshift */ 107 int32_t fs_nindir; /* value of NINDIR */ 108 int32_t fs_inopb; /* value of INOPB */ 109 int32_t fs_old_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_old_npsect; /* # sectors/track including spares */ 114 int32_t fs_old_interleave; /* hardware sector interleave */ 115 int32_t fs_old_trackskew; /* sector 0 skew, per track */ 116/* fs_id takes the space of unused fs_headswitch and fs_trkseek fields */ 117 int32_t fs_id[2]; /* unique file system id */ 118/* sizes determined by number of cylinder groups and their sizes */ 119 int32_t fs_old_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_spare2; /* old fs_ntrak */ 124 int32_t fs_old_nsect; /* sectors per track */ 125 int32_t fs_old_spc; /* sectors per cylinder */ 126 int32_t fs_old_ncyl; /* cylinders in file system */ 127 int32_t fs_old_cpg; /* cylinders per group */ 128 int32_t fs_ipg; /* inodes per group */ 129 int32_t fs_fpg; /* blocks per group * fs_frag */ 130/* this data must be re-computed after crashes */ 131 struct csum fs_old_cstotal; /* cylinder summary information */ 132/* these fields are cleared at mount time */ 133 int8_t fs_fmod; /* super block modified flag */ 134 int8_t fs_clean; /* file system is clean flag */ 135 int8_t fs_ronly; /* mounted read-only flag */ 136 uint8_t fs_old_flags; /* see FS_ flags below */ 137 u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ 138 u_char fs_volname[MAXVOLLEN]; /* volume name */ 139 uint64_t fs_swuid; /* system-wide uid */ 140 int32_t fs_pad; 141/* these fields retain the current block allocation info */ 142 int32_t fs_cgrotor; /* last cg searched (UNUSED) */ 143 void *fs_ocsp[NOCSPTRS];/* padding; was list of fs_cs buffers */ 144 uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */ 145 struct csum *fs_csp; /* cg summary info buffer for fs_cs */ 146 int32_t *fs_maxcluster; /* max cluster in each cyl group */ 147 u_char *fs_active; /* used by snapshots to track fs */ 148 int32_t fs_old_cpc; /* cyl per cycle in postbl */ 149/* this area is otherwise allocated unless fs_old_flags & FS_FLAGS_UPDATED */ 150 int32_t fs_maxbsize; /* maximum blocking factor permitted */ 151 int64_t fs_sparecon64[17]; /* old rotation block list head */ 152 int64_t fs_sblockloc; /* byte offset of standard superblock */ 153 struct csum_total fs_cstotal; /* cylinder summary information */ 154 int64_t fs_time; /* last time written */ 155 int64_t fs_size; /* number of blocks in fs */ 156 int64_t fs_dsize; /* number of data blocks in fs */ 157 int64_t fs_csaddr; /* blk addr of cyl grp summary area */ 158 int64_t fs_pendingblocks; /* blocks in process of being freed */ 159 int32_t fs_pendinginodes; /* inodes in process of being freed */ 160 int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ 161/* back to stuff that has been around a while */ 162 int32_t fs_avgfilesize; /* expected average file size */ 163 int32_t fs_avgfpdir; /* expected # of files per directory */ 164 int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ 165 int32_t fs_sparecon32[26]; /* reserved for future constants */ 166 uint32_t fs_flags; /* see FS_ flags below */ 167/* back to stuff that has been around a while (again) */ 168 int32_t fs_contigsumsize; /* size of cluster summary array */ 169 int32_t fs_maxsymlinklen; /* max length of an internal symlink */ 170 int32_t fs_old_inodefmt; /* format of on-disk inodes */ 171 uint64_t fs_maxfilesize; /* maximum representable file size */ 172 int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */ 173 int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */ 174 int32_t fs_state; /* validate fs_clean field (UNUSED) */ 175 int32_t fs_old_postblformat; /* format of positional layout tables */ 176 int32_t fs_old_nrpos; /* number of rotational positions */ 177 int32_t fs_spare5[2]; /* old fs_postbloff */ 178 /* old fs_rotbloff */ 179 int32_t fs_magic; /* magic number */ 180}; 181.Ed 182.Pp 183Each disk drive contains some number of file systems. 184A file system consists of a number of cylinder groups. 185Each cylinder group has inodes and data. 186.Pp 187A file system is described by its super-block, which in turn 188describes the cylinder groups. 189The super-block is critical data and is replicated in each cylinder 190group to protect against catastrophic loss. 191This is done at file system creation time and the critical super-block 192data does not change, so the copies need not be referenced further 193unless disaster strikes. 194.Pp 195Addresses stored in inodes are capable of addressing fragments 196of `blocks'. 197File system blocks of at most size 198.Dv MAXBSIZE 199can 200be optionally broken into 2, 4, or 8 pieces, each of which is 201addressable; these pieces may be 202.Dv DEV_BSIZE , 203or some multiple of 204a 205.Dv DEV_BSIZE 206unit. 207.Pp 208Large files consist of exclusively large data blocks. 209To avoid undue wasted disk space, the last data block of a small 210file is allocated as only as many fragments of a large block as 211are necessary. 212The file system format retains only a single pointer to such a 213fragment, which is a piece of a single large block that has been divided. 214The size of such a fragment is determinable from 215information in the inode, using the 216.Fn blksize fs ip lbn 217macro. 218.Pp 219The file system records space availability at the fragment level; 220to determine block availability, aligned fragments are examined. 221.Pp 222The root inode is the root of the file system. 223Inode 0 can't be used for normal purposes and 224historically bad blocks were linked to inode 1, 225thus the root inode is 2 (inode 1 is no longer used for 226this purpose, however numerous dump tapes make this 227assumption, so we are stuck with it). 228.Pp 229The 230.Fa fs_minfree 231element gives the minimum acceptable percentage of file system 232blocks that may be free. 233If the freelist drops below this level 234only the super-user may continue to allocate blocks. 235The 236.Fa fs_minfree 237element 238may be set to 0 if no reserve of free blocks is deemed necessary, 239however severe performance degradations will be observed if the 240file system is run at greater than 90% full; thus the default 241value of 242.Fa fs_minfree 243is 10%. 244.Pp 245Empirically the best trade-off between block fragmentation and 246overall disk utilization at a loading of 90% comes with a 247fragmentation of 8, thus the default fragment size is an eighth 248of the block size. 249.Pp 250The element 251.Fa fs_optim 252specifies whether the file system should try to minimize the time spent 253allocating blocks, or if it should attempt to minimize the space 254fragmentation on the disk. 255If the value of fs_minfree (see above) is less than 10%, 256then the file system defaults to optimizing for space to avoid 257running out of full sized blocks. 258If the value of minfree is greater than or equal to 10%, 259fragmentation is unlikely to be problematical, and 260the file system defaults to optimizing for time. 261.Pp 262.Em Cylinder group related limits : 263Each cylinder keeps track of the availability of blocks at different 264rotational positions, so that sequential blocks can be laid out 265with minimum rotational latency. 266With the default of 8 distinguished 267rotational positions, the resolution of the 268summary information is 2ms for a typical 3600 rpm drive. 269.Pp 270The element 271.Fa fs_rotdelay 272gives the minimum number of milliseconds to initiate 273another disk transfer on the same cylinder. 274It is used in determining the rotationally optimal 275layout for disk blocks within a file; 276the default value for 277.Fa fs_rotdelay 278is 2ms. 279.Pp 280Each file system has a statically allocated number of inodes, 281determined by its size and the desired number of file data bytes per 282inode at the time it was created. See 283.Xr newfs 8 284for details on how to set this (and other) filesystem parameters. 285By default, the inode allocation strategy is extremely conservative. 286.Pp 287.Dv MINBSIZE 288is the smallest allowable block size. 289With a 290.Dv MINBSIZE 291of 4096 292it is possible to create files of size 2932^32 with only two levels of indirection. 294.Dv MINBSIZE 295must be big enough to hold a cylinder group block, 296thus changes to 297.Pq Fa struct cg 298must keep its size within 299.Dv MINBSIZE . 300Note that super-blocks are never more than size 301.Dv SBSIZE . 302.Pp 303The path name on which the file system is mounted is maintained in 304.Fa fs_fsmnt . 305.Dv MAXMNTLEN 306defines the amount of space allocated in 307the super-block for this name. 308The limit on the amount of summary information per file system 309is defined by 310.Dv MAXCSBUFS . 311For a 4096 byte block size, it is currently parameterized for a 312maximum of two million cylinders. 313.Pp 314Per cylinder group information is summarized in blocks allocated 315from the first cylinder group's data blocks. 316These blocks are read in from 317.Fa fs_csaddr 318(size 319.Fa fs_cssize ) 320in addition to the super-block. 321.Pp 322.Sy N.B.: 323.Fn sizeof "struct csum" 324must be a power of two in order for 325the 326.Fn fs_cs 327macro to work. 328.Pp 329The 330.Em "Super-block for a file system" : 331The size of the rotational layout tables 332is limited by the fact that the super-block is of size 333.Dv SBSIZE . 334The size of these tables is 335.Em inversely 336proportional to the block size of the file system. 337The size of the tables is increased when sector sizes are not powers 338of two, as this increases the number of cylinders included before 339the rotational pattern repeats 340.Pq Fa fs_cpc . 341The size of the rotational layout 342tables is derived from the number of bytes remaining in 343.Pq Fa struct fs . 344.Pp 345The number of blocks of data per cylinder group 346is limited because cylinder groups are at most one block. 347The inode and free block tables 348must fit into a single block after deducting space for 349the cylinder group structure 350.Pq Fa struct cg . 351.Pp 352The 353.Em Inode : 354The inode is the focus of all file activity in the 355.Ux 356file system. 357There is a unique inode allocated 358for each active file, 359each current directory, each mounted-on file, 360text file, and the root. 361An inode is `named' by its device/i-number pair. 362For further information, see the include file 363.In ufs/ufs/inode.h . 364.Sh SEE ALSO 365.Xr newfs 8 366.Sh HISTORY 367A super-block structure named filsys appeared in 368.At v6 . 369The file system described in this manual appeared 370in 371.Bx 4.2 . 372