lib/libufs/cgread.3

   1 .\" Author:     Juli Mallett <jmallett@FreeBSD.org>
   2 .\" Date:       June 04, 2003
   3 .\" Description:
   4 .\"     Manual page for libufs functions:
   5 .\"             cgget(3)
   6 .\"             cgput(3)
   7 .\"             cgread(3)
   8 .\"             cgread1(3)
   9 .\"             cgwrite(3)
  10 .\"             cgwrite1(3)
  11 .\"
  12 .\" This file is in the public domain.
  13 .\"
  14 .\" $FreeBSD$
  15 .\"
  16 .Dd September 2, 2020
  17 .Dt CGREAD 3
  18 .Os
  19 .Sh NAME
  20 .Nm cgget , cgput , cgread , cgread1 , cgwrite , cgwrite1
  21 .Nd read/write cylinder groups of UFS disks
  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 cgget "int devfd" "struct fs *fs" "int cg" "struct cg *cgp"
  33 .Ft int
  34 .Fn cgput "int devfd" "struct fs *fs" "struct cg *cgp"
  35 .Ft int
  36 .Fn cgread "struct uufsd *disk"
  37 .Ft int
  38 .Fn cgread1 "struct uufsd *disk" "int cg"
  39 .Ft int
  40 .Fn cgwrite "struct uufsd *disk"
  41 .Ft int
  42 .Fn cgwrite1 "struct uufsd *disk" "int cg"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn cgget ,
  46 .Fn cgread ,
  47 and
  48 .Fn cgread1
  49 functions provide cylinder group reads for
  50 .Xr libufs 3
  51 consumers.
  52 The
  53 .Fn cgput ,
  54 .Fn cgwrite ,
  55 and
  56 .Fn cgwrite1
  57 functions provide cylinder group writes for
  58 .Xr libufs 3
  59 consumers.
  60 .Pp
  61 The
  62 .Fn cgget
  63 function reads the cylinder group specified by
  64 .Fa cg
  65 into the buffer pointed to by
  66 .Fa cgp
  67 from the filesystem described by the
  68 .Fa fs
  69 superblock using the
  70 .Fa devfd
  71 file descriptor that references the filesystem disk.
  72 The
  73 .Fn cgget
  74 function is the only cylinder group read function that is safe to use
  75 in threaded applications.
  76 .Pp
  77 The
  78 .Fn cgput
  79 function writes the cylinder group specified by
  80 .Va cgp
  81 to the filesystem described by the
  82 .Fa fs
  83 superblock using the
  84 .Fa devfd
  85 file descriptor that references the filesystem disk.
  86 The
  87 .Fn cgput
  88 function is the only cylinder group write function that is safe to use
  89 in threaded applications.
  90 Note that the
  91 .Fn cgput
  92 function needs to be called only if the cylinder group has been
  93 modified and the on-disk copy needs to be updated.
  94 .Pp
  95 The
  96 .Fn cgread1
  97 function reads from the cylinder group specified by
  98 .Fa cg
  99 into the
 100 .Va d_cg
 101 cylinder-group structure in a user-land UFS-disk structure.
 102 It sets the
 103 .Va d_lcg
 104 field to the cylinder group number
 105 .Fa cg .
 106 .Pp
 107 The
 108 .Fn cgread
 109 function operates on sequential cylinder groups.
 110 Calling the
 111 .Fn cgread
 112 function is equivalent to calling
 113 .Fn cgread1
 114 with a cylinder group specifier equivalent to the value of the current
 115 .Va d_ccg
 116 field, and then incrementing the
 117 .Va d_ccg
 118 field.
 119 .Pp
 120 The
 121 .Fn cgwrite
 122 function stores on disk the cylinder group held in the
 123 .Va d_cg
 124 cylinder-group structure in a user-land UFS-disk structure.
 125 .Pp
 126 The
 127 .Fn cgwrite1
 128 function provides no additional functionality over the
 129 .Fn cgwrite
 130 function as there is only one place that a given cylinder group
 131 can correctly be written.
 132 If the caller gets the
 133 .Fa cg
 134 parameter wrong, the function fails with the error
 135 .Er EDOOFUS .
 136 This function remains only to provide backward compatibility.
 137 .Sh RETURN VALUES
 138 The
 139 .Fn cgread
 140 function returns 0 if there are no more cylinder groups to read,
 141 1 if there are more cylinder groups, and \-1 on error.
 142 The
 143 .Fn cgread1
 144 function returns 1 on success and \-1 on error.
 145 The other functions return 0 on success and \-1 on error.
 146 .Sh ERRORS
 147 The
 148 .Fn cgget ,
 149 .Fn cgread ,
 150 and
 151 .Fn cgread1
 152 functions may fail and set
 153 .Va errno
 154 for any of the errors specified for the library function
 155 .Xr bread 3 .
 156 .Pp
 157 The
 158 .Fn cgput ,
 159 .Fn cgwrite ,
 160 and
 161 .Fn cgwrite1
 162 functions may fail and set
 163 .Va errno
 164 for any of the errors specified for the library function
 165 .Xr bwrite 3 .
 166 Additionally the
 167 .Fn cgwrite1
 168 will return the
 169 .Er EDOOFUS
 170 error if the cylinder group specified does not match the
 171 cylinder group that it is requesting to write.
 172 .Sh SEE ALSO
 173 .Xr bread 3 ,
 174 .Xr bwrite 3 ,
 175 .Xr libufs 3
 176 .Sh HISTORY
 177 These functions first appeared as part of
 178 .Xr libufs 3
 179 in
 180 .Fx 5.1 .
 181 .Sh AUTHORS
 182 .An Juli Mallett Aq Mt jmallett@FreeBSD.org
 183 .An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org