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