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