man/zip_fopen.mdoc

   1 .\" zip_fopen.mdoc -- open file in zip archive for reading
   2 .\" Copyright (C) 2003-2016 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 September 12, 2016
  33 .Dt ZIP_FOPEN 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_fopen ,
  37 .Nm zip_fopen_index
  38 .Nd open file in zip archive for reading
  39 .Sh LIBRARY
  40 libzip (-lzip)
  41 .Sh SYNOPSIS
  42 .In zip.h
  43 .Ft zip_file_t *
  44 .Fn zip_fopen "zip_t *archive" "const char *fname" "zip_flags_t flags"
  45 .Ft zip_file_t *
  46 .Fn zip_fopen_index "zip_t *archive" "zip_uint64_t index" "zip_flags_t flags"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn zip_fopen
  50 function opens the file name
  51 .Ar fname
  52 in
  53 .Ar archive .
  54 The
  55 .Ar flags
  56 argument specifies how the name lookup should be done, according to
  57 the values are described in
  58 .Xr zip_name_locate 3 .
  59 Also, the following values may be
  60 .Em or Ns No 'ed
  61 to it.
  62 .Bl -tag -offset indent -width ZIP_FL_COMPRESSED
  63 .It Dv ZIP_FL_COMPRESSED
  64 Read the compressed data.
  65 Otherwise the data is uncompressed by
  66 .Fn zip_fread .
  67 .It Dv ZIP_FL_UNCHANGED
  68 Read the original data from the zip archive, ignoring any changes made
  69 to the file.
  70 .El
  71 .Pp
  72 The
  73 .Fn zip_fopen_index
  74 function opens the file at position
  75 .Ar index .
  76 .Pp
  77 If encrypted data is encountered, the functions call
  78 .Xr zip_fopen_encrypted 3
  79 or
  80 .Xr zip_fopen_index_encrypted 3
  81 respectively, using the default password set with
  82 .Xr zip_set_default_password 3 .
  83 .Sh RETURN VALUES
  84 Upon successful completion, a
  85 .Ft struct zip_file
  86 pointer is returned.
  87 Otherwise,
  88 .Dv NULL
  89 is returned and the error code in
  90 .Ar archive
  91 is set to indicate the error.
  92 .Sh ERRORS
  93 .Bl -tag -width Er
  94 .It Bq Er ZIP_ER_CHANGED
  95 The file data has been changed.
  96 .It Bq Er ZIP_ER_COMPNOTSUPP
  97 The compression method used is not supported.
  98 .It Bq Er ZIP_ER_ENCRNOTSUPP
  99 The encryption method used is not supported.
 100 .It Bq Er ZIP_ER_MEMORY
 101 Required memory could not be allocated.
 102 .It Bq Er ZIP_ER_NOPASSWD
 103 The file is encrypted, but no password has been provided.
 104 .It Bq Er ZIP_ER_READ
 105 A file read error occurred.
 106 .It Bq Er ZIP_ER_SEEK
 107 A file seek error occurred.
 108 .It Bq Er ZIP_ER_WRONGPASSWD
 109 The provided password does not match the password used for encryption.
 110 Note that some incorrect passwords are not detected by the check done by
 111 .Fn zip_fopen .
 112 .It Bq Er ZIP_ER_ZLIB
 113 Initializing the zlib stream failed.
 114 .El
 115 .Pp
 116 The function
 117 .Fn zip_fopen
 118 may also fail and set
 119 .Va zip_err
 120 for any of the errors specified for the routine
 121 .Xr zip_name_locate 3 .
 122 .Pp
 123 The function
 124 .Fn zip_fopen_index
 125 may also fail with
 126 .Er ZIP_ER_INVAL
 127 if
 128 .Ar index
 129 is invalid.
 130 .Sh SEE ALSO
 131 .Xr libzip 3 ,
 132 .Xr zip_fclose 3 ,
 133 .Xr zip_fread 3 ,
 134 .Xr zip_fseek 3 ,
 135 .Xr zip_get_num_entries 3 ,
 136 .Xr zip_name_locate 3 ,
 137 .Xr zip_set_default_password 3
 138 .Sh AUTHORS
 139 .An -nosplit
 140 .An Dieter Baron Aq Mt dillo@nih.at
 141 and
 142 .An Thomas Klausner Aq Mt tk@giga.or.at