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