"Fossies" - the Fresh Open Source Software Archive

Member "libzip-1.5.2/man/zip_fopen.mdoc" (12 Mar 2019, 4387 Bytes) of package /linux/misc/libzip-1.5.2.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "zip_fopen.mdoc": 1.3.2_vs_1.4.0.

    1 .\" zip_fopen.mdoc -- open file in zip archive for reading
    2 .\" Copyright (C) 2003-2017 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 December 18, 2017
   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 HISTORY
  139 .Fn zip_fopen
  140 and
  141 .Fn zip_fopen_index
  142 were added in libzip 1.0.
  143 .Sh AUTHORS
  144 .An -nosplit
  145 .An Dieter Baron Aq Mt dillo@nih.at
  146 and
  147 .An Thomas Klausner Aq Mt tk@giga.or.at