Date: Sun, 7 Mar 2004 16:43:50 +0100 (CET) From: Lukas Ertl <le@FreeBSD.org> To: geom@FreeBSD.org Subject: gctl_* API (libgeom) Message-ID: <20040307164215.H624@korben.in.tern>
next in thread | raw e-mail | index | archive | help
Hi, I've put together some docs for the gctl_* API in libgeom that I'd like to commit anytime soon. Please review it. ---8<--- Index: lib/libgeom/Makefile =================================================================== RCS file: /home/ncvs/src/lib/libgeom/Makefile,v retrieving revision 1.9 diff -u -r1.9 Makefile --- lib/libgeom/Makefile 18 Aug 2003 15:25:38 -0000 1.9 +++ lib/libgeom/Makefile 7 Mar 2004 15:41:18 -0000 @@ -25,6 +25,12 @@ 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> Index: lib/libgeom/libgeom.3 =================================================================== RCS file: /home/ncvs/src/lib/libgeom/libgeom.3,v retrieving revision 1.4 diff -u -r1.4 libgeom.3 --- lib/libgeom/libgeom.3 18 Jun 2003 19:43:17 -0000 1.4 +++ lib/libgeom/libgeom.3 7 Mar 2004 15:41:18 -0000 @@ -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,8 +148,86 @@ returns the next item, and .Dv NULL if there are no more items in the snapshot. +.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" function. +.Pp +A +.Ar struct gctl_req * , +obtained with +.Fn gctl_get_handle , +can hold any number of parameters, which must be set 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 write the contents of +.Ar req +to the open file handle pointed to by +.Ar f . +.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 AUTHORS .An Poul-Henning Kamp Aq phk@FreeBSD.org +.An Lukas Ertl Aq le@FreeBSD.org .Sh HISTORY The .Nm geom ---8<--- regards, le -- Lukas Ertl http://mailbox.univie.ac.at/~le/ le@FreeBSD.org http://people.freebsd.org/~le/
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040307164215.H624>