libhammer - Add missing manual pages
authorAntonio Huete Jimenez <tuxillo@quantumachine.net>
Thu, 19 Feb 2015 13:13:53 +0000 (14:13 +0100)
committerAntonio Huete Jimenez <tuxillo@quantumachine.net>
Thu, 19 Feb 2015 14:31:05 +0000 (15:31 +0100)
- Adapt the info one for the recent changes.
- Remove old manpages via upgrade.

Makefile_upgrade.inc
lib/libhammer/Makefile
lib/libhammer/libhammer.3 [new file with mode: 0644]
lib/libhammer/libhammer_fsinfo.3 [copied from lib/libhammer/libhammer_get_volinfo.3 with 82% similarity]
lib/libhammer/libhammer_snapshot.3 [moved from lib/libhammer/libhammer_get_volinfo.3 with 56% similarity]
lib/libhammer/libhammer_stats.3

index d6eea2f..0d41f87 100644 (file)
@@ -2820,6 +2820,10 @@ TO_REMOVE+=/usr/share/man/man1/gcc44.1.gz
 TO_REMOVE+=/usr/share/man/man1/gcov44.1.gz
 TO_REMOVE+=/usr/share/mk/bsd.cpu.gcc44.mk
 TO_REMOVE+=/usr/libdata/gcc50/stddef.h
+TO_REMOVE+=/usr/share/man/man3/libhammer_get_volinfo.3.gz
+TO_REMOVE+=/usr/share/man/cat3/libhammer_get_volinfo.3.gz
+TO_REMOVE+=/usr/share/man/man3/libhammer_free_volinfo.3.gz
+TO_REMOVE+=/usr/share/man/cat3/libhammer_free_volinfo.3.gz
 
 .if ${MACHINE_ARCH} == "x86_64"
 TO_REMOVE+=/usr/sbin/stlstats
index 5dd36e6..af22d53 100644 (file)
@@ -7,14 +7,24 @@ INCS= libhammer.h
 
 SRCS+= crc32.c
 
-MAN+=   libhammer_get_volinfo.3
+MAN+=   libhammer.3
+MAN+=   libhammer_fsinfo.3
+MAN+=   libhammer_snapshot.3
 MAN+=   libhammer_stats.3
 
-MLINKS+= libhammer_get_volinfo.3 libhammer_get_next_pfs.3
-MLINKS+= libhammer_get_volinfo.3 libhammer_get_prev_pfs.3
-MLINKS+= libhammer_get_volinfo.3 libhammer_get_first_pfs.3
-MLINKS+= libhammer_get_volinfo.3 libhammer_get_last_pfs.3
-MLINKS+= libhammer_get_volinfo.3 libhammer_free_volinfo.3
+MLINKS+= libhammer_fsinfo.3 libhammer_get_fsinfo.3
+MLINKS+= libhammer_fsinfo.3 libhammer_get_next_pfs.3
+MLINKS+= libhammer_fsinfo.3 libhammer_get_prev_pfs.3
+MLINKS+= libhammer_fsinfo.3 libhammer_get_first_pfs.3
+MLINKS+= libhammer_fsinfo.3 libhammer_get_last_pfs.3
+MLINKS+= libhammer_fsinfo.3 libhammer_free_fsinfo.3
+
+MLINKS+= libhammer_snapshot.3 libhammer_pfs_get_snapshots.3
+MLINKS+= libhammer_snapshot.3 libhammer_get_next_snap.3
+MLINKS+= libhammer_snapshot.3 libhammer_get_prev_snap.3
+MLINKS+= libhammer_snapshot.3 libhammer_get_first_snap.3
+MLINKS+= libhammer_snapshot.3 libhammer_get_last_snap.3
+MLINKS+= libhammer_snapshot.3 libhammer_pfs_free_snapshots.3
 
 MLINKS+= libhammer_stats.3 libhammer_stats_redo.3
 MLINKS+= libhammer_stats.3 libhammer_stats_undo.3
