diff options
Diffstat (limited to 'lib/libufs/sbread.3')
| -rw-r--r-- | lib/libufs/sbread.3 | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/lib/libufs/sbread.3 b/lib/libufs/sbread.3 new file mode 100644 index 000000000000..47c32ce029ae --- /dev/null +++ b/lib/libufs/sbread.3 @@ -0,0 +1,203 @@ +.\" Author: Juli Mallett <jmallett@FreeBSD.org> +.\" Date: June 04, 2003 +.\" Description: +.\" Manual page for libufs functions: +.\" sbget(3) +.\" sbsearch(3) +.\" sbput(3) +.\" sbread(3) +.\" sbfind(3) +.\" sbwrite(3) +.\" +.\" This file is in the public domain. +.\" +.Dd August 8, 2022 +.Dt SBREAD 3 +.Os +.Sh NAME +.Nm sbget , sbsearch , sbput , sbread , sbfind , sbwrite +.Nd read and write superblocks of a UFS file system +.Sh LIBRARY +.Lb libufs +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In ufs/ufs/ufsmount.h +.In ufs/ufs/dinode.h +.In ufs/ffs/fs.h +.In libufs.h +.Ft int +.Fn sbget "int devfd" "struct fs **fsp" "off_t sblockloc" "int flags" +.Ft int +.Fn sbsearch "int devfd" "struct fs **fsp" "int flags" +.Ft int +.Fn sbput "int devfd" "struct fs *fs" "int numaltwrite" +.Ft int +.Fn sbread "struct uufsd *disk" +.Ft int +.Fn sbfind "struct uufsd *disk" "int flags" +.Ft int +.Fn sbwrite "struct uufsd *disk" "int all" +.Sh DESCRIPTION +The +.Fn sbget , +.Fn sbsearch , +.Fn sbread , +and +.Fn sbfind +functions provide superblock reads for +.Xr libufs 3 +consumers. +The +.Fn sbput +and +.Fn sbwrite +functions provide superblock writes for +.Xr libufs 3 +consumers. +.Pp +The +.Fn sbget +and +.Fn sbsearch +functions first allocate 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. +The value +.Cm UFS_STDSB +may be specified for +.Va sblockloc +to request that the standard location for the superblock be read. +The +.Fn sbsearch +function uses the +.Va devfd +file descriptor that references the filesystem disk, +to search first for the superblock at the standard location. +If it is not found or is too damaged to use +.Fn sbsearch +will attempt to find one of the filesystem's alternate superblocks. +Flags are specified by +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width UFS_NOCSUM +.It Cm UFS_NOCSUM +Causes only the superblock itself to be returned, but does not read in any +auxiliary data structures like the cylinder group summary information. +.It Cm UFS_NOMSG +Indicates that superblock inconsistency error messages should not be printed. +.El +.Pp +If successful, +.Fn sbget +and +.Fn sbsearch +functions return a pointer to the buffer containing the superblock in +.Va fsp . +The +.Fn sbget +and +.Fn sbsearch +functions are 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 +function reads the standard filesystem superblock. +The +.Fn sbfind +function tries to find a usable superblock. +It searchs first for the superblock at the standard location. +If it is not found or is too damaged to use +.Fn sbfind +will attempt to find one of the filesystem's alternate superblocks. +If successful +.Fn sbread +and +.Fn sbfind +return a superblock in the +.Va d_sb , +structure embedded in the given user-land UFS disk structure. +.Pp +The +.Fn sbwrite +function writes the superblock from the +.Va d_sb , +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 the alternate superblock locations if the +.Fa all +value is non-zero. +.Sh RETURN VALUES +.Rv -std sbread sbwrite +The +.Fn sbget , +.Fn sbsearch , +and +.Fn sbput +functions return the value 0 if successful; +otherwise they return one of the errors described below. +.Sh ERRORS +The errors returned by +.Fn sbget , +.Fn sbsearch , +.Fn sbread , +and +.Fn sbfind , +include any of the errors specified for the library function +.Xr bread 3 . +Additionally, they may follow the +.Xr libufs 3 +error methodologies in situations where no usable superblock could be +found. +.Pp +The errors returned by +.Fn sbput +and +.Fn sbwrite +include any of the errors specified for the library function +.Xr bwrite 3 . +.Sh SEE ALSO +.Xr bread 3 , +.Xr bwrite 3 , +.Xr libufs 3 +.Sh HISTORY +These functions first appeared as part of +.Xr libufs 3 +in +.Fx 5.0 . +.Sh AUTHORS +.An Juli Mallett Aq Mt jmallett@FreeBSD.org +.An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org |