From ea1893785c709e15070cd36b800d1bbaa7e46011 Mon Sep 17 00:00:00 2001 From: phk Date: Sun, 7 Mar 2004 16:07:57 +0000 Subject: Add manpages for the gctl API. Submitted by: le Tweaks by: phk --- lib/libgeom/Makefile | 8 +++- lib/libgeom/libgeom.3 | 114 ++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 118 insertions(+), 4 deletions(-) (limited to 'lib/libgeom') diff --git a/lib/libgeom/Makefile b/lib/libgeom/Makefile index 3a4dad5..c64ce50 100644 --- a/lib/libgeom/Makefile +++ b/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 diff --git a/lib/libgeom/libgeom.3 b/lib/libgeom/libgeom.3 index f0e61bb..e141345 100644 --- a/lib/libgeom/libgeom.3 +++ b/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 -- cgit v1.1