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