1 files changed, 136 insertions, 0 deletions
diff --git a/lib/libgeom/libgeom.3 b/lib/libgeom/libgeom.3
new file mode 100644
index 0000000..ff8b5fd
--- /dev/null
+++ b/lib/libgeom/libgeom.3
@@ -0,0 +1,136 @@
+.\" Copyright (c) 2003 Poul-Henning Kamp
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The names of the authors may not be used to endorse or promote
+.\"    products derived from this software without specific prior written
+.\"    permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 8, 2003
+.Dt LIBGEOM 3
+.Os
+.Sh NAME
+.Nm geom_stats_open ,
+.Nm geom_stats_close ,
+.Nm geom_stats_resync ,
+.Nm geom_stats_snapshot_get ,
+.Nm geom_stats_snapshot_free ,
+.Nm geom_stats_snapshot_timestamp ,
+.Nm geom_stats_snapshot_reset ,
+.Nm geom_stats_snapshot_next
+.Nd userland API library for kernel GEOM subsystem
+.Sh LIBRARY
+.Lb libgeom
+.Sh SYNOPSIS
+.In libgeom.h
+.Ss "Statistics Functions"
+.Ft void
+.Fn geom_stats_close void
+.Ft int
+.Fn geom_stats_open void
+.Ft void
+.Fn geom_stats_resync void
+.Ft "void *"
+.Fn geom_stats_snapshot_get void
+.Ft void
+.Fn geom_stats_snapshot_free "void *arg"
+.Ft void
+.Fn geom_stats_snapshot_timestamp "void *arg" "struct timespec *tp"
+.Ft void
+.Fn geom_stats_snapshot_reset "void *arg"
+.Ft "struct g_stat *"
+.Fn geom_stats_snapshot_next "void *arg"
+.Sh DESCRIPTION
+The
+.Nm geom
+library contains the official and publicized API for
+interacting with the GEOM subsystem in the kernel.
+.Ss "Statistics Functions"
+GEOM collects statistics data for all consumers and providers, but does
+not perform any normalization or presentation on the raw data, this is
+left as an excercize for user-land presentation utilities.
+.Pp
+The
+.Fn geom_stats_open
+and
+.Fn geom_stats_close
+functions open and close the necessary pathways to access the raw
+statistics information in the kernel.
+These functions are likely to
+open one or more files and cache the file descriptors locally.
+.Fn geom_stats_open
+returns zero on success, and sets
+.Va errno
+if not.
+.Pp
+The
+.Fn geom_stats_resync
+function will check if more statistics collection points have been
+added in the kernel since
+.Fn geom_stats_open
+or the previous call to
+.Fn geom_stats_resync .
+.Pp
+The
+.Fn geom_stats_snapshot_get
+function
+will acquire a snapshot of the raw data from the kernel, and while a
+reasonable effort is made to make this snapshot as atomic and consistent
+as possible, no guarantee is given that it will actually be so.
+The snapshot must be freed again using the
+.Fn geom_stats_snapshot_free
+function.
+.Fn geom_stats_snapshot_get
+returns
+.Dv NULL
+on failure.
+.Pp
+The
+.Fn geom_stats_snapshot_timestamp
+function
+provides access to the timestamp acquired in the snapshot.
+.Pp
+The
+.Fn geom_stats_snapshot_reset
+and
+.Fn geom_stats_snapshot_next
+functions
+provide an iterator over the statistics slots in the snapshot.
+The
+.Fn geom_stats_snapshot_reset
+function
+forces the internal pointer in the snapshot back to before the first item.
+The
+.Fn geom_stats_snapshot_next
+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
+.Sh HISTORY
+The
+.Nm geom
+library appeared in
+.Fx 5.1 .