Refactoring of reading and writing of the UFS/FFS superblock.

Specifically reading is done if ffs_sbget() and writing is done
in ffs_sbput(). These functions are exported to libufs via the
sbget() and sbput() functions which then used in the various
filesystem utilities. This work is in preparation for adding
subperblock check hashes.

No functional change intended.

Reviewed by: kib

1 files changed, 76 insertions, 12 deletions

diff --git a/lib/libufs/sbread.3 b/lib/libufs/sbread.3
index 8b5e8c0d4d6b..42342b2f3271 100644
--- a/lib/libufs/sbread.3
+++ b/lib/libufs/sbread.3
@@ -2,6 +2,8 @@
 .\" Date:	June 04, 2003
 .\" Description:
 .\" 	Manual page for libufs functions:
+.\"		sbget(3)
+.\"		sbput(3)
 .\"		sbread(3)
 .\"		sbwrite(3)
 .\"
@@ -9,11 +11,11 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 4, 2003
+.Dd January 19, 2018
 .Dt SBREAD 3
 .Os
 .Sh NAME
-.Nm sbread , sbwrite
+.Nm sbget , sbput , sbread , sbwrite
 .Nd read and write superblocks of a UFS file system
 .Sh LIBRARY
 .Lb libufs
@@ -25,35 +27,95 @@
 .In ufs/ffs/fs.h
 .In libufs.h
 .Ft int
+.Fn sbget "int devfd" "struct fs **fsp" "off_t sblockloc"
+.Ft int
+.Fn sbput "int devfd" "struct fs *fs" "int numaltwrite"
+.Ft int
 .Fn sbread "struct uufsd *disk"
 .Ft int
 .Fn sbwrite "struct uufsd *disk" "int all"
 .Sh DESCRIPTION
 The
+.Fn sbget
+and
 .Fn sbread
+functions provide superblock reads for
+.Xr libufs 3
+consumers.
+The
+.Fn sbput
 and
 .Fn sbwrite
-functions provide superblock reads and writes for
+functions provide superblock writes for
 .Xr libufs 3
 consumers.
+.Pp
+The
+.Fn sbget
+function first allocates a buffer to hold the superblock.
+Using the
+.Va devfd
+file descriptor that references the filesystem disk,
+.Fn sbget
+reads the superblock located at the byte offset specified by
+.Va sblockloc
+into the allocated buffer.
+If successful, it returns a pointer to the buffer containing the superblock in
+.Va fsp .
+The
+.Fn sbget
+function is safe to use in threaded applications.
+.Pp
+The
+.Fn sbput
+function writes the superblock specified by
+.Va fs
+to the location from which it was read on the disk referenced by the
+.Va devfd
+file descriptor.
+Additionally, the
+.Fn sbput
+function will update the first
+.Va numaltwrite
+alternate superblock locations.
+To update all the alternate superblocks,
+specify a
+.Va numaltwrite
+value of
+.Va fs->fs_ncg .
+The
+.Fn sbput
+function is safe to use in threaded applications.
+Note that the
+.Fn sbput
+function needs to be called only if the superblock has been
+modified and the on-disk copy needs to be updated.
+.Pp
 The
 .Fn sbread
-and
+function reads the standard filesystem superblock into the
+.Va d_sb ,
+structure embedded in the given user-land UFS disk structure.
+.Pp
+The
 .Fn sbwrite
-functions operate on the superblock field,
+function writes the superblock from the
 .Va d_sb ,
-associated with a given userland UFS disk structure.
+structure embedded in the given user-land UFS disk structure
+to the location from which it was read.
 Additionally, the
 .Fn sbwrite
-function will write to all superblock locations if the
+function will write to all the alternate superblock locations if the
 .Fa all
 value is non-zero.
 .Sh RETURN VALUES
-.Rv -std sbread sbwrite
+.Rv -std sbget sbput sbread sbwrite
 .Sh ERRORS
-The function
+The
+.Fn sbget
+and
 .Fn sbread
-may fail and set
+functions may fail and set
 .Va errno
 for any of the errors specified for the library function
 .Xr bread 3 .
@@ -62,9 +124,11 @@ Additionally, it may follow the
 error methodologies in situations where no usable superblock could be
 found.
 .Pp
-The function
+The
+.Fn sbput
+and
 .Fn sbwrite
-may fail and set
+functions may fail and set
 .Va errno
 for any of the errors specified for the library function
 .Xr bwrite 3 .