From 4fddfecb7bc49b05c3fca5b7fc9d2c55755e43d0 Mon Sep 17 00:00:00 2001
From: romain <romain@FreeBSD.org>
Date: Mon, 16 Oct 2017 17:21:52 +0000
Subject: [PATCH] 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
---
 lib/libgeom/Makefile  |  4 ++++
 lib/libgeom/libgeom.3 | 54 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/lib/libgeom/Makefile b/lib/libgeom/Makefile
index ea1f6c83a961..b7877cc56ece 100644
--- a/lib/libgeom/Makefile
+++ b/lib/libgeom/Makefile
@@ -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 \
diff --git a/lib/libgeom/libgeom.3 b/lib/libgeom/libgeom.3
index dbe21c84d38e..e1a3a35b7062 100644
--- a/lib/libgeom/libgeom.3
+++ b/lib/libgeom/libgeom.3
@@ -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,6 +103,14 @@
 .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
@@ -279,6 +291,46 @@ 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.
 .Pp