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 January 19, 2018
  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 "struct uufsd *disk" "int cg" "struct cg *cgp"
  33 .Ft int
  34 .Fn cgput "struct uufsd *disk" "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 disk referenced by the user-land UFS-disk structure.
  68 The
  69 .Fn cgget
  70 function is the only cylinder group read function that is safe to use
  71 in threaded applications.
  72 .Pp
  73 The
  74 .Fn cgput
  75 function writes the cylinder group specified by
  76 .Va cgp
  77 to the disk referenced by the user-land UFS-disk structure.
  78 The
  79 .Fn cgput
  80 function is the only cylinder group write function that is safe to use
  81 in threaded applications.
  82 Note that the
  83 .Fn cgput
  84 function needs to be called only if the cylinder group has been
  85 modified and the on-disk copy needs to be updated.
  86 .Pp
  87 The
  88 .Fn cgread1
  89 function reads from the cylinder group specified by
  90 .Fa cg
  91 into the
  92 .Va d_cg
  93 cylinder-group structure in a user-land UFS-disk structure.
  94 It sets the
  95 .Va d_lcg
  96 field to the cylinder group number
  97 .Fa cg .
  98 .Pp
  99 The
 100 .Fn cgread
 101 function operates on sequential cylinder groups.
 102 Calling the
 103 .Fn cgread
 104 function is equivalent to calling
 105 .Fn cgread1
 106 with a cylinder group specifier equivalent to the value of the current
 107 .Va d_ccg
 108 field, and then incrementing the
 109 .Va d_ccg
 110 field.
 111 .Pp
 112 The
 113 .Fn cgwrite
 114 function stores on disk the cylinder group held in the
 115 .Va d_cg
 116 cylinder-group structure in a user-land UFS-disk structure.
 117 .Pp
 118 The
 119 .Fn cgwrite1
 120 function provides no additional functionality over the
 121 .Fn cgwrite
 122 function as there is only one place that a given cylinder group
 123 can correctly be written.
 124 If the caller gets the
 125 .Fa cg
 126 parameter wrong, the function fails with the error
 127 .Er EDOOFUS .
 128 This function remains only to provide backward compatibility.
 129 .Sh RETURN VALUES
 130 The
 131 .Fn cgread
 132 function returns 0 if there are no more cylinder groups to read,
 133 1 if there are more cylinder groups, and \-1 on error.
 134 The
 135 .Fn cgread1
 136 function returns 1 on success and \-1 on error.
 137 The other functions return 0 on success and \-1 on error.
 138 .Sh ERRORS
 139 The
 140 .Fn cgget ,
 141 .Fn cgread ,
 142 and
 143 .Fn cgread1
 144 functions may fail and set
 145 .Va errno
 146 for any of the errors specified for the library function
 147 .Xr bread 3 .
 148 .Pp
 149 The
 150 .Fn cgput ,
 151 .Fn cgwrite ,
 152 and
 153 .Fn cgwrite1
 154 functions may fail and set
 155 .Va errno
 156 for any of the errors specified for the library function
 157 .Xr bwrite 3 .
 158 Additionally the
 159 .Fn cgwrite1
 160 will return the
 161 .Er EDOOFUS
 162 error if the cylinder group specified does not match the
 163 cylinder group that it is requesting to write.
 164 .Sh SEE ALSO
 165 .Xr bread 3 ,
 166 .Xr bwrite 3 ,
 167 .Xr libufs 3
 168 .Sh HISTORY
 169 These functions first appeared as part of
 170 .Xr libufs 3
 171 in
 172 .Fx 5.1 .
 173 .Sh AUTHORS
 174 .An Juli Mallett Aq Mt jmallett@FreeBSD.org