Add manpages for the gctl API.
Submitted by: le Tweaks by: phk
This commit is contained in:
Poul-Henning Kamp
parent
2cd7fe4dc1
commit
5e5bfe7757
@ -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>
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user