diff --git a/lib/libhammer/libhammer.3 b/lib/libhammer/libhammer.3
new file mode 100644 (file)
index 0000000..01ac987
--- /dev/null
@@ -0,0 +1,116 @@
+.\"
+.\" Copyright (c) 2015 The DragonFly Project.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to The DragonFly Project
+.\" by Antonio Huete Jimenez <tuxillo@quantumachine.net>
+.\"
+.\" 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. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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
+.\" COPYRIGHT HOLDERS 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.
+.\"
+.Dd February 19, 2015
+.Dt LIBHAMMER 3
+.Os
+.Sh NAME
+.Nm hammer
+.Nd HAMMER filesystem interface
+.Sh LIBRARY
+.Lb libhammer
+.Sh SYNOPSIS
+.In libhammer.h
+.Sh DESCRIPTION
+The
+.Xr hammer 3
+library provides a set of functions which serve as an interface to applications
+that need to obtain information or perform maintenance operations in
+.Xr HAMMER 5
+file systems.
+.Sh INTRODUCTION
+This library is an attempt to factor out most of the code in the initial
+.Xr hammer 8
+program greatly reducing its complexity and taking advantage of all the
+functionality it contained helping other programs to reuse it.
+.Pp
+There are several parts of the
+.Xr HAMMER 5
+file system for which this library provides an API:
+.Bl -bullet
+.It
+.Em Information facilities:
+The following information is gathered and exposed by this library:
+.Bl -dash -offset indent
+.It
+File system specific information such as size, bigblock details, version,
+PFSes, snapshots, mount points.
+.It
+Statistical data like number of B-Tree operations, number of device operations,
+number of undo operations.
+.El
+.It
+.Em Pseudo-filesystems:
+These are independent sub file systems within a HAMMER filesystem.
+After
+.Nm
+library initialisation the list of pseudo-file systems will be available in the
+.Vt libhammer_fsinfo
+structure within a
+.Dv TAILQ .
+.Pp
+Creating and deleting pseudo-filesystems is not yet supported by this library.
+.It
+.Em Snapshots:
+Per PFS point in time snapshots are kept in the filesystem metadata since
+HAMMER version 3.
+A list of snaptshots is collected and placed within a
+.Dv TAILQ
+for each PFS.
+.Pp
+Creating and deleting snapshots is not yet supported by this library.
+.El
+.Sh INITIALISATION
+Before any API call the library must be initalised with the
+.Fn libhammer_get_fsinfo
+function.
+This will perform all the operations needed to initialise the data strutures in
+which the API function rely for the specified HAMMER file system.
+.Pp
+Once you are done, the special function
+.Fn libhammer_free_fsinfo
+will release all the resources used by the library during its initialisation and
+usage.
+.Sh SEE ALSO
+.Xr HAMMER 5 ,
+.Xr hammer 8 ,
+.Xr libhammer_fsinfo 3 ,
+.Xr libhammer_snapshot 3 ,
+.Xr libhammer_stats 3
+.Sh AUTHORS
+This manpage was written by
+.An Antonio Huete Jimenez Aq Mt tuxillo@quantumachine.net .
+.Sh BUGS
+Please note that, at the moment of writing this man page, the
+.Nm
+library is incomplete.
similarity index 82%
copy from lib/libhammer/libhammer_get_volinfo.3
copy to lib/libhammer/libhammer_fsinfo.3
index a122eb0..785c16d 100644 (file)
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 9, 2013
+.Dd February 19, 2015
 .Dt LIBHAMMER 3
 .Os
 .Sh NAME
-.Nm libhammer_get_volinfo ,
+.Nm libhammer_get_fsinfo ,
 .Nm libhammer_get_next_pfs ,
 .Nm libhammer_get_prev_pfs ,
 .Nm libhammer_get_first_pfs ,
 .Nm libhammer_get_last_pfs ,
-.Nm libhammer_free_volinfo
+.Nm libhammer_free_fsinfo
 .Nd libhammer information functions
 .Sh LIBRARY
 .Lb libhammer
 .Sh SYNOPSIS
 .In libhammer.h
-.Ft libhammer_volinfo_t
-.Fn libhammer_get_volinfo "const char *path"
+.Ft libhammer_fsinfo_t
+.Fn libhammer_get_fsinfo "const char *path"
 .Ft libhammer_pfsinfo_t
-.Fn libhammer_get_first_pfs "libhammer_volinfo_t volinfo"
+.Fn libhammer_get_first_pfs "libhammer_fsinfo_t fsinfo"
 .Ft libhammer_pfsinfo_t
-.Fn libhammer_get_last_pfs "libhammer_volinfo_t volinfo"
+.Fn libhammer_get_last_pfs "libhammer_fsinfo_t fsinfo"
 .Ft libhammer_pfsinfo_t
 .Fn libhammer_get_next_pfs "libhammer_pfsinfo_t pfsinfo"
 .Ft libhammer_pfsinfo_t
 .Fn libhammer_get_prev_pfs "libhammer_pfsinfo_t pfsinfo"
 .Ft void
