svn commit: r324667 - head/lib/libgeom

[Romain Tartière]

Author: romain (ports committer)
Date: Mon Oct 16 17:21:52 2017
New Revision: 324667
URL: https://svnweb.freebsd.org/changeset/base/324667

Log:
  Add a quick description of the geom_getxml(3), geom_xml2tree(3),
  geom_gettree(3) and geom_deletetree(3) functions provided by libgeom and are
  not documented in libgeom(3).
  
  Reviewed by:	mav, bjk, allanjude
  Approved by:	allanjude
  Differential Revision:	https://reviews.freebsd.org/D12679

Modified:
  head/lib/libgeom/Makefile
  head/lib/libgeom/libgeom.3

Modified: head/lib/libgeom/Makefile
==============================================================================
--- head/lib/libgeom/Makefile	Mon Oct 16 16:14:50 2017	(r324666)
+++ head/lib/libgeom/Makefile	Mon Oct 16 17:21:52 2017	(r324667)
@@ -33,6 +33,10 @@ MLINKS+= \
 	libgeom.3 gctl_issue.3 \
 	libgeom.3 gctl_free.3 \
 	libgeom.3 gctl_dump.3 \
+	libgeom.3 geom_getxml.3 \
+	libgeom.3 geom_xml2tree.3 \
+	libgeom.3 geom_gettree.3 \
+	libgeom.3 geom_deletetree.3 \
 	libgeom.3 g_close.3 \
 	libgeom.3 g_delete.3 \
 	libgeom.3 g_device_path.3 \

Modified: head/lib/libgeom/libgeom.3
==============================================================================
--- head/lib/libgeom/libgeom.3	Mon Oct 16 16:14:50 2017	(r324666)
+++ head/lib/libgeom/libgeom.3	Mon Oct 16 17:21:52 2017	(r324667)
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 22, 2017
+.Dd October 16, 2017
 .Dt LIBGEOM 3
 .Os
 .Sh NAME
@@ -46,6 +46,10 @@
 .Nm gctl_issue ,
 .Nm gctl_free ,
 .Nm gctl_dump ,
+.Nm geom_getxml ,
+.Nm geom_xml2tree ,
+.Nm geom_gettree ,
+.Nm geom_deletetree ,
 .Nm g_open ,
 .Nm g_close ,
 .Nm g_mediasize ,
@@ -99,7 +103,15 @@
 .Ft void
 .Fn gctl_dump "struct gctl_req *req" "FILE *f"
 .Ss "Utility Functions"
+.Ft "char *"
+.Fn geom_getxml void
 .Ft int
+.Fn geom_xml2tree "struct gmesh *gmp" "char *p"
+.Ft int
+.Fn geom_gettree "struct gmesh *gmp"
+.Ft void
+.Fn geom_deletetree "struct gmesh *gmp"
+.Ft int
 .Fn g_open "const char *name" "int dowrite"
 .Ft int
 .Fn g_close "int fd"
@@ -278,6 +290,46 @@ which returns
 on success, or an error message corresponding to the
 first error which happened.
 .Ss "Utility Functions"
+The
+.Fn geom_getxml
+function is a wrapper around
+.Xr sysctl 3
+that fetches the
+.Ar kern.geom.confxml
+OID, and returns it's value.
+The allocated memory should be released with
+.Xr free 2
+after use.
+.Pp
+The
+.Fn geom_xml2tree
+function parses the XML representation of a GEOM topology passed as
+.Ar p ,
+allocates the needed data structures to access this information and fills in
+the passed
+.Ar gmp
+data structure.
+Memory allocated during this transformation should be released
+using
+.Fn geom_deletetree
+after use.
+.Pp
+The
+.Fn geom_gettree
+function is a wrapper around the
+.Fn geom_getxml
+and
+.Fn geom_xml2tree
+functions.
+Memory allocated during this operation should be released using
+.Fn geom_deletetree
+after use.
+.Pp
+The
+.Fn geom_deletetree
+function releases memory allocated for storing the data-structures referenced by
+.Ar gmp .
+.Pp
 The
 .Fn g_*
 functions are used to communicate with GEOM providers.