1.\" Author: Juli Mallett <jmallett@FreeBSD.org> 2.\" Date: June 04, 2003 3.\" Description: 4.\" Manual page for libufs functions: 5.\" sbget(3) 6.\" sbsearch(3) 7.\" sbput(3) 8.\" sbread(3) 9.\" sbfind(3) 10.\" sbwrite(3) 11.\" 12.\" This file is in the public domain. 13.\" 14.\" $FreeBSD$ 15.\" 16.Dd August 8, 2022 17.Dt SBREAD 3 18.Os 19.Sh NAME 20.Nm sbget , sbsearch , sbput , sbread , sbfind , sbwrite 21.Nd read and write superblocks of a UFS file system 22.Sh LIBRARY 23.Lb libufs 24.Sh SYNOPSIS 25.In sys/param.h 26.In sys/mount.h 27.In ufs/ufs/ufsmount.h 28.In ufs/ufs/dinode.h 29.In ufs/ffs/fs.h 30.In libufs.h 31.Ft int 32.Fn sbget "int devfd" "struct fs **fsp" "off_t sblockloc" "int flags" 33.Ft int 34.Fn sbsearch "int devfd" "struct fs **fsp" "int flags" 35.Ft int 36.Fn sbput "int devfd" "struct fs *fs" "int numaltwrite" 37.Ft int 38.Fn sbread "struct uufsd *disk" 39.Ft int 40.Fn sbfind "struct uufsd *disk" "int flags" 41.Ft int 42.Fn sbwrite "struct uufsd *disk" "int all" 43.Sh DESCRIPTION 44The 45.Fn sbget , 46.Fn sbsearch , 47.Fn sbread , 48and 49.Fn sbfind 50functions provide superblock reads for 51.Xr libufs 3 52consumers. 53The 54.Fn sbput 55and 56.Fn sbwrite 57functions provide superblock writes for 58.Xr libufs 3 59consumers. 60.Pp 61The 62.Fn sbget 63and 64.Fn sbsearch 65functions first allocate a buffer to hold the superblock. 66Using the 67.Va devfd 68file descriptor that references the filesystem disk, 69.Fn sbget 70reads the superblock located at the byte offset specified by 71.Va sblockloc 72into the allocated buffer. 73The value 74.Cm UFS_STDSB 75may be specified for 76.Va sblockloc 77to request that the standard location for the superblock be read. 78The 79.Fn sbsearch 80function uses the 81.Va devfd 82file descriptor that references the filesystem disk, 83to search first for the superblock at the standard location. 84If it is not found or is too damaged to use 85.Fn sbsearch 86will attempt to find one of the filesystem's alternate superblocks. 87Flags are specified by 88.Em or Ns 'ing 89the following values: 90.Pp 91.Bl -tag -width UFS_NOCSUM 92.It Cm UFS_NOCSUM 93Causes only the superblock itself to be returned, but does not read in any 94auxiliary data structures like the cylinder group summary information. 95.It Cm UFS_NOMSG 96Indicates that superblock inconsistency error messages should not be printed. 97.El 98.Pp 99If successful, 100.Fn sbget 101and 102.Fn sbsearch 103functions return a pointer to the buffer containing the superblock in 104.Va fsp . 105The 106.Fn sbget 107and 108.Fn sbsearch 109functions are safe to use in threaded applications. 110.Pp 111The 112.Fn sbput 113function writes the superblock specified by 114.Va fs 115to the location from which it was read on the disk referenced by the 116.Va devfd 117file descriptor. 118Additionally, the 119.Fn sbput 120function will update the first 121.Va numaltwrite 122alternate superblock locations. 123To update all the alternate superblocks, 124specify a 125.Va numaltwrite 126value of 127.Va fs->fs_ncg . 128The 129.Fn sbput 130function is safe to use in threaded applications. 131Note that the 132.Fn sbput 133function needs to be called only if the superblock has been 134modified and the on-disk copy needs to be updated. 135.Pp 136The 137.Fn sbread 138function reads the standard filesystem superblock. 139The 140.Fn sbfind 141function tries to find a usable superblock. 142It searchs first for the superblock at the standard location. 143If it is not found or is too damaged to use 144.Fn sbfind 145will attempt to find one of the filesystem's alternate superblocks. 146If successful 147.Fn sbread 148and 149.Fn sbfind 150return a superblock in the 151.Va d_sb , 152structure embedded in the given user-land UFS disk structure. 153.Pp 154The 155.Fn sbwrite 156function writes the superblock from the 157.Va d_sb , 158structure embedded in the given user-land UFS disk structure 159to the location from which it was read. 160Additionally, the 161.Fn sbwrite 162function will write to all the alternate superblock locations if the 163.Fa all 164value is non-zero. 165.Sh RETURN VALUES 166.Rv -std sbread sbwrite 167The 168.Fn sbget , 169.Fn sbsearch , 170and 171.Fn sbput 172functions return the value 0 if successful; 173otherwise they return one of the errors described below. 174.Sh ERRORS 175The errors returned by 176.Fn sbget , 177.Fn sbsearch , 178.Fn sbread , 179and 180.Fn sbfind , 181include any of the errors specified for the library function 182.Xr bread 3 . 183Additionally, they may follow the 184.Xr libufs 3 185error methodologies in situations where no usable superblock could be 186found. 187.Pp 188The errors returned by 189.Fn sbput 190and 191.Fn sbwrite 192include any of the errors specified for the library function 193.Xr bwrite 3 . 194.Sh SEE ALSO 195.Xr bread 3 , 196.Xr bwrite 3 , 197.Xr libufs 3 198.Sh HISTORY 199These functions first appeared as part of 200.Xr libufs 3 201in 202.Fx 5.0 . 203.Sh AUTHORS 204.An Juli Mallett Aq Mt jmallett@FreeBSD.org 205.An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org 206