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 .