docs: OpenBSD Man Pages Added

1 files changed, 383 insertions, 0 deletions

diff --git a/static/openbsd/man5/fs.5 b/static/openbsd/man5/fs.5
new file mode 100644
index 00000000..73cc418d
--- /dev/null
+++ b/static/openbsd/man5/fs.5
@@ -0,0 +1,383 @@
+.\"	$OpenBSD: fs.5,v 1.20 2024/02/03 18:51:57 beck Exp $
+.\"	$NetBSD: fs.5,v 1.3 1994/11/30 19:31:17 jtc Exp $
+.\"
+.\" Copyright (c) 1983, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)fs.5	8.2 (Berkeley) 4/19/94
+.\"
+.Dd $Mdocdate: February 3 2024 $
+.Dt FS 5
+.Os
+.Sh NAME
+.Nm fs ,
+.Nm inode
+.Nd format of file system volume
+.Sh SYNOPSIS
+.In sys/types.h
+.In ufs/ffs/fs.h
+.In ufs/ufs/inode.h
+.Sh DESCRIPTION
+The files
+.In ufs/ffs/fs.h
+and
+.In 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).
+.Pp
+The block size and number of blocks which
+comprise a file system are parameters of the file system.
+Sectors beginning at
+.Dv BBLOCK
+and continuing for
+.Dv BBSIZE
+are used
+for a disklabel and for some hardware primary
+and secondary bootstrapping programs.
+.Pp
+The actual file system begins at sector
+.Dv SBLOCK
+with the
+.Em super-block
+that is of size
+.Dv SBSIZE .
+The following structure describes the super-block and is
+from the file
+.In ufs/ffs/fs.h :
+.Bd -literal
+#define	FS_MAGIC 0x011954
+struct 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 / frags */
+	int32_t	 fs_cblkno;	/* offset of cyl-block / frags */
+	int32_t	 fs_iblkno;	/* offset of inode-blocks / frags */
+	int32_t	 fs_dblkno;	/* offset of first data / frags */
+	int32_t	 fs_cgoffset;	/* cylinder group offset in cylinder */
+	int32_t	 fs_cgmask;	/* used to calc mod fs_ntrak */
+	int32_t	 fs_ffs1_time;	/* last time written */
+	int32_t	 fs_ffs1_size;	/* # of blocks in fs / frags */
+	int32_t	 fs_ffs1_dsize;	/* # of data blocks in fs */
+	int32_t	 fs_ncg;	/* # of cylinder groups */
+	int32_t	 fs_bsize;	/* size of basic blocks / bytes */
+	int32_t	 fs_fsize;	/* size of frag blocks / bytes */
+	int32_t	 fs_frag;	/* # of frags in a block in fs */
+/* these are configuration parameters */
+	int32_t	 fs_minfree;	/* minimum percentage of free blocks */
+	int32_t	 fs_rotdelay;	/* # of ms for optimal next block */
+	int32_t	 fs_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 # of frags */
+/* these are configuration parameters */
+	int32_t	 fs_maxcontig;	/* max # of contiguous blks */
+	int32_t	 fs_maxbpg;	/* max # 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_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;	/* inodes per file system block */
+	int32_t	 fs_nspf;	/* DEV_BSIZE sectors per frag */
+/* yet another configuration parameter */
+	int32_t	 fs_optim;	/* optimization preference, see below */
+/* these fields are derived from the hardware */
+	int32_t	 fs_npsect;	/* DEV_BSIZE sectors/track + spares */
+	int32_t	 fs_interleave;	/* DEV_BSIZE sector interleave */
+	int32_t	 fs_trackskew;	/* sector 0 skew, per track */
+/* fs_id takes the space of unused fs_headswitch and fs_trkseek fields */
+	int32_t	 fs_id[2];	/* unique filesystem id */
+/* sizes determined by number of cylinder groups and their sizes */
+	int32_t	 fs_ffs1_csaddr; /* blk addr of cyl grp summary area */
+	int32_t	 fs_cssize;	/* cyl grp summary area size / bytes */
+	int32_t	 fs_cgsize;	/* cyl grp block size / bytes */
+/* these fields are derived from the hardware */
+	int32_t	 fs_ntrak;	/* tracks per cylinder */
+	int32_t	 fs_nsect;	/* DEV_BSIZE sectors per track */
+	int32_t	 fs_spc;	/* DEV_BSIZE sectors per cylinder */
+/* this comes from the disk driver partitioning */
+	int32_t	 fs_ncyl;	/* cylinders in file system */
+/* these fields can be computed from the others */
+	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_ffs1_cstotal; /* cylinder summary information */
+/* these fields are cleared at mount time */
+	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_ffs1_flags;	/* see FS_ below */
+	u_char	 fs_fsmnt[MAXMNTLEN]; /* name mounted on */
+	u_char	 fs_volname[MAXVOLLEN]; /* volume name */
+	u_int64_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 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 */
+	u_char	*fs_active;	 /* reserved for snapshots */
+	int32_t	 fs_cpc;	 /* cyl per cycle in postbl */
+/* this area is only allocated if fs_ffs1_flags & FS_FLAGS_UPDATED */
+	int32_t	 fs_maxbsize;	/* maximum blocking factor permitted */
+	int64_t	 fs_spareconf64[17]; /* old rotation block list head */
+	int64_t	 fs_sblockloc;	/* offset of standard super block */
+	struct csum_total fs_cstotal; /* cylinder summary information */
+	int64_t	 fs_time;	/* time last written */
+	int64_t	 fs_size;	/* number of blocks in fs */
+	int64_t	 fs_dsize;	/* number of data blocks in fs */
+	int64_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];/* space reserved for snapshots */
+/* back to stuff that has been around a while */
+	int32_t	 fs_avgfilesize; /* expected average file size */
+	int32_t	 fs_avgfpdir;	 /* expected # of files per directory */
+	int32_t	 fs_sparecon[26];/* reserved for future constants */
+	u_int32_t fs_flags;	/* see FS_ flags below */
+	int32_t	 fs_fscktime;	 /* last time fsck(8)ed */
+	int32_t	 fs_contigsumsize; /* size of cluster summary array */
+	int32_t	 fs_maxsymlinklen; /* max length of an 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
+.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.
+.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.
+.Pp
+Addresses stored in inodes are capable of addressing fragments
+of
+.Dq blocks .
+File system blocks of at most size
+.Dv MAXBSIZE
+can
+be optionally broken into 2, 4, or 8 pieces, each of which is
+addressable; these pieces may be
+.Dv DEV_BSIZE ,
+or some multiple of a
+.Dv DEV_BSIZE
+unit.
+.Pp
+Large files consist of exclusively large data blocks.
+To avoid undue wasted disk space, the last data block of a small file is
+allocated 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
+.Fn blksize fs ip lbn
+macro.
+.Pp
+The file system records space availability at the fragment level;
+to determine block availability, aligned fragments are examined.
+.Pp
+The root inode is the root of the file system.
+Inode 0 can't be used for normal purposes and
+historically bad blocks were linked to inode 1
+(inode 1 is no longer used for
+this purpose; however, numerous dump tapes make this
+assumption, so we are stuck with it).
+Thus the root inode is 2.
+.Pp
+The
+.Va fs_minfree
+element gives the minimum acceptable percentage of file system
+blocks that may be free.
+If the freelist drops below this level,
+only the superuser may continue to allocate blocks.
+The
+.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
+.Va fs_minfree
+is 5%.
+.Pp
+Empirically the best trade-off between block fragmentation and
+overall disk utilization at a loading of 95% comes with a
+fragmentation of 8; thus the default fragment size is an eighth
+of the block size.
+.Pp
+The element
+.Va fs_optim
+specifies whether the file system should try to minimize the time spent
+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
+.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
+.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_UNCLEAN -offset ind -compact
+.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 1 distinct
+rotational position, the resolution of the
+summary information is 16ms for a typical 3600 RPM drive.
+.Pp
+The element
+.Va fs_rotdelay
+was once used to tweak block layout.
+.Pp
+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.
+With a
+.Dv MINBSIZE
+of 4096
+it is possible to create files of size
+2^32 with only two levels of indirection.
+.Dv MINBSIZE
+must be big enough to hold a cylinder group block,
+thus changes to
+.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
+.Va fs_fsmnt .
+.Dv MAXMNTLEN
+defines the amount of space allocated in
+the super-block for this name.
+.Pp
+Per cylinder group information is summarized in blocks allocated
+from the first cylinder group's data blocks.
+These blocks are read in from
+.Va fs_csaddr
+(of size
+.Va fs_cssize )
+in addition to the super-block.
+.Pp
+Note that
+.Fn sizeof "struct csum"
+must be a power of two in order for
+the
+.Fn fs_cs
+macro to work.
+.Ss Super-block for a file system
+The size of the rotational layout tables
+is limited by the fact that the super-block is of size
+.Dv SBSIZE .
+The size of these tables is inversely
+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
+.Pq Va fs_cpc .
+The size of the rotational layout
+tables is derived from the number of bytes remaining in
+.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
+.Va struct cg .
+.Ss Inodes
+The
+.Em inode
+is the focus of all file activity in the
+.Tn UNIX
+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
+.Dq named
+by its device/i-number pair.
+For further information, see the include file
+.In ufs/ufs/inode.h .
+.Sh HISTORY
+A super-block structure named
+.Em filsys
+appeared in
+.At v6 .
+The file system described in this manual appeared
+in
+.Bx 4.2 .