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 .\"             sbput(3)
   7 .\"             sbread(3)
   8 .\"             sbwrite(3)
   9 .\"
  10 .\" This file is in the public domain.
  11 .\"
  12 .\" $FreeBSD$
  13 .\"
  14 .Dd September 2, 2020
  15 .Dt SBREAD 3
  16 .Os
  17 .Sh NAME
  18 .Nm sbget , sbput , sbread , 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 sbput "int devfd" "struct fs *fs" "int numaltwrite"
  33 .Ft int
  34 .Fn sbread "struct uufsd *disk"
  35 .Ft int
  36 .Fn sbwrite "struct uufsd *disk" "int all"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn sbget
  40 and
  41 .Fn sbread
  42 functions provide superblock reads for
  43 .Xr libufs 3
  44 consumers.
  45 The
  46 .Fn sbput
  47 and
  48 .Fn sbwrite
  49 functions provide superblock writes for
  50 .Xr libufs 3
  51 consumers.
  52 .Pp
  53 The
  54 .Fn sbget
  55 function first allocates a buffer to hold the superblock.
  56 Using the
  57 .Va devfd
  58 file descriptor that references the filesystem disk,
  59 .Fn sbget
  60 reads the superblock located at the byte offset specified by
  61 .Va sblockloc
  62 into the allocated buffer.
  63 The value
  64 .Cm UFS_STDSB
  65 may be specified for
  66 .Va sblockloc
  67 to request that the standard location for the superblock be read.
  68 Flags are specified by
  69 .Em or Ns 'ing
  70 the following values:
  71 .Pp
  72 .Bl -tag -width UFS_NOHASHFAIL
  73 .It Cm UFS_NOHASHFAIL
  74 Will note if the check hash is wrong but will still return the superblock.
  75 .It Cm UFS_NOMSG
  76 Indicates that superblock inconsistency error messages should not be printed.
  77 .It Cm UFS_NOCSUM
  78 Causes only the superblock itself to be returned, but does not read in any auxiliary data structures like the cylinder group summary information.
  79 .El
  80 .Pp
  81 If successful,
  82 .Fn sbget
  83 returns a pointer to the buffer containing the superblock in
  84 .Va fsp .
  85 The
  86 .Fn sbget
  87 function is safe to use in threaded applications.
  88 .Pp
  89 The
  90 .Fn sbput
  91 function writes the superblock specified by
  92 .Va fs
  93 to the location from which it was read on the disk referenced by the
  94 .Va devfd
  95 file descriptor.
  96 Additionally, the
  97 .Fn sbput
  98 function will update the first
  99 .Va numaltwrite
 100 alternate superblock locations.
 101 To update all the alternate superblocks,
 102 specify a
 103 .Va numaltwrite
 104 value of
 105 .Va fs->fs_ncg .
 106 The
 107 .Fn sbput
 108 function is safe to use in threaded applications.
 109 Note that the
 110 .Fn sbput
 111 function needs to be called only if the superblock has been
 112 modified and the on-disk copy needs to be updated.
 113 .Pp
 114 The
 115 .Fn sbread
 116 function reads the standard filesystem superblock into the
 117 .Va d_sb ,
 118 structure embedded in the given user-land UFS disk structure.
 119 .Pp
 120 The
 121 .Fn sbwrite
 122 function writes the superblock from the
 123 .Va d_sb ,
 124 structure embedded in the given user-land UFS disk structure
 125 to the location from which it was read.
 126 Additionally, the
 127 .Fn sbwrite
 128 function will write to all the alternate superblock locations if the
 129 .Fa all
 130 value is non-zero.
 131 .Sh RETURN VALUES
 132 .Rv -std sbread sbwrite
 133 The
 134 .Fn sbget
 135 and
 136 .Fn sbput
 137 functions return the value 0 if successful;
 138 otherwise they return one of the errors described below.
 139 .Sh ERRORS
 140 The errors returned by
 141 .Fn sbget
 142 and
 143 .Fn sbread
 144 include any of the errors specified for the library function
 145 .Xr bread 3 .
 146 Additionally, they may follow the
 147 .Xr libufs 3
 148 error methodologies in situations where no usable superblock could be
 149 found.
 150 .Pp
 151 The errors returned by
 152 .Fn sbput
 153 and
 154 .Fn sbwrite
 155 include any of the errors specified for the library function
 156 .Xr bwrite 3 .
 157 .Sh SEE ALSO
 158 .Xr bread 3 ,
 159 .Xr bwrite 3 ,
 160 .Xr libufs 3
 161 .Sh HISTORY
 162 These functions first appeared as part of
 163 .Xr libufs 3
 164 in
 165 .Fx 5.0 .
 166 .Sh AUTHORS
 167 .An Juli Mallett Aq Mt jmallett@FreeBSD.org
 168 .An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org