lib/libhammer/libhammer_get_volinfo.3

   1 .\"
   2 .\" Copyright (c) 2011 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The DragonFly Project
   5 .\" by Antonio Huete Jimenez <tuxillo@quantumachine.net>
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in
  15 .\"    the documentation and/or other materials provided with the
  16 .\"    distribution.
  17 .\" 3. Neither the name of The DragonFly Project nor the names of its
  18 .\"    contributors may be used to endorse or promote products derived
  19 .\"    from this software without specific, prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd September 9, 2013
  35 .Dt LIBHAMMER 3
  36 .Os
  37 .Sh NAME
  38 .Nm libhammer_get_volinfo ,
  39 .Nm libhammer_get_next_pfs ,
  40 .Nm libhammer_get_prev_pfs ,
  41 .Nm libhammer_get_first_pfs ,
  42 .Nm libhammer_get_last_pfs ,
  43 .Nm libhammer_free_volinfo
  44 .Nd libhammer information functions
  45 .Sh LIBRARY
  46 .Lb libhammer
  47 .Sh SYNOPSIS
  48 .In libhammer.h
  49 .Ft libhammer_volinfo_t
  50 .Fn libhammer_get_volinfo "const char *path"
  51 .Ft libhammer_pfsinfo_t
  52 .Fn libhammer_get_first_pfs "libhammer_volinfo_t volinfo"
  53 .Ft libhammer_pfsinfo_t
  54 .Fn libhammer_get_last_pfs "libhammer_volinfo_t volinfo"
  55 .Ft libhammer_pfsinfo_t
  56 .Fn libhammer_get_next_pfs "libhammer_pfsinfo_t pfsinfo"
  57 .Ft libhammer_pfsinfo_t
  58 .Fn libhammer_get_prev_pfs "libhammer_pfsinfo_t pfsinfo"
  59 .Ft void
  60 .Fn libhammer_free_volinfo "libhammer_volinfo_t volinfo"
  61 .Sh DESCRIPTION
  62 The
  63 .Fn libhammer_get_volinfo
  64 iterates all the PFSs from a given path belonging to a
  65 .Nm HAMMER
  66 filesystem and returns
  67 .Vt libhammer_volinfo_t
  68 .Fa volinfo
  69 which holds a
  70 .Nm TAILQ
  71 of
  72 .Vt libhammer_pfsinfo
  73 structs, one per PFS found.
  74 .Pp
  75 The list of found PFSs can be iterated with
  76 .Fn libhammer_get_first_pfs ,
  77 .Fn libhammer_get_last_pfs ,
  78 .Fn libhammer_get_next_pfs
  79 and
  80 .Fn libhammer_get_prev_pfs .
  81 .Pp
  82 Note that to use the next and previous functions described above you need
  83 to store the returning
  84 .Vt libhammer_pfsinfo_t
  85 value from the first and last functions.
  86 .Pp
  87 .Fn libhammer_free_volinfo
  88 frees up all the memory allocated previously by
  89 .Fn libhammer_get_volinfo .
  90 .Sh RETURN VALUES
  91 .Fn libhammer_get_volinfo
  92 returns a
  93 .Vt libhammer_volinfo_t
  94 in any case where path is in a
  95 .Nm HAMMER
  96 filesystem scope or
  97 .Dv NULL
  98 if there was any other problem.
  99 You can check
 100 .Nm errno
 101 in the error cases.
 102 .Pp
 103 .Fn libhammer_get_first_pfs
 104 and
 105 .Fn libhammer_get_last_pfs
 106 must return a
 107 .Vt libhammer_pfs_t
 108 if the
 109 .Fa volinfo
 110 passed in is valid.
 111 .Fn libhammer_get_next_pfs
 112 and
 113 .Fn libhammer_get_prev_pfs
 114 return a
 115 .Vt libhammer_pfsinfo_t
 116 or
 117 .Dv NULL
 118 in case there are no more elements.
 119 .Sh SEE ALSO
 120 .Xr HAMMER 5 ,
 121 .Xr hammer 8 ,
 122 .Sh AUTHORS
 123 This manpage was written by
 124 .An Antonio Huete Jimenez.