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