diff options
Diffstat (limited to 'static/freebsd/man5/fs.5 3.html')
| -rw-r--r-- | static/freebsd/man5/fs.5 3.html | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/static/freebsd/man5/fs.5 3.html b/static/freebsd/man5/fs.5 3.html new file mode 100644 index 00000000..239ca996 --- /dev/null +++ b/static/freebsd/man5/fs.5 3.html @@ -0,0 +1,336 @@ +<table class="head"> + <tr> + <td class="head-ltitle">FS(5)</td> + <td class="head-vol">File Formats Manual</td> + <td class="head-rtitle">FS(5)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">fs</code>, <code class="Nm">inode</code> — + <span class="Nd">format of file system volume</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/param.h</a>></code> + <br/> + <code class="In">#include <<a class="In">ufs/ffs/fs.h</a>></code></p> +<p class="Pp"> + <br/> + <code class="In">#include <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/lock.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/extattr.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/acl.h</a>></code> + <br/> + <code class="In">#include <<a class="In">ufs/ufs/quota.h</a>></code> + <br/> + <code class="In">#include <<a class="In">ufs/ufs/dinode.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">ufs/ufs/extattr.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The files <code class="In"><<a class="In">fs.h</a>></code> + and <code class="In"><<a class="In">inode.h</a>></code> declare + several structures, defined variables and macros which are used to create + and manage the underlying format of file system objects on random access + devices (disks).</p> +<p class="Pp">The block size and number of blocks which comprise a file system + are parameters of the file system. Sectors beginning at + <code class="Dv">BBLOCK</code> and continuing for + <code class="Dv">BBSIZE</code> are used for a disklabel and for some + hardware primary and secondary bootstrapping programs.</p> +<p class="Pp" id="super-block">The actual file system begins at sector + <code class="Dv">SBLOCK</code> with the + <a class="permalink" href="#super-block"><i class="Em">super-block</i></a> + that is of size <code class="Dv">SBLOCKSIZE</code>. The following structure + describes the super-block and is from the file + <code class="In"><<a class="In">ufs/ffs/fs.h</a>></code>:</p> +<div class="Bd Pp Li"> +<pre>/* + * Super block for an FFS filesystem. + */ +struct fs { + int32_t fs_firstfield; /* historic filesystem linked list, */ + int32_t fs_unused_1; /* used for incore super blocks */ + int32_t fs_sblkno; /* offset of super-block in filesys */ + int32_t fs_cblkno; /* offset of cyl-block in filesys */ + int32_t fs_iblkno; /* offset of inode-blocks in filesys */ + int32_t fs_dblkno; /* offset of first data after cg */ + int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ + int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ + int32_t fs_old_time; /* last time written */ + int32_t fs_old_size; /* number of blocks in fs */ + int32_t fs_old_dsize; /* number of data blocks in fs */ + int32_t fs_ncg; /* number of cylinder groups */ + int32_t fs_bsize; /* size of basic blocks in fs */ + int32_t fs_fsize; /* size of frag blocks in fs */ + int32_t fs_frag; /* number of frags in a block in fs */ +/* these are configuration parameters */ + int32_t fs_minfree; /* minimum percentage of free blocks */ + int32_t fs_old_rotdelay; /* num of ms for optimal next block */ + int32_t fs_old_rps; /* disk revolutions per second */ +/* these fields can be computed from the others */ + int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ + int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ + int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ + int32_t fs_fshift; /* ``numfrags'' calc number of frags */ +/* these are configuration parameters */ + int32_t fs_maxcontig; /* max number of contiguous blks */ + int32_t fs_maxbpg; /* max number of blks per cyl group */ +/* these fields can be computed from the others */ + int32_t fs_fragshift; /* block to frag shift */ + int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ + int32_t fs_sbsize; /* actual size of super block */ + int32_t fs_spare1[2]; /* old fs_csmask */ + /* old fs_csshift */ + int32_t fs_nindir; /* value of NINDIR */ + int32_t fs_inopb; /* value of INOPB */ + int32_t fs_old_nspf; /* value of NSPF */ +/* yet another configuration parameter */ + int32_t fs_optim; /* optimization preference, see below */ + int32_t fs_old_npsect; /* # sectors/track including spares */ + int32_t fs_old_interleave; /* hardware sector interleave */ + int32_t fs_old_trackskew; /* sector 0 skew, per track */ + int32_t fs_id[2]; /* unique filesystem id */ +/* sizes determined by number of cylinder groups and their sizes */ + int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */ + int32_t fs_cssize; /* size of cyl grp summary area */ + int32_t fs_cgsize; /* cylinder group size */ + int32_t fs_spare2; /* old fs_ntrak */ + int32_t fs_old_nsect; /* sectors per track */ + int32_t fs_old_spc; /* sectors per cylinder */ + int32_t fs_old_ncyl; /* cylinders in filesystem */ + int32_t fs_old_cpg; /* cylinders per group */ + int32_t fs_ipg; /* inodes per group */ + int32_t fs_fpg; /* blocks per group * fs_frag */ +/* this data must be re-computed after crashes */ + struct csum fs_old_cstotal; /* cylinder summary information */ +/* these fields are cleared at mount time */ + int8_t fs_fmod; /* super block modified flag */ + int8_t fs_clean; /* filesystem is clean flag */ + int8_t fs_ronly; /* mounted read-only flag */ + int8_t fs_old_flags; /* old FS_ flags */ + u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ + u_char fs_volname[MAXVOLLEN]; /* volume name */ + uint64_t fs_swuid; /* system-wide uid */ + int32_t fs_pad; /* due to alignment of fs_swuid */ +/* these fields retain the current block allocation info */ + int32_t fs_cgrotor; /* last cg searched */ + void *fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs buffers */ + uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */ + struct csum *fs_csp; /* cg summary info buffer for fs_cs */ + int32_t *fs_maxcluster; /* max cluster in each cyl group */ + u_int *fs_active; /* used by snapshots to track fs */ + int32_t fs_old_cpc; /* cyl per cycle in postbl */ + int32_t fs_maxbsize; /* maximum blocking factor permitted */ + int64_t fs_unrefs; /* number of unreferenced inodes */ + int64_t fs_sparecon64[16]; /* old rotation block list head */ + int64_t fs_sblockloc; /* byte offset of standard superblock */ + struct csum_total fs_cstotal; /* cylinder summary information */ + ufs_time_t fs_time; /* last time written */ + int64_t fs_size; /* number of blocks in fs */ + int64_t fs_dsize; /* number of data blocks in fs */ + ufs2_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ + int64_t fs_pendingblocks; /* blocks in process of being freed */ + int32_t fs_pendinginodes; /* inodes in process of being freed */ + int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ + int32_t fs_avgfilesize; /* expected average file size */ + int32_t fs_avgfpdir; /* expected # of files per directory */ + int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ + int32_t fs_sparecon32[26]; /* reserved for future constants */ + int32_t fs_flags; /* see FS_ flags below */ + int32_t fs_contigsumsize; /* size of cluster summary array */ + int32_t fs_maxsymlinklen; /* max length of an internal symlink */ + int32_t fs_old_inodefmt; /* format of on-disk inodes */ + uint64_t fs_maxfilesize; /* maximum representable file size */ + int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */ + int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */ + int32_t fs_state; /* validate fs_clean field */ + int32_t fs_old_postblformat; /* format of positional layout tables */ + int32_t fs_old_nrpos; /* number of rotational positions */ + int32_t fs_spare5[2]; /* old fs_postbloff */ + /* old fs_rotbloff */ + int32_t fs_magic; /* magic number */ +}; + +/* + * Filesystem identification + */ +#define FS_UFS1_MAGIC 0x011954 /* UFS1 fast filesystem magic number */ +#define FS_UFS2_MAGIC 0x19540119 /* UFS2 fast filesystem magic number */ +#define FS_OKAY 0x7c269d38 /* superblock checksum */ +#define FS_42INODEFMT -1 /* 4.2BSD inode format */ +#define FS_44INODEFMT 2 /* 4.4BSD inode format */ + +/* + * Preference for optimization. + */ +#define FS_OPTTIME 0 /* minimize allocation time */ +#define FS_OPTSPACE 1 /* minimize disk fragmentation */</pre> +</div> +<p class="Pp">Each disk drive contains some number of file systems. A file + system consists of a number of cylinder groups. Each cylinder group has + inodes and data.</p> +<p class="Pp">A file system is described by its super-block, which in turn + describes the cylinder groups. The super-block is critical data and is + replicated in each cylinder group to protect against catastrophic loss. This + is done at file system creation time and the critical super-block data does + not change, so the copies need not be referenced further unless disaster + strikes.</p> +<p class="Pp">Addresses stored in inodes are capable of addressing fragments of + `blocks'. File system blocks of at most size + <code class="Dv">MAXBSIZE</code> can be optionally broken into 2, 4, or 8 + pieces, each of which is addressable; these pieces may be + <code class="Dv">DEV_BSIZE</code>, or some multiple of a + <code class="Dv">DEV_BSIZE</code> unit.</p> +<p class="Pp" id="blksize">Large files consist of exclusively large data blocks. + To avoid undue wasted disk space, the last data block of a small file is + allocated as only as many fragments of a large block as are necessary. The + file system format retains only a single pointer to such a fragment, which + is a piece of a single large block that has been divided. The size of such a + fragment is determinable from information in the inode, using the + <a class="permalink" href="#blksize"><code class="Fn">blksize</code></a>(<var class="Fa">fs</var>, + <var class="Fa">ip</var>, <var class="Fa">lbn</var>) macro.</p> +<p class="Pp">The file system records space availability at the fragment level; + to determine block availability, aligned fragments are examined.</p> +<p class="Pp">The root inode is the root of the file system. Inode 0 cannot be + used for normal purposes and historically bad blocks were linked to inode 1, + thus the root inode is 2 (inode 1 is no longer used for this purpose, + however numerous dump tapes make this assumption, so we are stuck with + it).</p> +<p class="Pp">The <var class="Fa">fs_minfree</var> element gives the minimum + acceptable percentage of file system blocks that may be free. If the + freelist drops below this level only the super-user may continue to allocate + blocks. The <var class="Fa">fs_minfree</var> element may be set to 0 if no + reserve of free blocks is deemed necessary, however severe performance + degradations will be observed if the file system is run at greater than 90% + full; thus the default value of <var class="Fa">fs_minfree</var> is 8%.</p> +<p class="Pp">Empirically the best trade-off between block fragmentation and + overall disk utilization at a loading of 90% comes with a fragmentation of + 8, thus the default fragment size is an eighth of the block size.</p> +<p class="Pp">The element <var class="Fa">fs_optim</var> specifies whether the + file system should try to minimize the time spent allocating blocks, or if + it should attempt to minimize the space fragmentation on the disk. If the + value of fs_minfree (see above) is less than 8%, then the file system + defaults to optimizing for space to avoid running out of full sized blocks. + If the value of minfree is greater than or equal to 8%, fragmentation is + unlikely to be problematical, and the file system defaults to optimizing for + time.</p> +<p class="Pp" id="Cylinder"><a class="permalink" href="#Cylinder"><i class="Em">Cylinder + group related limits</i></a>: Each cylinder keeps track of the availability + of blocks at different rotational positions, so that sequential blocks can + be laid out with minimum rotational latency. With the default of 8 + distinguished rotational positions, the resolution of the summary + information is 2ms for a typical 3600 rpm drive.</p> +<p class="Pp">The element <var class="Fa">fs_old_rotdelay</var> gives the + minimum number of milliseconds to initiate another disk transfer on the same + cylinder. It is used in determining the rotationally optimal layout for disk + blocks within a file; the default value for + <var class="Fa">fs_old_rotdelay</var> is 2ms.</p> +<p class="Pp">Each file system has a statically allocated number of inodes. An + inode is allocated for each <code class="Dv">NBPI</code> bytes of disk + space. The inode allocation strategy is extremely conservative.</p> +<p class="Pp"><code class="Dv">MINBSIZE</code> is the smallest allowable block + size. With a <code class="Dv">MINBSIZE</code> of 4096 it is possible to + create files of size 2^32 with only two levels of indirection. + <code class="Dv">MINBSIZE</code> must be big enough to hold a cylinder group + block, thus changes to (<var class="Fa">struct cg</var>) must keep its size + within <code class="Dv">MINBSIZE</code>. Note that super-blocks are never + more than size <code class="Dv">SBLOCKSIZE</code>.</p> +<p class="Pp">The path name on which the file system is mounted is maintained in + <var class="Fa">fs_fsmnt</var>. <code class="Dv">MAXMNTLEN</code> defines + the amount of space allocated in the super-block for this name. The limit on + the amount of summary information per file system is defined by + <code class="Dv">MAXCSBUFS</code>. For a 4096 byte block size, it is + currently parameterized for a maximum of two million cylinders.</p> +<p class="Pp">Per cylinder group information is summarized in blocks allocated + from the first cylinder group's data blocks. These blocks are read in from + <var class="Fa">fs_csaddr</var> (size <var class="Fa">fs_cssize</var>) in + addition to the super-block.</p> +<p class="Pp" id="N.B."><a class="permalink" href="#N.B."><b class="Sy">N.B.</b></a>: + <a class="permalink" href="#sizeof"><code class="Fn" id="sizeof">sizeof</code></a>(<var class="Fa">struct + csum</var>) must be a power of two in order for the + <a class="permalink" href="#fs_cs"><code class="Fn" id="fs_cs">fs_cs</code></a>() + macro to work.</p> +<p class="Pp" id="Super-block">The + <a class="permalink" href="#Super-block"><i class="Em">Super-block for a + file system</i></a>: The size of the rotational layout tables is limited by + the fact that the super-block is of size <code class="Dv">SBLOCKSIZE</code>. + The size of these tables is + <a class="permalink" href="#inversely"><i class="Em" id="inversely">inversely</i></a> + proportional to the block size of the file system. The size of the tables is + increased when sector sizes are not powers of two, as this increases the + number of cylinders included before the rotational pattern repeats + (<var class="Fa">fs_cpc</var>). The size of the rotational layout tables is + derived from the number of bytes remaining in (<var class="Fa">struct + fs</var>).</p> +<p class="Pp">The number of blocks of data per cylinder group is limited because + cylinder groups are at most one block. The inode and free block tables must + fit into a single block after deducting space for the cylinder group + structure (<var class="Fa">struct cg</var>).</p> +<p class="Pp" id="Inode">The + <a class="permalink" href="#Inode"><i class="Em">Inode</i></a>: The inode is + the focus of all file activity in the <span class="Ux">UNIX</span> file + system. There is a unique inode allocated for each active file, each current + directory, each mounted-on file, text file, and the root. An inode is + `named' by its device/i-number pair. For further information, see the + include file + <code class="In"><<a class="In">ufs/ufs/inode.h</a>></code>.</p> +<p class="Pp">The format of an external attribute is defined by the extattr + structure:</p> +<div class="Bd Pp Li"> +<pre>struct extattr { + uint32_t ea_length; /* length of this attribute */ + uint8_t ea_namespace; /* name space of this attribute */ + uint8_t ea_contentpadlen; /* bytes of padding at end of attribute */ + uint8_t ea_namelength; /* length of attribute name */ + char ea_name[1]; /* attribute name (NOT nul-terminated) */ + /* padding, if any, to align attribute content to 8 byte boundary */ + /* extended attribute content follows */ +};</pre> +</div> +<p class="Pp">Several macros are defined to manipulate these structures. Each + macro takes a pointer to an extattr structure.</p> +<dl class="Bl-tag"> + <dt id="EXTATTR_NEXT(eap)"><a class="permalink" href="#EXTATTR_NEXT(eap)"><code class="Dv">EXTATTR_NEXT(eap)</code></a></dt> + <dd>Returns a pointer to the next extended attribute following + <var class="Fa">eap</var>.</dd> + <dt id="EXTATTR_CONTENT(eap)"><a class="permalink" href="#EXTATTR_CONTENT(eap)"><code class="Dv">EXTATTR_CONTENT(eap)</code></a></dt> + <dd>Returns a pointer to the extended attribute content referenced by + <var class="Fa">eap</var>.</dd> + <dt id="EXTATTR_CONTENT_SIZE(eap)"><a class="permalink" href="#EXTATTR_CONTENT_SIZE(eap)"><code class="Dv">EXTATTR_CONTENT_SIZE(eap)</code></a></dt> + <dd>Returns the size of the extended attribute content referenced by + <var class="Fa">eap</var>.</dd> +</dl> +<p class="Pp">The following code identifies an ACL:</p> +<div class="Bd Pp Li"> +<pre> if (eap->ea_namespace == EXTATTR_NAMESPACE_SYSTEM && + eap->ea_namelength == sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1 && + strncmp(eap->ea_name, POSIX1E_ACL_ACCESS_EXTATTR_NAME, + sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1) == 0) { + aclp = EXTATTR_CONTENT(eap); + acllen = EXTATTR_CONTENT_SIZE(eap); + ... + }</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">A super-block structure named filsys appeared in + <span class="Ux">Version 6 AT&T UNIX</span>. The file system + described in this manual appeared in <span class="Ux">4.2BSD</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 16, 2017</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |