Add manpages for the gctl API.

Submitted by:	le
Tweaks by:	phk

lib/libgeom/Makefile

@@ -25,6 +25,12 @@ MLINKS+= \
 	libgeom.3 geom_stats_snapshot_free.3 \
 	libgeom.3 geom_stats_snapshot_timestamp.3 \
 	libgeom.3 geom_stats_snapshot_reset.3 \
-	libgeom.3 geom_stats_snapshot_next.3
+	libgeom.3 geom_stats_snapshot_next.3 \
+	libgeom.3 gctl_get_handle.3 \
+	libgeom.3 gctl_ro_param.3 \
+	libgeom.3 gctl_rw_param.3 \
+	libgeom.3 gctl_issue.3 \
+	libgeom.3 gctl_free.3 \
+	libgeom.3 gctl_dump.3
 
 .include <bsd.lib.mk>

lib/libgeom/libgeom.3

@@ -38,7 +38,13 @@
 .Nm geom_stats_snapshot_free ,
 .Nm geom_stats_snapshot_timestamp ,
 .Nm geom_stats_snapshot_reset ,
-.Nm geom_stats_snapshot_next
+.Nm geom_stats_snapshot_next ,
+.Nm gctl_get_handle ,
+.Nm gctl_ro_param ,
+.Nm gctl_rw_param ,
+.Nm gctl_issue ,
+.Nm gctl_free ,
+.Nm gctl_dump
 .Nd userland API library for kernel GEOM subsystem
 .Sh LIBRARY
 .Lb libgeom
@@ -61,6 +67,19 @@
 .Fn geom_stats_snapshot_reset "void *arg"
 .Ft "struct g_stat *"
 .Fn geom_stats_snapshot_next "void *arg"
+.Ss "Control Functions"
+.Ft "struct gctl_req *"
+.Fn gctl_get_handle "void"
+.Ft void
+.Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value"
+.Ft void
+.Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value"
+.Ft "const char *"
+.Fn gctl_issue "struct gctl_req *req"
+.Ft void
+.Fn gctl_free "struct gctl_req *req"
+.Ft void
+.Fn gctl_dump "struct gctl_req *req" "FILE *f"
 .Sh DESCRIPTION
 The
 .Nm geom
@@ -129,10 +148,99 @@ function
 returns the next item, and
 .Dv NULL
 if there are no more items in the snapshot.
-.Sh AUTHORS
-.An Poul-Henning Kamp Aq phk@FreeBSD.org
+.Ss "Control Functions"
+The
+.Fn gctl_*
+functions are used to send requests to GEOM classes.  In order for a GEOM
+class to actually be able to receive these requests, it must have defined a
+"ctlreq" method.
+.Pp
+A
+.Ar struct gctl_req * ,
+obtained with
+.Fn gctl_get_handle ,
+can hold any number of parameters, which must be added to it with
+.Fn gctl_ro_param
+(for read-only parameters) or
+.Fn gctl_rw_param
+(for read/write parameters).
+.Pp
+Both
+.Fn gctl_ro_param
+and
+.Fn gctl_rw_param
+take a string
+.Ar name ,
+which is used to identify the parameter, and a
+.Ar value ,
+which contains - in the read-only case - the data to be passed to the
+GEOM class, or - in the read/write case - a pointer to preallocated memory
+that the GEOM class should fill with the desired data.  If
+.Ar len
+is negative, it is assumed that
+.Ar value
+is an ASCII string and the actual length is taken from the string length of
+.Ar value ;
+otherwise it must hold the size of
+.Ar value .
+.Pp
+A parameter with a
+.Ar name
+containing the string "class" is mandatory for each request, and the
+corresponding
+.Ar value
+must hold the name of the GEOM class where the request should be sent to.
+.Pp
+Also mandatory for each request is a parameter with a
+.Ar name
+called "verb", and the corresponding
+.Ar value
+needs to hold the command string that the GEOM class should react upon.
+.Pp
+Once all desired parameters are filled in, the request must be sent to
+the GEOM subsystem with
+.Fn gctl_issue ,
+which returns NULL on success, or a string containing the error message
+on failure.
+.Pp
+After the request is finished, the allocated memory should be released with
+.Fn gctl_free .
+.Pp
+.Fn gctl_dump
+can be used to format the contents of
+.Ar req
+to the open file handle pointed to by
+.Ar f 
+for debugging purposes.
+.Pp
+Error handling for the control functions is postponed until the call
+to 
+.Fn gctl_issue
+which returns NULL on success or an error message corresponding to the
+first error which happened.
+.Sh EXAMPLES
+Create a request that is to be sent to the CCD class and tell
+it to destroy a specific geom:
+.Bd -literal -offset indent
+H = gctl_get_handle();
+gctl_ro_param(H, "verb", -1, "destroy geom");
+gctl_ro_param(H, "class", -1, "CCD");
+sprintf(buf, "ccd%d", ccd);
+gctl_ro_param(H, "geom", -1, buf);
+errstr = gctl_issue(H);
+if (errstr != NULL)
+    err(1, "Could not destroy ccd: %s", errstr);
+gctl_free(H);
+.Ed
+.Sh SEE ALSO
+.Rs
+http://ezine.daemonnews.org/200308/blueprints.html
+.Re
 .Sh HISTORY
 The
 .Nm geom
 library appeared in
 .Fx 5.1 .
+.Sh AUTHORS
+.An Poul-Henning Kamp Aq phk@FreeBSD.org
+.An Lukas Ertl Aq le@FreeBSD.org