- clarify header locations

- sync header description w/ reality
- better macro usage
- update descriptions
- document FS_* mount flags

all from jared yanovich;
help/editing/ok tedu@

1 files changed, 132 insertions, 112 deletions

diff --git a/share/man/man5/fs.5 b/share/man/man5/fs.5
index ad59186c49f..c364a9aa2a0 100644
--- a/share/man/man5/fs.5
+++ b/share/man/man5/fs.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: fs.5,v 1.13 2004/02/24 07:17:32 jmc Exp $
+.\"	$OpenBSD: fs.5,v 1.14 2004/05/26 09:42:14 jmc Exp $
 .\"	$NetBSD: fs.5,v 1.3 1994/11/30 19:31:17 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -43,9 +43,9 @@
 .Fd #include <ufs/ufs/inode.h>
 .Sh DESCRIPTION
 The files
-.Aq Pa fs.h
+.Aq Pa ufs/ffs/fs.h
 and
-.Aq Pa inode.h
+.Aq Pa ufs/ufs/inode.h
 declare several structures and define variables and macros
 which are used to create and manage the underlying format of
 file system objects on random access devices (disks).
@@ -68,90 +68,102 @@ that is of size
 .Dv SBSIZE .
 The following structure describes the super-block and is
 from the file
-.Aq Pa ufs/fs.h :
+.Aq Pa ufs/ffs/fs.h :
 .Bd -literal
 #define	FS_MAGIC 0x011954
 struct fs {
-	struct	fs *fs_link;	/* linked list of file systems */
-	struct	fs *fs_rlink;	/*     used for incore super blocks */
-	daddr_t	fs_sblkno;	/* addr of super-block in filesys */
-	daddr_t	fs_cblkno;	/* offset of cyl-block in filesys */
-	daddr_t	fs_iblkno;	/* offset of inode-blocks in filesys */
-	daddr_t	fs_dblkno;	/* offset of first data after cg */
-	long	fs_cgoffset;	/* cylinder group offset in cylinder */
-	long	fs_cgmask;	/* used to calc mod fs_ntrak */
-	time_t 	fs_time;    	/* last time written */
-	long	fs_size;	/* number of blocks in fs */
-	long	fs_dsize;	/* number of data blocks in fs */
-	long	fs_ncg;	/* number of cylinder groups */
-	long	fs_bsize;	/* size of basic blocks in fs */
-	long	fs_fsize;	/* size of frag blocks in fs */
-	long	fs_frag;	/* number of frags in a block in fs */
+	int32_t	 fs_firstfield;	/* historic file system linked list, */
+	int32_t	 fs_unused_1;	/*     used for incore super blocks */
+	int32_t	 fs_sblkno;	/* addr 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_cgoffset;	/* cylinder group offset in cylinder */
+	int32_t	 fs_cgmask;	/* used to calc mod fs_ntrak */
+	time_t	 fs_time;	/* last time written */
+	int32_t	 fs_size;	/* number of blocks in fs */
+	int32_t	 fs_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 */
-	long	fs_minfree;	/* minimum percentage of free blocks */
-	long	fs_rotdelay;	/* num of ms for optimal next block */
-	long	fs_rps;	/* disk revolutions per second */
+	int32_t	 fs_minfree;	/* minimum percentage of free blocks */
+	int32_t	 fs_rotdelay;	/* num of ms for optimal next block */
+	int32_t	 fs_rps;	/* disk revolutions per second */
 /* these fields can be computed from the others */
-	long	fs_bmask;	/* ``blkoff'' calc of blk offsets */
-	long	fs_fmask;	/* ``fragoff'' calc of frag offsets */
-	long	fs_bshift;	/* ``lblkno'' calc of logical blkno */
-	long	fs_fshift;	/* ``numfrags'' calc number of frags */
+	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 */
-	long	fs_maxcontig;	/* max number of contiguous blks */
-	long	fs_maxbpg;	/* max number of blks per cyl group */
+	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 */
-	long	fs_fragshift;	/* block to frag shift */
-	long	fs_fsbtodb;	/* fsbtodb and dbtofsb shift constant */
-	long	fs_sbsize;	/* actual size of super block */
-	long	fs_csmask;	/* csum block offset */
-	long	fs_csshift;	/* csum block number */
-	long	fs_nindir;	/* value of NINDIR */
-	long	fs_inopb;	/* value of INOPB */
-	long	fs_nspf;	/* value of NSPF */
+	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_csmask;	/* csum block offset (now unused) */
+	int32_t	 fs_csshift;	/* csum block number (now unused) */
+	int32_t	 fs_nindir;	/* value of NINDIR */
+	int32_t	 fs_inopb;	/* value of INOPB */
+	int32_t	 fs_nspf;	/* value of NSPF */
 /* yet another configuration parameter */
-	long	fs_optim;	/* optimization preference, see below */
+	int32_t	 fs_optim;	/* optimization preference, see below */
 /* these fields are derived from the hardware */
-	long	fs_npsect;	/* # sectors/track including spares */
-	long	fs_interleave;	/* hardware sector interleave */
-	long	fs_trackskew;	/* sector 0 skew, per track */
-	long	fs_headswitch;	/* head switch time, usec */
-	long	fs_trkseek;	/* track-to-track seek, usec */
+	int32_t	 fs_npsect;	/* # sectors/track including spares */
+	int32_t	 fs_interleave;	/* hardware sector interleave */
+	int32_t	 fs_trackskew;	/* sector 0 skew, per track */
+/* fs_id takes the space of the unused fs_headswitch and fs_trkseek */
+	int32_t	 fs_id[2];	/* unique filesystem id */
 /* sizes determined by number of cylinder groups and their sizes */
-	daddr_t fs_csaddr;	/* blk addr of cyl grp summary area */
-	long	fs_cssize;	/* size of cyl grp summary area */
-	long	fs_cgsize;	/* cylinder group size */
+	int32_t	 fs_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 */
 /* these fields are derived from the hardware */
-	long	fs_ntrak;	/* tracks per cylinder */
-	long	fs_nsect;	/* sectors per track */
-	long  	fs_spc;   	/* sectors per cylinder */
+	int32_t	 fs_ntrak;	/* tracks per cylinder */
+	int32_t	 fs_nsect;	/* sectors per track */
+	int32_t	 fs_spc;	/* sectors per cylinder */
 /* this comes from the disk driver partitioning */
-	long	fs_ncyl;   	/* cylinders in file system */
+	int32_t	 fs_ncyl;	/* cylinders in file system */
 /* these fields can be computed from the others */
-	long	fs_cpg;	/* cylinders per group */
-	long	fs_ipg;	/* inodes per group */
-	long	fs_fpg;	/* blocks per group * fs_frag */
+	int32_t	 fs_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_cstotal;	/* cylinder summary information */
+	struct csum fs_cstotal;	/* cylinder summary information */
 /* these fields are cleared at mount time */
-	char   	fs_fmod;    	/* super block modified flag */
-	char   	fs_clean;    	/* file system is clean flag */
-	char   	fs_ronly;   	/* mounted read-only flag */
-	char   	fs_flags;   	/* currently unused flag */
-	char	fs_fsmnt[MAXMNTLEN];	/* name mounted on */
+	int8_t	 fs_fmod;	/* super block modified flag */
+	int8_t	 fs_clean;	/* file system is clean flag */
+	int8_t	 fs_ronly;	/* mounted read-only flag */
+	int8_t	 fs_flags;	/* see FS_ below */
+	u_char	 fs_fsmnt[MAXMNTLEN]; /* name mounted on */
 /* these fields retain the current block allocation info */
-	long	fs_cgrotor;	/* last cg searched */
-	struct	csum *fs_csp[MAXCSBUFS]; /* list of fs_cs info buffers */
-	long	fs_cpc;	/* cyl per cycle in postbl */
-	short	fs_opostbl[16][8];	/* old rotation block list head */
-	long	fs_sparecon[56];	/* reserved for future constants */
-	quad	fs_qbmask;	/* ~fs_bmask - for use with quad size */
-	quad	fs_qfmask;	/* ~fs_fmask - for use with quad size */
-	long	fs_postblformat; /* format of positional layout tables */
-	long	fs_nrpos;	/* number of rotational positions */
-	long	fs_postbloff;	/* (short) rotation block list head */
-	long	fs_rotbloff;	/* (u_char) blocks for each rotation */
-	long	fs_magic;	/* magic number */
-	u_char	fs_space[1];	/* list of blocks for each rotation */
+	int32_t	 fs_cgrotor;	 /* last cg searched */
+	void	*fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs bufs */
+	u_int8_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 */
+	int32_t	 fs_cpc;	 /* cyl per cycle in postbl */
+	int16_t	 fs_opostbl[16][8]; /* old rotation block list head */
+	int32_t	 fs_snapinum[20];/* reserved for snapshot inode nums */
+	int32_t	 fs_avgfilesize; /* expected average file size */
+	int32_t	 fs_avgfpdir;	 /* expected # of files per directory */
+	int32_t	 fs_sparecon[27];/* reserved for future constants */
+	time_t	 fs_fscktime;	 /* last time fsck(8)ed */
+	int32_t	 fs_contigsumsize; /* size of cluster summary array */
+	int32_t	 fs_maxsymlinklen; /* max length of internal symlink */
+	int32_t	 fs_inodefmt;	 /* format of on-disk inodes */
+	u_int64_t fs_maxfilesize;/* maximum representable file size */
+	int64_t	 fs_qbmask;	 /* ~fs_bmask - for use with quad size */
+	int64_t	 fs_qfmask;	 /* ~fs_fmask - for use with quad size */
+	int32_t	 fs_state;	 /* validate fs_clean field */
+	int32_t	 fs_postblformat;/* format of positional layout tables */
+	int32_t	 fs_nrpos;	 /* number of rotational positions */
+	int32_t	 fs_postbloff;	 /* (u_int16) rotation block list head */
+	int32_t	 fs_rotbloff;	 /* (u_int8) blocks for each rotation */
+	int32_t	 fs_magic;	 /* magic number */
+	u_int8_t fs_space[1];	 /* list of blocks for each rotation */
 /* actually longer */
 };
 .Ed
