man/zip_stat.mdoc

   1 .\" zip_stat.mdoc -- get information about file
   2 .\" Copyright (C) 2003-2011 Dieter Baron and Thomas Klausner
   3 .\"
   4 .\" This file is part of libzip, a library to manipulate ZIP archives.
   5 .\" The authors can be contacted at <libzip@nih.at>
   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 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. The names of the authors may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior
  18 .\"    written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
  21 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
  24 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  26 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  28 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  30 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd February 14, 2011
  33 .Dt ZIP_STAT 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_stat ,
  37 .Nm zip_stat_index
  38 .Nd get information about file
  39 .Sh LIBRARY
  40 libzip (-lzip)
  41 .Sh SYNOPSIS
  42 .In zip.h
  43 .Ft int
  44 .Fn zip_stat "struct zip *archive" "const char *fname" "int flags" "struct zip_stat *sb"
  45 .Ft int
  46 .Fn zip_stat_index "struct zip *archive" "int index" "int flags" "struct zip_stat *sb"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn zip_stat
  50 function obtains information about the file named
  51 .Ar fname
  52 in
  53 .Ar archive .
  54 The
  55 .Ar flags
  56 argument specifies how the name lookup should be done.
  57 Its values are described in
  58 .Xr zip_name_locate 3 .
  59 Also,
  60 .Dv ZIP_FL_UNCHANGED
  61 may be
  62 .Em or Ns No 'ed
  63 to it to request information about the original file in the archive,
  64 ignoring any changes made.
  65 .Pp
  66 The
  67 .Fn zip_stat_index
  68 function obtains information about the file at position
  69 .Ar index .
  70 .Pp
  71 The
  72 .Ar sb
  73 argument is a pointer to a
  74 .Ft struct zip_stat
  75 (shown below), into which information about the file is placed.
  76 .Bd -literal
  77 struct zip_stat {
  78     zip_uint64_t valid;                 /* which fields have valid values */
  79     const char *name;                   /* name of the file */
  80     zip_uint64_t index;                 /* index within archive */
  81     zip_uint64_t size;                  /* size of file (uncompressed) */
  82     zip_uint64_t comp_size;             /* size of file (compressed) */
  83     time_t mtime;                       /* modification time */
  84     zip_uint32_t crc;                   /* crc of file data */
  85     zip_uint16_t comp_method;           /* compression method used */
  86     zip_uint16_t encryption_method;     /* encryption method used */
  87     zip_uint32_t flags;                 /* reserved for future use */
  88 };
  89 .Ed
  90 The structure pointed to by
  91 .Ar sb
  92 must be allocated before calling
  93 .Fn zip_stat
  94 or
  95 .Fn zip_stat_index .
  96 .Pp
  97 The
  98 .Ar valid
  99 field of the structure specifies which other fields are valid.
 100 Check if the flag defined by the following defines are in
 101 .Ar valid
 102 before accessing the fields:
 103 .Bl -tag -width ZIP_STAT_ENCRYPTION_METHODXX -compact -offset indent
 104 .It ZIP_STAT_NAME
 105 .Ar name
 106 .It ZIP_STAT_INDEX
 107 .Ar index
 108 .It ZIP_STAT_SIZE
 109 .Ar size
 110 .It ZIP_STAT_COMP_SIZE
 111 .Ar comp_size
 112 .It ZIP_STAT_MTIME
 113 .Ar mtime
 114 .It ZIP_STAT_CRC
 115 .Ar crc
 116 .It ZIP_STAT_COMP_METHOD
 117 .Ar comp_method
 118 .It ZIP_STAT_ENCRYPTION_METHOD
 119 .Ar encryption_method
 120 .It ZIP_STAT_FLAGS
 121 .Ar flags
 122 .El
 123 .Sh RETURN VALUES
 124 Upon successful completion 0 is returned.
 125 Otherwise, \-1 is returned and the error information in
 126 .Ar archive
 127 is set to indicate the error.
 128 .Sh ERRORS
 129 The function
 130 .Fn zip_stat
 131 can fail for any of the errors specified for the routine
 132 .Xr zip_name_locate 3 .
 133 .Pp
 134 The function
 135 .Fn zip_stat_index
 136 fails and sets the error information to
 137 .Er ZIP_ER_INVAL
 138 if
 139 .Ar index
 140 is invalid.
 141 If
 142 .Dv ZIP_FL_UNCHANGED
 143 is not set and no information can be obtained from the source
 144 callback, the error information is set to
 145 .Er ZIP_ER_CHANGED .
 146 .Sh SEE ALSO
 147 .Xr libzip 3 ,
 148 .Xr zip_get_num_entries 3 ,
 149 .Xr zip_name_locate 3 ,
 150 .Xr zip_stat_init 3
 151 .Sh AUTHORS
 152 .An -nosplit
 153 .An Dieter Baron Aq dillo@giga.or.at
 154 and
 155 .An Thomas Klausner Aq tk@giga.or.at