1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd January 16, 2017 29.Dt FS 5 30.Os 31.Sh NAME 32.Nm fs , 33.Nm inode 34.Nd format of file system volume 35.Sh SYNOPSIS 36.In sys/param.h 37.In ufs/ffs/fs.h 38.Pp 39.In sys/types.h 40.In sys/lock.h 41.In sys/extattr.h 42.In sys/acl.h 43.In ufs/ufs/quota.h 44.In ufs/ufs/dinode.h 45.In ufs/ufs/extattr.h 46.Sh DESCRIPTION 47The files 48.In fs.h 49and 50.In inode.h 51declare several structures, defined variables and macros 52which are used to create and manage the underlying format of 53file system objects on random access devices (disks). 54.Pp 55The block size and number of blocks which 56comprise a file system are parameters of the file system. 57Sectors beginning at 58.Dv BBLOCK 59and continuing for 60.Dv BBSIZE 61are used 62for a disklabel and for some hardware primary 63and secondary bootstrapping programs. 64.Pp 65The actual file system begins at sector 66.Dv SBLOCK 67with the 68.Em super-block 69that is of size 70.Dv SBLOCKSIZE . 71The following structure describes the super-block and is 72from the file 73.In ufs/ffs/fs.h : 74.Bd -literal 75/* 76 * Super block for an FFS filesystem. 77 */ 78struct fs { 79 int32_t fs_firstfield; /* historic filesystem linked list, */ 80 int32_t fs_unused_1; /* used for incore super blocks */ 81 int32_t fs_sblkno; /* offset of super-block in filesys */ 82 int32_t fs_cblkno; /* offset of cyl-block in filesys */ 83 int32_t fs_iblkno; /* offset of inode-blocks in filesys */ 84 int32_t fs_dblkno; /* offset of first data after cg */ 85 int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ 86 int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ 87 int32_t fs_old_time; /* last time written */ 88 int32_t fs_old_size; /* number of blocks in fs */ 89 int32_t fs_old_dsize; /* number of data blocks in fs */ 90 int32_t fs_ncg; /* number of cylinder groups */ 91 int32_t fs_bsize; /* size of basic blocks in fs */ 92 int32_t fs_fsize; /* size of frag blocks in fs */ 93 int32_t fs_frag; /* number of frags in a block in fs */ 94/* these are configuration parameters */ 95 int32_t fs_minfree; /* minimum percentage of free blocks */ 96 int32_t fs_old_rotdelay; /* num of ms for optimal next block */ 97 int32_t fs_old_rps; /* disk revolutions per second */ 98/* these fields can be computed from the others */ 99 int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ 100 int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ 101 int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ 102 int32_t fs_fshift; /* ``numfrags'' calc number of frags */ 103/* these are configuration parameters */ 104 int32_t fs_maxcontig; /* max number of contiguous blks */ 105 int32_t fs_maxbpg; /* max number of blks per cyl group */ 106/* these fields can be computed from the others */ 107 int32_t fs_fragshift; /* block to frag shift */ 108 int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ 109 int32_t fs_sbsize; /* actual size of super block */ 110 int32_t fs_spare1[2]; /* old fs_csmask */ 111 /* old fs_csshift */ 112 int32_t fs_nindir; /* value of NINDIR */ 113 int32_t fs_inopb; /* value of INOPB */ 114 int32_t fs_old_nspf; /* value of NSPF */ 115/* yet another configuration parameter */ 116 int32_t fs_optim; /* optimization preference, see below */ 117 int32_t fs_old_npsect; /* # sectors/track including spares */ 118 int32_t fs_old_interleave; /* hardware sector interleave */ 119 int32_t fs_old_trackskew; /* sector 0 skew, per track */ 120 int32_t fs_id[2]; /* unique filesystem id */ 121/* sizes determined by number of cylinder groups and their sizes */ 122 int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */ 123 int32_t fs_cssize; /* size of cyl grp summary area */ 124 int32_t fs_cgsize; /* cylinder group size */ 125 int32_t fs_spare2; /* old fs_ntrak */ 126 int32_t fs_old_nsect; /* sectors per track */ 127 int32_t fs_old_spc; /* sectors per cylinder */ 128 int32_t fs_old_ncyl; /* cylinders in filesystem */ 129 int32_t fs_old_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_old_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; /* filesystem is clean flag */ 137 int8_t fs_ronly; /* mounted read-only flag */ 138 int8_t fs_old_flags; /* old FS_ flags */ 139 u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ 140 u_char fs_volname[MAXVOLLEN]; /* volume name */ 141 uint64_t fs_swuid; /* system-wide uid */ 142 int32_t fs_pad; /* due to alignment of fs_swuid */ 143/* these fields retain the current block allocation info */ 144 int32_t fs_cgrotor; /* last cg searched */ 145 void *fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs buffers */ 146 uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */ 147 struct csum *fs_csp; /* cg summary info buffer for fs_cs */ 148 int32_t *fs_maxcluster; /* max cluster in each cyl group */ 149 u_int *fs_active; /* used by snapshots to track fs */ 150 int32_t fs_old_cpc; /* cyl per cycle in postbl */ 151 int32_t fs_maxbsize; /* maximum blocking factor permitted */ 152 int64_t fs_unrefs; /* number of unreferenced inodes */ 153 int64_t fs_sparecon64[16]; /* old rotation block list head */ 154 int64_t fs_sblockloc; /* byte offset of standard superblock */ 155 struct csum_total fs_cstotal; /* cylinder summary information */ 156 ufs_time_t fs_time; /* last time written */ 157 int64_t fs_size; /* number of blocks in fs */ 158 int64_t fs_dsize; /* number of data blocks in fs */ 159 ufs2_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ 160 int64_t fs_pendingblocks; /* blocks in process of being freed */ 161 int32_t fs_pendinginodes; /* inodes in process of being freed */ 162 int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ 163 int32_t fs_avgfilesize; /* expected average file size */ 164 int32_t fs_avgfpdir; /* expected # of files per directory */ 165 int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ 166 int32_t fs_sparecon32[26]; /* reserved for future constants */ 167 int32_t fs_flags; /* see FS_ flags below */ 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 */ 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 182/* 183 * Filesystem identification 184 */ 185#define FS_UFS1_MAGIC 0x011954 /* UFS1 fast filesystem magic number */ 186#define FS_UFS2_MAGIC 0x19540119 /* UFS2 fast filesystem magic number */ 187#define FS_OKAY 0x7c269d38 /* superblock checksum */ 188#define FS_42INODEFMT -1 /* 4.2BSD inode format */ 189#define FS_44INODEFMT 2 /* 4.4BSD inode format */ 190 191/* 192 * Preference for optimization. 193 */ 194#define FS_OPTTIME 0 /* minimize allocation time */ 195#define FS_OPTSPACE 1 /* minimize disk fragmentation */ 196.Ed 197.Pp 198Each disk drive contains some number of file systems. 199A file system consists of a number of cylinder groups. 200Each cylinder group has inodes and data. 201.Pp 202A file system is described by its super-block, which in turn 203describes the cylinder groups. 204The super-block is critical 205data and is replicated in each cylinder group to protect against 206catastrophic loss. 207This is done at file system creation 208time and the critical 209super-block data does not change, so the copies need not be 210referenced further unless disaster strikes. 211.Pp 212Addresses stored in inodes are capable of addressing fragments 213of `blocks'. 214File system blocks of at most size 215.Dv MAXBSIZE 216can 217be optionally broken into 2, 4, or 8 pieces, each of which is 218addressable; these pieces may be 219.Dv DEV_BSIZE , 220or some multiple of 221a 222.Dv DEV_BSIZE 223unit. 224.Pp 225Large files consist of exclusively large data blocks. 226To avoid 227undue wasted disk space, the last data block of a small file is 228allocated as only as many fragments of a large block as are 229necessary. 230The file system format retains only a single pointer 231to such a fragment, which is a piece of a single large block that 232has been divided. 233The size of such a fragment is determinable from 234information in the inode, using the 235.Fn blksize fs ip lbn 236macro. 237.Pp 238The file system records space availability at the fragment level; 239to determine block availability, aligned fragments are examined. 240.Pp 241The root inode is the root of the file system. 242Inode 0 cannot be used for normal purposes and 243historically bad blocks were linked to inode 1, 244thus the root inode is 2 (inode 1 is no longer used for 245this purpose, however numerous dump tapes make this 246assumption, so we are stuck with it). 247.Pp 248The 249.Fa fs_minfree 250element gives the minimum acceptable percentage of file system 251blocks that may be free. 252If the freelist drops below this level 253only the super-user may continue to allocate blocks. 254The 255.Fa fs_minfree 256element 257may be set to 0 if no reserve of free blocks is deemed necessary, 258however severe performance degradations will be observed if the 259file system is run at greater than 90% full; thus the default 260value of 261.Fa fs_minfree 262is 8%. 263.Pp 264Empirically the best trade-off between block fragmentation and 265overall disk utilization at a loading of 90% comes with a 266fragmentation of 8, thus the default fragment size is an eighth 267of the block size. 268.Pp 269The element 270.Fa fs_optim 271specifies whether the file system should try to minimize the time spent 272allocating blocks, or if it should attempt to minimize the space 273fragmentation on the disk. 274If the value of fs_minfree (see above) is less than 8%, 275then the file system defaults to optimizing for space to avoid 276running out of full sized blocks. 277If the value of minfree is greater than or equal to 8%, 278fragmentation is unlikely to be problematical, and 279the file system defaults to optimizing for time. 280.Pp 281.Em Cylinder group related limits : 282Each cylinder keeps track of the availability of blocks at different 283rotational positions, so that sequential blocks can be laid out 284with minimum rotational latency. 285With the default of 8 distinguished 286rotational positions, the resolution of the 287summary information is 2ms for a typical 3600 rpm drive. 288.Pp 289The element 290.Fa fs_old_rotdelay 291gives the minimum number of milliseconds to initiate 292another disk transfer on the same cylinder. 293It is used in determining the rotationally optimal 294layout for disk blocks within a file; 295the default value for 296.Fa fs_old_rotdelay 297is 2ms. 298.Pp 299Each file system has a statically allocated number of inodes. 300An inode is allocated for each 301.Dv NBPI 302bytes of disk space. 303The inode allocation strategy is extremely conservative. 304.Pp 305.Dv MINBSIZE 306is the smallest allowable block size. 307With a 308.Dv MINBSIZE 309of 4096 310it is possible to create files of size 3112^32 with only two levels of indirection. 312.Dv MINBSIZE 313must be big enough to hold a cylinder group block, 314thus changes to 315.Pq Fa struct cg 316must keep its size within 317.Dv MINBSIZE . 318Note that super-blocks are never more than size 319.Dv SBLOCKSIZE . 320.Pp 321The path name on which the file system is mounted is maintained in 322.Fa fs_fsmnt . 323.Dv MAXMNTLEN 324defines the amount of space allocated in 325the super-block for this name. 326The limit on the amount of summary information per file system 327is defined by 328.Dv MAXCSBUFS . 329For a 4096 byte block size, it is currently parameterized for a 330maximum of two million cylinders. 331.Pp 332Per cylinder group information is summarized in blocks allocated 333from the first cylinder group's data blocks. 334These blocks are read in from 335.Fa fs_csaddr 336(size 337.Fa fs_cssize ) 338in addition to the super-block. 339.Pp 340.Sy N.B. : 341.Fn sizeof "struct csum" 342must be a power of two in order for 343the 344.Fn fs_cs 345macro to work. 346.Pp 347The 348.Em "Super-block for a file system" : 349The size of the rotational layout tables 350is limited by the fact that the super-block is of size 351.Dv SBLOCKSIZE . 352The size of these tables is 353.Em inversely 354proportional to the block 355size of the file system. 356The size of the tables is 357increased when sector sizes are not powers of two, 358as this increases the number of cylinders 359included before the rotational pattern repeats 360.Pq Fa fs_cpc . 361The size of the rotational layout 362tables is derived from the number of bytes remaining in 363.Pq Fa struct fs . 364.Pp 365The number of blocks of data per cylinder group 366is limited because cylinder groups are at most one block. 367The inode and free block tables 368must fit into a single block after deducting space for 369the cylinder group structure 370.Pq Fa struct cg . 371.Pp 372The 373.Em Inode : 374The inode is the focus of all file activity in the 375.Ux 376file system. 377There is a unique inode allocated 378for each active file, 379each current directory, each mounted-on file, 380text file, and the root. 381An inode is `named' by its device/i-number pair. 382For further information, see the include file 383.In ufs/ufs/inode.h . 384.Pp 385The format of an external attribute is defined by the extattr structure: 386.Bd -literal 387struct extattr { 388 uint32_t ea_length; /* length of this attribute */ 389 uint8_t ea_namespace; /* name space of this attribute */ 390 uint8_t ea_contentpadlen; /* bytes of padding at end of attribute */ 391 uint8_t ea_namelength; /* length of attribute name */ 392 char ea_name[1]; /* attribute name (NOT nul-terminated) */ 393 /* padding, if any, to align attribute content to 8 byte boundary */ 394 /* extended attribute content follows */ 395}; 396.Ed 397.Pp 398Several macros are defined to manipulate these structures. 399Each macro takes a pointer to an extattr structure. 400.Bl -tag -width ".Dv EXTATTR_CONTENT_SIZE(eap)" 401.It Dv EXTATTR_NEXT(eap) 402Returns a pointer to the next extended attribute following 403.Fa eap . 404.It Dv EXTATTR_CONTENT(eap) 405Returns a pointer to the extended attribute content referenced by 406.Fa eap . 407.It Dv EXTATTR_CONTENT_SIZE(eap) 408Returns the size of the extended attribute content referenced by 409.Fa eap . 410.El 411.Pp 412The following code identifies an ACL: 413.Bd -literal 414 if (eap->ea_namespace == EXTATTR_NAMESPACE_SYSTEM && 415 eap->ea_namelength == sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1 && 416 strncmp(eap->ea_name, POSIX1E_ACL_ACCESS_EXTATTR_NAME, 417 sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1) == 0) { 418 aclp = EXTATTR_CONTENT(eap); 419 acllen = EXTATTR_CONTENT_SIZE(eap); 420 ... 421 } 422.Ed 423.Sh HISTORY 424A super-block structure named filsys appeared in 425.At v6 . 426The file system described in this manual appeared 427in 428.Bx 4.2 . 429