@@ -191,7 +203,7 @@ 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
-.Fn blksize
+.Fn blksize fs ip lbn
 macro.
 .Pp
 The file system records space availability at the fragment level;
@@ -206,19 +218,19 @@ assumption, so we are stuck with it).
 Thus the root inode is 2.
 .Pp
 The
-.Fa fs_minfree
+.Va fs_minfree
 element gives the minimum acceptable percentage of file system
 blocks that may be free.
-If the freelist drops below this level
+If the freelist drops below this level,
 only the superuser may continue to allocate blocks.
 The
-.Fa fs_minfree
+.Va fs_minfree
 element
 may be set to 0 if no reserve of free blocks is deemed necessary,
 although severe performance degradations will be observed if the
 file system is run at greater than 95% full; thus the default
 value of
-.Fa fs_minfree
+.Va fs_minfree
 is 5%.
 .Pp
 Empirically the best trade-off between block fragmentation and
@@ -227,43 +239,52 @@ fragmentation of 8; thus the default fragment size is an eighth
 of the block size.
 .Pp
 The element
-.Fa fs_optim
+.Va fs_optim
 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.
+allocating blocks
+.Pq Dv FS_OPTTIME ,
+or if it should attempt to minimize the space fragmentation on the disk
+.Pq Dv FS_OPTSPACE .
 If the value of
