man/zip_open.mdoc

   1 .\" zip_open.mdoc -- open zip archive
   2 .\" Copyright (C) 2003-2022 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 June 18, 2022
  33 .Dt ZIP_OPEN 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_open ,
  37 .Nm zip_open_from_source
  38 .Nd open zip archive
  39 .Sh LIBRARY
  40 libzip (-lzip)
  41 .Sh SYNOPSIS
  42 .In zip.h
  43 .Ft zip_t *
  44 .Fn zip_open "const char *path" "int flags" "int *errorp"
  45 .Ft zip_t *
  46 .Fn zip_open_from_source "zip_source_t *zs" "int flags" "zip_error_t *ze"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn zip_open
  50 function opens the zip archive specified by
  51 .Ar path
  52 and returns a pointer to a
  53 .Ft struct zip ,
  54 used to manipulate the archive.
  55 The
  56 .Fa flags
  57 are specified by
  58 .Em or Ns No 'ing
  59 the following values, or 0 for none of them.
  60 .Bl -tag -offset indent -width ZIP_CHECKCONS
  61 .It Dv ZIP_CHECKCONS
  62 Perform additional stricter consistency checks on the archive, and
  63 error if they fail.
  64 .It Dv ZIP_CREATE
  65 Create the archive if it does not exist.
  66 .It Dv ZIP_EXCL
  67 Error if archive already exists.
  68 .It Dv ZIP_TRUNCATE
  69 If archive exists, ignore its current contents.
  70 In other words, handle it the same way as an empty archive.
  71 .It Dv ZIP_RDONLY
  72 Open archive in read-only mode.
  73 .El
  74 .Pp
  75 If an error occurs and
  76 .Ar errorp
  77 is
  78 .Pf non- Dv NULL ,
  79 it will be set to the corresponding error code.
  80 .Pp
  81 The
  82 .Fn zip_open_from_source
  83 function opens a zip archive encapsulated by the zip_source
  84 .Fa zs
  85 using the provided
  86 .Fa flags .
  87 In case of error, the zip_error
  88 .Fa ze
  89 is filled in.
  90 .Sh RETURN VALUES
  91 Upon successful completion
  92 .Fn zip_open
  93 and
  94 .Fn zip_open_from_source
  95 return a
  96 .Ft struct zip
  97 pointer.
  98 Otherwise,
  99 .Dv NULL
 100 is returned and
 101 .Fn zip_open
 102 sets
 103 .Ar *errorp
 104 to indicate the error, while
 105 .Fn zip_open_from source
 106 sets
 107 .Ar ze
 108 to indicate the error.
 109 .Sh ERRORS
 110 The archive specified by
 111 .Ar path
 112 is opened unless:
 113 .Bl -tag -width Er
 114 .It Bq Er ZIP_ER_EXISTS
 115 The file specified by
 116 .Ar path
 117 exists and
 118 .Dv ZIP_EXCL
 119 is set.
 120 .It Bq Er ZIP_ER_INCONS
 121 Inconsistencies were found in the file specified by
 122 .Ar path .
 123 This error is often caused by specifying
 124 .Dv ZIP_CHECKCONS
 125 but can also happen without it.
 126 .It Bq Er ZIP_ER_INVAL
 127 The
 128 .Ar path
 129 argument is
 130 .Dv NULL .
 131 .It Bq Er ZIP_ER_MEMORY
 132 Required memory could not be allocated.
 133 .It Bq Er ZIP_ER_NOENT
 134 The file specified by
 135 .Ar path
 136 does not exist and
 137 .Dv ZIP_CREATE
 138 is not set.
 139 .It Bq Er ZIP_ER_NOZIP
 140 The file specified by
 141 .Ar path
 142 is not a zip archive.
 143 .It Bq Er ZIP_ER_OPEN
 144 The file specified by
 145 .Ar path
 146 could not be opened.
 147 .It Bq Er ZIP_ER_READ
 148 A read error occurred; see
 149 .Va errno
 150 for details.
 151 .It Bq Er ZIP_ER_SEEK
 152 The file specified by
 153 .Ar path
 154 does not allow seeks.
 155 .El
 156 For newly created archives,
 157 .Fn zip_open
 158 does not try to create the file; this is done when calling
 159 .Xr zip_close 3
 160 and any errors, like missing write permissions, will
 161 be reported then.
 162 .Sh SEE ALSO
 163 .Xr libzip 3 ,
 164 .Xr zip_close 3 ,
 165 .Xr zip_error_strerror 3 ,
 166 .Xr zip_fdopen 3
 167 .Sh HISTORY
 168 .Fn zip_open
 169 and
 170 .Fn zip_open_from_source
 171 were added in libzip 1.0.
 172 .Sh AUTHORS
 173 .An -nosplit
 174 .An Dieter Baron Aq Mt dillo@nih.at
 175 and
 176 .An Thomas Klausner Aq Mt tk@giga.or.at