From 44935d4cc49d3b6612481fb9f871ed9ac3fcb12d Mon Sep 17 00:00:00 2001 From: Antonio Huete Jimenez Date: Thu, 19 Feb 2015 14:13:53 +0100 Subject: [PATCH] libhammer - Add missing manual pages - Adapt the info one for the recent changes. - Remove old manpages via upgrade. --- Makefile_upgrade.inc | 4 + lib/libhammer/Makefile | 22 +++- lib/libhammer/libhammer.3 | 116 ++++++++++++++++++ ...ammer_get_volinfo.3 => libhammer_fsinfo.3} | 41 ++++--- ...mer_get_volinfo.3 => libhammer_snapshot.3} | 112 ++++++++--------- lib/libhammer/libhammer_stats.3 | 7 +- 6 files changed, 216 insertions(+), 86 deletions(-) create mode 100644 lib/libhammer/libhammer.3 copy lib/libhammer/{libhammer_get_volinfo.3 => libhammer_fsinfo.3} (82%) rename lib/libhammer/{libhammer_get_volinfo.3 => libhammer_snapshot.3} (56%) diff --git a/Makefile_upgrade.inc b/Makefile_upgrade.inc index d6eea2f3d1..0d41f8790e 100644 --- a/Makefile_upgrade.inc +++ b/Makefile_upgrade.inc @@ -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 diff --git a/lib/libhammer/Makefile b/lib/libhammer/Makefile index 5dd36e6e43..af22d532a1 100644 --- a/lib/libhammer/Makefile +++ b/lib/libhammer/Makefile @@ -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 index 0000000000..01ac987ad4 --- /dev/null +++ b/lib/libhammer/libhammer.3 @@ -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 +.\" +.\" 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. diff --git a/lib/libhammer/libhammer_get_volinfo.3 b/lib/libhammer/libhammer_fsinfo.3 similarity index 82% copy from lib/libhammer/libhammer_get_volinfo.3 copy to lib/libhammer/libhammer_fsinfo.3 index a122eb0e81..785c16d1f8 100644 --- a/lib/libhammer/libhammer_get_volinfo.3 +++ b/lib/libhammer/libhammer_fsinfo.3 @@ -31,41 +31,41 @@ .\" 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 . diff --git a/lib/libhammer/libhammer_get_volinfo.3 b/lib/libhammer/libhammer_snapshot.3 similarity index 56% rename from lib/libhammer/libhammer_get_volinfo.3 rename to lib/libhammer/libhammer_snapshot.3 index a122eb0e81..4060eb9dc9 100644 --- a/lib/libhammer/libhammer_get_volinfo.3 +++ b/lib/libhammer/libhammer_snapshot.3 @@ -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 @@ -31,94 +31,88 @@ .\" 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 . diff --git a/lib/libhammer/libhammer_stats.3 b/lib/libhammer/libhammer_stats.3 index e959133c96..2857593798 100644 --- a/lib/libhammer/libhammer_stats.3 +++ b/lib/libhammer/libhammer_stats.3 @@ -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 . -- 2.41.0