-.Fn libhammer_free_volinfo "libhammer_volinfo_t volinfo"
+.Fn libhammer_free_fsinfo "libhammer_fsinfo_t fsinfo"
 .Sh DESCRIPTION
 The
-.Fn libhammer_get_volinfo
+.Fn libhammer_get_fsinfo
 iterates all the PFSs from a given path belonging to a
 .Nm HAMMER
 filesystem and returns
-.Vt libhammer_volinfo_t
-.Fa volinfo
+.Vt libhammer_fsinfo_t
+.Fa fsinfo
 which holds a
 .Nm TAILQ
 of
@@ -84,16 +84,16 @@ to store the returning
 .Vt libhammer_pfsinfo_t
 value from the first and last functions.
 .Pp
-.Fn libhammer_free_volinfo
-frees up all the memory allocated previously by
-.Fn libhammer_get_volinfo .
+.Fn libhammer_free_fsinfo
+frees up all the resources allocated previously by
+.Fn libhammer_get_fsinfo .
 .Sh RETURN VALUES
-.Fn libhammer_get_volinfo
+.Fn libhammer_get_fsinfo
 returns a
-.Vt libhammer_volinfo_t
+.Vt libhammer_fsinfo_t
 in any case where path is in a
 .Nm HAMMER
-filesystem scope or
+filesystem or
 .Dv NULL
 if there was any other problem.
 You can check
@@ -106,7 +106,7 @@ and
 must return a
 .Vt libhammer_pfs_t
 if the
-.Fa volinfo
+.Fa fsinfo
 passed in is valid.
 .Fn libhammer_get_next_pfs
 and
@@ -119,6 +119,9 @@ in case there are no more elements.
 .Sh SEE ALSO
 .Xr HAMMER 5 ,
 .Xr hammer 8 ,
+.Xr libhammer 3 ,
+.Xr libhammer_snapshot 3 ,
+.Xr libhammer_stats 3
 .Sh AUTHORS
 This manpage was written by
-.An Antonio Huete Jimenez.
+.An Antonio Huete Jimenez Aq Mt tuxillo@quantumachine.net .
similarity index 56%
rename from lib/libhammer/libhammer_get_volinfo.3
rename to lib/libhammer/libhammer_snapshot.3
index a122eb0..4060eb9 100644 (file)
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2011 The DragonFly Project.  All rights reserved.
+.\" Copyright (c) 2015 The DragonFly Project.  All rights reserved.
 .\"
 .\" This code is derived from software contributed to The DragonFly Project
 .\" by Antonio Huete Jimenez <tuxillo@quantumachine.net>
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 9, 2013
+.Dd February 19, 2015
 .Dt LIBHAMMER 3
 .Os
 .Sh NAME
-.Nm libhammer_get_volinfo ,
-.Nm libhammer_get_next_pfs ,
-.Nm libhammer_get_prev_pfs ,
-.Nm libhammer_get_first_pfs ,
-.Nm libhammer_get_last_pfs ,
-.Nm libhammer_free_volinfo
-.Nd libhammer information functions
+.Nm libhammer_pfs_get_snapshots ,
+.Nm libhammer_get_next_snap ,
+.Nm libhammer_get_prev_snap ,
+.Nm libhammer_get_first_snap ,
+.Nm libhammer_get_last_snap ,
+.Nm libhammer_pfs_free_snapshots
+.Nd libhammer snapshot functions
 .Sh LIBRARY
 .Lb libhammer
 .Sh SYNOPSIS
 .In libhammer.h
-.Ft libhammer_volinfo_t
-.Fn libhammer_get_volinfo "const char *path"
-.Ft libhammer_pfsinfo_t
-.Fn libhammer_get_first_pfs "libhammer_volinfo_t volinfo"
-.Ft libhammer_pfsinfo_t
-.Fn libhammer_get_last_pfs "libhammer_volinfo_t volinfo"
-.Ft libhammer_pfsinfo_t
-.Fn libhammer_get_next_pfs "libhammer_pfsinfo_t pfsinfo"
-.Ft libhammer_pfsinfo_t
-.Fn libhammer_get_prev_pfs "libhammer_pfsinfo_t pfsinfo"
+.Ft int
+.Fn libhammer_pfs_get_snapshots "libhammer_fsinfo_t fsinfo" "libhammer_pfsinfo_t pip"
+.Ft libhammer_snapinfo_t
+.Fn libhammer_get_first_snap "libhammer_pfsinfo_t pip"
+.Ft libhammer_snapinfo_t
+.Fn libhammer_get_last_snap "libhammer_pfsinfo_t pip"
+.Ft libhammer_snapinfo_t
+.Fn libhammer_get_next_snap "libhammer_snapinfo_t sip"
+.Ft libhammer_snapinfo_t
+.Fn libhammer_get_prev_snap "libhammer_snapinfo_t sip"
 .Ft void
