Index: share/man/man9/mutex.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/mutex.9,v
retrieving revision 1.33
diff -u -r1.33 mutex.9
--- share/man/man9/mutex.9	21 Oct 2002 12:54:13 -0000	1.33
+++ share/man/man9/mutex.9	18 Feb 2003 22:47:55 -0000
@@ -477,7 +477,66 @@
 .Xr fuword 9 ,
 etc.
 No locks are needed when calling these functions.
+.Ss Giant Lock Manipulation Macros
+The following macros are useful when dealing with the Giant
+lock:
+.Bl -tag -width GIANT_REQUIRED
+.It Dv GIANT_REQUIRED
+Macro used for a routine that wants to assert the Giant lock.
+.It Dv PICKUP_GIANT
+Allows a routine to hold the Giant lock and save it's
+.Xr witness 4
+lock order.
+.It Dv DROP_GIANT
+Allows a routine to drop the Giant lock and restore it's
+.Xr witness 4
+lock order.
+.El
+.Pp
+It should be noted that
+.Dv PICKUP_GIANT
+and
+.Dv DROP_GIANT
+have to be paired together and cannot operate on seperate levels,
+i.e. the following is incorrect and not possible:
+.Bd -literal
+void incorrect(void *dummy)
+{
+	/* initialization ... */
+	
+	DROP_GIANT();
+
+	if (condition) {
+		/* stuff ... */
+
+		PICKUP_GIANT();
+	}
+}
+.Ed
+.Pp
+A correct way of calling
+.Dv PICKUP_GIANT
+and
+.Dv DROP_GIANT :
+.Bd -literal
+void correct(void *dummy)
+{
+	/* initialization ... */
+
+	DROP_GIANT();
+
+	if (condition) {
+		/* stuff ... */
+
+		/* more stuff ... */
+	}
+
+	PICKUP_GIANT();
+}
+.Ed
 .Sh SEE ALSO
+.Xr ddb 4 ,
+.Xr witness 4 ,
 .Xr condvar 9 ,
 .Xr msleep 9 ,
 .Xr mtx_pool 9 ,
@@ -489,3 +548,9 @@
 .Bsx 4.1
 and
 .Fx 5.0 .
+.Sh AUTHORS
+This manual page is partially derived from its
+.Bsx
+counterpart with parts written by Jason Evans and improvements from
+John Baldwin, Chuck Paterson, Doug Rabson, Matthew Dillon, Greg Lehey
+and Jake Burkholder.