-.Fa fs_minfree
+.Va fs_minfree
 (see above) is less than 5%,
 then the file system defaults to optimizing for space to avoid
 running out of full sized blocks.
 If the value of
-.Fa fs_minfree
+.Va fs_minfree
 is greater than or equal to 5%,
 fragmentation is unlikely to be problematical, and
 the file system defaults to optimizing for time.
+.Pp
+The
+.Va fs_flags
+element specifies how the filesystem was mounted:
+.Pp
+.Bl -tag -width FS_DOSOFTDEP -offset ind -compact
+.It Dv FS_DOSOFTDEP
+The filesystem was mounted using soft dependencies.
+.It Dv FS_UNCLEAN
+The filesystem was mounted uncleanly.
+.El
 .Ss Cylinder group related limits
 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.
+With the default of 1 distinct
+rotational position, the resolution of the
+summary information is 16ms for a typical 3600 RPM drive.
 .Pp
 The element
-.Fa fs_rotdelay
-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
-.Fa fs_rotdelay
-is 2ms.
+.Va fs_rotdelay
+was once used to tweak block layout.
 .Pp
-Each file system has a statically allocated number of inodes.
-An inode is allocated for each
-.Dv NBPI
-bytes of disk space.
-The inode allocation strategy is extremely conservative.
+Each file system has a statically allocated number of inodes, determined
+by its size and the desired number of file data bytes per inode at the
+time it was created.
+See
+.Xr newfs 8
+for details on how to set this (and other) filesystem parameters.
+By default, the inode allocation strategy is extremely conservative.
 .Pp
 .Dv MINBSIZE
 is the smallest allowable block size.
@@ -275,29 +296,24 @@ it is possible to create files of size
 .Dv MINBSIZE
 must be big enough to hold a cylinder group block,
 thus changes to
-.Fa struct cg
+.Va struct cg
 must keep its size within
 .Dv MINBSIZE .
 Note that super-blocks are never more than size
 .Dv SBSIZE .
 .Pp
 The path name on which the file system is mounted is maintained in
-.Fa fs_fsmnt .
+.Va fs_fsmnt .
 .Dv MAXMNTLEN
 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
-.Dv MAXCSBUFS .
-For a 4096 byte block size, it is currently parameterized for a
-maximum of two million cylinders.
 .Pp
 Per cylinder group information is summarized in blocks allocated
 from the first cylinder group's data blocks.
 These blocks are read in from
-.Fa fs_csaddr
-(size
-.Fa fs_cssize )
+.Va fs_csaddr
+(of size
+.Va fs_cssize )
 in addition to the super-block.
 .Pp
 Note that
@@ -317,19 +333,21 @@ 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
-.Pq Fa fs_cpc .
+.Pq Va fs_cpc .
 The size of the rotational layout
 tables is derived from the number of bytes remaining in
-.Fa struct fs .
+.Va struct fs .
 .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
-.Fa struct cg .
+.Va struct cg .
 .Ss Inodes
-The inode is the focus of all file activity in the
+The
+.Em inode
+is the focus of all file activity in the
 .Tn UNIX
 file system.
 There is a unique inode allocated
@@ -342,7 +360,9 @@ by its device/i-number pair.
 For further information, see the include file
 .Aq Pa ufs/ufs/inode.h .
 .Sh HISTORY
-A super-block structure named filsys appeared in
+A super-block structure named
+.Em filsys
+appeared in
 .At v6 .
 The file system described in this manual appeared
 in