-.Fn libhammer_free_volinfo "libhammer_volinfo_t volinfo"
+.Fn libhammer_pfs_free_snapshots "libhammer_pfsinfo_t pip"
 .Sh DESCRIPTION
 The
-.Fn libhammer_get_volinfo
-iterates all the PFSs from a given path belonging to a
-.Nm HAMMER
-filesystem and returns
-.Vt libhammer_volinfo_t
-.Fa volinfo
-which holds a
-.Nm TAILQ
-of
-.Vt libhammer_pfsinfo
-structs, one per PFS found.
+.Fn libhammer_pfs_get_snapshots
+gathers all the snapshot information for the PFS specified in
+.Fa pip .
 .Pp
-The list of found PFSs can be iterated with
-.Fn libhammer_get_first_pfs ,
-.Fn libhammer_get_last_pfs ,
-.Fn libhammer_get_next_pfs
+The list of snapshots can be iterated with
+.Fn libhammer_get_first_snap ,
+.Fn libhammer_get_last_snap ,
+.Fn libhammer_get_next_snap
 and
-.Fn libhammer_get_prev_pfs .
+.Fn libhammer_get_prev_snap .
 .Pp
 Note that to use the next and previous functions described above you need
 to store the returning
-.Vt libhammer_pfsinfo_t
+.Vt libhammer_snapinfo_t
 value from the first and last functions.
 .Pp
-.Fn libhammer_free_volinfo
-frees up all the memory allocated previously by
-.Fn libhammer_get_volinfo .
+The
+.Fn libhammer_pfs_free_snapshots
+function releases all the resources used to hold the information of the
+snapshots for a particular PFS.
 .Sh RETURN VALUES
-.Fn libhammer_get_volinfo
-returns a
-.Vt libhammer_volinfo_t
-in any case where path is in a
-.Nm HAMMER
-filesystem scope or
-.Dv NULL
-if there was any other problem.
-You can check
-.Nm errno
-in the error cases.
+.Fn libhammer_pfs_get_snapshots
+returns 0 when successful and -1 in the case of failure.
+The
+.Vt errno
+value indicating the error is stored within the passed
+.Vt libhammer_pfsinfo_t
+in the
+.Vt libhammer_head
+struct.
 .Pp
-.Fn libhammer_get_first_pfs
+.Fn libhammer_get_first_snap
 and
-.Fn libhammer_get_last_pfs
+.Fn libhammer_get_last_snap
 must return a
-.Vt libhammer_pfs_t
+.Vt libhammer_snapinfo_t
 if the
-.Fa volinfo
+.Fa pip
 passed in is valid.
-.Fn libhammer_get_next_pfs
+.Fn libhammer_get_next_snap
 and
-.Fn libhammer_get_prev_pfs
+.Fn libhammer_get_prev_snap
 return a
-.Vt libhammer_pfsinfo_t
+.Vt libhammer_snapinfo_t
 or
 .Dv NULL
 in case there are no more elements.
 .Sh SEE ALSO
 .Xr HAMMER 5 ,
 .Xr hammer 8 ,
+.Xr libhammer 3 ,
+.Xr libhammer_fsinfo 3 ,
+.Xr libhammer_stats 3
 .Sh AUTHORS
 This manpage was written by
-.An Antonio Huete Jimenez.
+.An Antonio Huete Jimenez Aq Mt tuxillo@quantumachine.net .
index e959133..2857593 100644 (file)
@@ -31,7 +31,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 9, 2013
+.Dd February 19, 2015
 .Dt LIBHAMMER 3
 .Os
 .Sh NAME
@@ -121,6 +121,9 @@ which will take structures to store groups of values.
 .Sh SEE ALSO
 .Xr HAMMER 5 ,
 .Xr hammer 8 ,
+.Xr libhammer 3 ,
+.Xr libhammer_fsinfo 3 ,
+.Xr libhammer_snapshot 3
 .Sh AUTHORS
 This manpage was written by
-.An Antonio Huete Jimenez.
+.An Antonio Huete Jimenez Aq Mt tuxillo@quantumachine.net .