lib/libufs/sbread.3

   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
  42 The
  43 .Fn sbget ,
  44 .Fn sbsearch ,
  45 .Fn sbread ,
  46 and
  47 .Fn sbfind
  48 functions provide superblock reads for
  49 .Xr libufs 3
  50 consumers.
  51 The
  52 .Fn sbput
  53 and
  54 .Fn sbwrite
  55 functions provide superblock writes for
  56 .Xr libufs 3
  57 consumers.
  58 .Pp
  59 The
  60 .Fn sbget
  61 and
  62 .Fn sbsearch
  63 functions first allocate a buffer to hold the superblock.
  64 Using the
  65 .Va devfd
  66 file descriptor that references the filesystem disk,
  67 .Fn sbget
  68 reads the superblock located at the byte offset specified by
  69 .Va sblockloc
  70 into the allocated buffer.
  71 The value
  72 .Cm UFS_STDSB
  73 may be specified for
  74 .Va sblockloc
  75 to request that the standard location for the superblock be read.
  76 The
  77 .Fn sbsearch
  78 function uses the
  79 .Va devfd
  80 file descriptor that references the filesystem disk,
  81 to search first for the superblock at the standard location.
  82 If it is not found or is too damaged to use
  83 .Fn sbsearch
  84 will attempt to find one of the filesystem's alternate superblocks.
  85 Flags are specified by
  86 .Em or Ns 'ing
  87 the following values:
  88 .Pp
  89 .Bl -tag -width UFS_NOCSUM
  90 .It Cm UFS_NOCSUM
  91 Causes only the superblock itself to be returned, but does not read in any
  92 auxiliary data structures like the cylinder group summary information.
  93 .It Cm UFS_NOMSG
  94 Indicates that superblock inconsistency error messages should not be printed.
  95 .El
  96 .Pp
  97 If successful,
  98 .Fn sbget
  99 and
 100 .Fn sbsearch
 101 functions return a pointer to the buffer containing the superblock in
 102 .Va fsp .
 103 The
 104 .Fn sbget
 105 and
 106 .Fn sbsearch
 107 functions are safe to use in threaded applications.
 108 .Pp
 109 The
 110 .Fn sbput
 111 function writes the superblock specified by
 112 .Va fs
 113 to the location from which it was read on the disk referenced by the
 114 .Va devfd
 115 file descriptor.
 116 Additionally, the
 117 .Fn sbput
 118 function will update the first
 119 .Va numaltwrite
 120 alternate superblock locations.
 121 To update all the alternate superblocks,
 122 specify a
 123 .Va numaltwrite
 124 value of
 125 .Va fs->fs_ncg .
 126 The
 127 .Fn sbput
 128 function is safe to use in threaded applications.
 129 Note that the
 130 .Fn sbput
 131 function needs to be called only if the superblock has been
 132 modified and the on-disk copy needs to be updated.
 133 .Pp
 134 The
 135 .Fn sbread
 136 function reads the standard filesystem superblock.
 137 The
 138 .Fn sbfind
 139 function tries to find a usable superblock.
 140 It searchs first for the superblock at the standard location.
 141 If it is not found or is too damaged to use
 142 .Fn sbfind
 143 will attempt to find one of the filesystem's alternate superblocks.
 144 If successful
 145 .Fn sbread
 146 and
 147 .Fn sbfind
 148 return a superblock in the
 149 .Va d_sb ,
 150 structure embedded in the given user-land UFS disk structure.
 151 .Pp
 152 The
 153 .Fn sbwrite
 154 function writes the superblock from the
 155 .Va d_sb ,
 156 structure embedded in the given user-land UFS disk structure
 157 to the location from which it was read.
 158 Additionally, the
 159 .Fn sbwrite
 160 function will write to all the alternate superblock locations if the
 161 .Fa all
 162 value is non-zero.
 163 .Sh RETURN VALUES
 164 .Rv -std sbread sbwrite
 165 The
 166 .Fn sbget ,
 167 .Fn sbsearch ,
 168 and
 169 .Fn sbput
 170 functions return the value 0 if successful;
 171 otherwise they return one of the errors described below.
 172 .Sh ERRORS
 173 The errors returned by
 174 .Fn sbget ,
 175 .Fn sbsearch ,
 176 .Fn sbread ,
 177 and
 178 .Fn sbfind ,
 179 include any of the errors specified for the library function
 180 .Xr bread 3 .
 181 Additionally, they may follow the
 182 .Xr libufs 3
 183 error methodologies in situations where no usable superblock could be
 184 found.
 185 .Pp
 186 The errors returned by
 187 .Fn sbput
 188 and
 189 .Fn sbwrite
 190 include 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
 197 These functions first appeared as part of
 198 .Xr libufs 3
 199 in
 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