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"
  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 If successful, it returns a pointer to the buffer containing the superblock in
  64 .Va fsp .
  65 The
  66 .Fn sbget
  67 function is safe to use in threaded applications.
  68 .Pp
  69 The
  70 .Fn sbput
  71 function writes the superblock specified by
  72 .Va fs
  73 to the location from which it was read on the disk referenced by the
  74 .Va devfd
  75 file descriptor.
  76 Additionally, the
  77 .Fn sbput
  78 function will update the first
  79 .Va numaltwrite
  80 alternate superblock locations.
  81 To update all the alternate superblocks,
  82 specify a
  83 .Va numaltwrite
  84 value of
  85 .Va fs->fs_ncg .
  86 The
  87 .Fn sbput
  88 function is safe to use in threaded applications.
  89 Note that the
  90 .Fn sbput
  91 function needs to be called only if the superblock has been
  92 modified and the on-disk copy needs to be updated.
  93 .Pp
  94 The
  95 .Fn sbread
  96 function reads the standard filesystem superblock into the
  97 .Va d_sb ,
  98 structure embedded in the given user-land UFS disk structure.
  99 .Pp
 100 The
 101 .Fn sbwrite
 102 function writes the superblock from the
 103 .Va d_sb ,
 104 structure embedded in the given user-land UFS disk structure
 105 to the location from which it was read.
 106 Additionally, the
 107 .Fn sbwrite
 108 function will write to all the alternate superblock locations if the
 109 .Fa all
 110 value is non-zero.
 111 .Sh RETURN VALUES
 112 .Rv -std sbread sbwrite
 113 The
 114 .Fn sbget
 115 and
 116 .Fn sbput
 117 functions return the value 0 if successful;
 118 otherwise they return one of the errors described below.
 119 .Sh ERRORS
 120 The errors returned by
 121 .Fn sbget
 122 and
 123 .Fn sbread
 124 include any of the errors specified for the library function
 125 .Xr bread 3 .
 126 Additionally, they may follow the
 127 .Xr libufs 3
 128 error methodologies in situations where no usable superblock could be
 129 found.
 130 .Pp
 131 The errors returned by
 132 .Fn sbput
 133 and
 134 .Fn sbwrite
 135 include any of the errors specified for the library function
 136 .Xr bwrite 3 .
 137 .Sh SEE ALSO
 138 .Xr bread 3 ,
 139 .Xr bwrite 3 ,
 140 .Xr libufs 3
 141 .Sh HISTORY
 142 These functions first appeared as part of
 143 .Xr libufs 3
 144 in
 145 .Fx 5.0 .
 146 .Sh AUTHORS
 147 .An Juli Mallett Aq Mt jmallett@FreeBSD.org
 148 .An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org