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 January 19, 2018
  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 sbget sbput sbread sbwrite
 113 .Sh ERRORS
 114 The
 115 .Fn sbget
 116 and
 117 .Fn sbread
 118 functions may fail and set
 119 .Va errno
 120 for any of the errors specified for the library function
 121 .Xr bread 3 .
 122 Additionally, it may follow the
 123 .Xr libufs 3
 124 error methodologies in situations where no usable superblock could be
 125 found.
 126 .Pp
 127 The
 128 .Fn sbput
 129 and
 130 .Fn sbwrite
 131 functions may fail and set
 132 .Va errno
 133 for any of the errors specified for the library function
 134 .Xr bwrite 3 .
 135 .Sh SEE ALSO
 136 .Xr bread 3 ,
 137 .Xr bwrite 3 ,
 138 .Xr libufs 3
 139 .Sh HISTORY
 140 These functions first appeared as part of
 141 .Xr libufs 3
 142 in
 143 .Fx 5.0 .
 144 .Sh AUTHORS
 145 .An Juli Mallett Aq Mt jmallett@FreeBSD.org