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