aboutsummaryrefslogtreecommitdiff
path: root/lib/libufs/cgread.3
diff options
context:
space:
mode:
authorKirk McKusick <mckusick@FreeBSD.org>2018-01-17 17:58:24 +0000
committerKirk McKusick <mckusick@FreeBSD.org>2018-01-17 17:58:24 +0000
commit72f854ce8f359100d957a07da44ae98591d3dfd9 (patch)
tree6603c949e870e1510902951cb2391e730e174006 /lib/libufs/cgread.3
parent64e12b4140ffeaea04b7230d506ee0326e3b077d (diff)
downloadsrc-72f854ce8f359100d957a07da44ae98591d3dfd9.tar.gz
src-72f854ce8f359100d957a07da44ae98591d3dfd9.zip
Correct fsck journal-recovery code to update a cylinder-group
check-hash after making changes to the cylinder group. The problem was that the journal-recovery code was calling the libufs bwrite() function instead of the cgput() function. The cgput() function updates the cylinder-group check-hash before writing the cylinder group. This change required the additions of the cgget() and cgput() functions to the libufs API to avoid a gratuitous bcopy of every cylinder group to be read or written. These new functions have been added to the libufs manual pages. This was the first opportunity that I have had to use and document the use of the EDOOFUS error code. Reviewed by: kib Reported by: emaste and others
Notes
Notes: svn path=/head/; revision=328092
Diffstat (limited to 'lib/libufs/cgread.3')
-rw-r--r--lib/libufs/cgread.3118
1 files changed, 93 insertions, 25 deletions
diff --git a/lib/libufs/cgread.3 b/lib/libufs/cgread.3
index 28feaad11764..1feb93bed133 100644
--- a/lib/libufs/cgread.3
+++ b/lib/libufs/cgread.3
@@ -2,19 +2,22 @@
.\" Date: June 04, 2003
.\" Description:
.\" Manual page for libufs functions:
+.\" cgget(3)
+.\" cgput(3)
.\" cgread(3)
.\" cgread1(3)
+.\" cgwrite(3)
.\" cgwrite1(3)
.\"
.\" This file is in the public domain.
.\"
.\" $FreeBSD$
.\"
-.Dd June 4, 2003
+.Dd January 19, 2018
.Dt CGREAD 3
.Os
.Sh NAME
-.Nm cgread , cgread1, cgwrite1
+.Nm cgget , cgput , cgread , cgread1 , cgwrite , cgwrite1
.Nd read/write cylinder groups of UFS disks
.Sh LIBRARY
.Lb libufs
@@ -26,30 +29,72 @@
.In ufs/ffs/fs.h
.In libufs.h
.Ft int
+.Fn cgget "struct uufsd *disk" "int cg" "struct cg *cgp"
+.Ft int
+.Fn cgput "struct uufsd *disk" "struct cg *cgp"
+.Ft int
.Fn cgread "struct uufsd *disk"
.Ft int
-.Fn cgread1 "struct uufsd *disk" "int c"
+.Fn cgread1 "struct uufsd *disk" "int cg"
+.Ft int
+.Fn cgwrite "struct uufsd *disk"
.Ft int
-.Fn cgwrite1 "struct uufsd *disk" "int c"
+.Fn cgwrite1 "struct uufsd *disk" "int cg"
.Sh DESCRIPTION
The
-.Fn cgread
+.Fn cgget ,
+.Fn cgread ,
and
.Fn cgread1
functions provide cylinder group reads for
.Xr libufs 3
consumers.
The
+.Fn cgput ,
+.Fn cgwrite ,
+and
+.Fn cgwrite1
+functions provide cylinder group writes for
+.Xr libufs 3
+consumers.
+.Pp
+The
+.Fn cgget
+function reads the cylinder group specified by
+.Fa cg
+into the buffer pointed to by
+.Fa cgp
+from the disk referenced by the user-land UFS-disk structure.
+The
+.Fn cgget
+function is the only cylinder group read function that is safe to use
+in threaded applications.
+.Pp
+The
+.Fn cgput
+function writes the cylinder group specified by
+.Va cgp
+to the disk referenced by the user-land UFS-disk structure.
+The
+.Fn cgput
+function is the only cylinder group write function that is safe to use
+in threaded applications.
+Note that the
+.Fn cgput
+function needs to be called only if the cylinder group has been
+modified and the on-disk copy needs to be updated.
+.Pp
+The
.Fn cgread1
-function reads from one cylinder group, specified by
-.Fa c
+function reads from the cylinder group specified by
+.Fa cg
into the
.Va d_cg
-field of a userland UFS disk structure.
+cylinder-group structure in a user-land UFS-disk structure.
It sets the
.Va d_lcg
field to the cylinder group number
-.Fa c .
+.Fa cg .
.Pp
The
.Fn cgread
@@ -65,34 +110,57 @@ field, and then incrementing the
field.
.Pp
The
-.Fn cgwrite1
-function stores cylinder group specified by
-.Fa c
-from
+.Fn cgwrite
+function stores on disk the cylinder group held in the
.Va d_cg
-field of a userland UFS disk structure on disk.
+cylinder-group structure in a user-land UFS-disk structure.
+.Pp
+The
+.Fn cgwrite1
+function provides no additional functionality over the
+.Fn cgwrite
+function as there is only one place that a given cylinder group
+can correctly be written.
+If the caller gets the
+.Fa cg
+parameter wrong, the function fails with the error
+.Er EDOOFUS .
+This function remains only to provide backward compatibility.
.Sh RETURN VALUES
-Both functions return 0 if there are no more cylinder groups to read,
+The
+.Fn cgread
+function returns 0 if there are no more cylinder groups to read,
1 if there are more cylinder groups, and \-1 on error.
+The
+.Fn cgread1
+function returns 1 on success and \-1 on error.
+The other functions return 0 on success and \-1 on error;
.Sh ERRORS
-The function
-.Fn cgread
-may fail and set
+The
+.Fn cgget ,
+.Fn cgread ,
+and
+.Fn cgread1
+functions may fail and set
.Va errno
for any of the errors specified for the library function
.Xr bread 3 .
.Pp
-The function
-.Fn cgread1
-has semantically identical failure conditions to those of
-.Fn cgread .
-.Pp
-The function
+The
+.Fn cgput ,
+.Fn cgwrite ,
+and
.Fn cgwrite1
-may fail and set
+functions may fail and set
.Va errno
for any of the errors specified for the library function
.Xr bwrite 3 .
+Additionally the
+.Fn cgwrite1
+will return the
+.Er EDOOFUS
+error if the cylinder group specified does not match the
+cylinder group that it is requesting to write.
.Sh SEE ALSO
.Xr bread 3 ,
.Xr bwrite 3 ,