man/zip_close.mdoc

   1 .\" zip_close.mdoc -- close 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 April 1, 2022
  33 .Dt ZIP_CLOSE 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_close
  37 .Nd close zip archive
  38 .Sh LIBRARY
  39 libzip (-lzip)
  40 .Sh SYNOPSIS
  41 .In zip.h
  42 .Ft int
  43 .Fn zip_close "zip_t *archive"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn zip_close
  47 function writes any changes made to
  48 .Ar archive
  49 to disk.
  50 If
  51 .Ar archive
  52 contains no files, the file is completely removed (no empty archive is
  53 written).
  54 If successful,
  55 .Ar archive
  56 is freed.
  57 Otherwise
  58 .Ar archive
  59 is left unchanged and must still be freed.
  60 .Pp
  61 To close and free a zip archive without saving changes, use
  62 .Xr zip_discard 3 .
  63 .Pp
  64 Progress updates for GUIs can be implemented using
  65 .Xr zip_register_progress_callback_with_state 3 .
  66 Cancelling the write of an archive during
  67 .Nm
  68 can be implemented using
  69 .Xr zip_register_cancel_callback_with_state 3 .
  70 .Sh RETURN VALUES
  71 Upon successful completion 0 is returned.
  72 Otherwise, \-1 is returned and the error code in
  73 .Ar archive
  74 is set to indicate the error.
  75 .Sh ERRORS
  76 .Fn zip_close
  77 will fail if:
  78 .Bl -tag -width Er
  79 .It Bq Er ZIP_ER_EOF
  80 Unexpected end-of-file found while reading from a file.
  81 .It Bq Er ZIP_ER_INTERNAL
  82 The callback function of an added or replaced file returned an
  83 error but failed to report which.
  84 .It Bq Er ZIP_ER_INVAL
  85 The
  86 .Ar path
  87 argument is
  88 .Dv NULL .
  89 .It Bq Er ZIP_ER_MEMORY
  90 Required memory could not be allocated.
  91 .It Bq Er ZIP_ER_NOZIP
  92 File is not a zip archive.
  93 .It Bq Er ZIP_ER_READ
  94 A file read failed.
  95 .It Bq Er ZIP_ER_RENAME
  96 A temporary file could not be renamed to its final name.
  97 .It Bq Er ZIP_ER_SEEK
  98 A file seek failed.
  99 .It Bq Er ZIP_ER_TMPOPEN
 100 A temporary file could not be created.
 101 .It Bq Er ZIP_ER_WRITE
 102 A file write failed.
 103 .It Bq Er ZIP_ER_ZLIB
 104 An error occurred while (de)compressing a stream with
 105 .Xr zlib 3 .
 106 .El
 107 Additionally, any errors returned by the callback function
 108 for added or replaced files will be passed back.
 109 .Sh SEE ALSO
 110 .Xr libzip 3 ,
 111 .Xr zip_discard 3 ,
 112 .Xr zip_fdopen 3 ,
 113 .Xr zip_get_error 3 ,
 114 .Xr zip_open 3 ,
 115 .Xr zip_register_cancel_callback_with_state 3 ,
 116 .Xr zip_register_progress_callback_with_state 3 ,
 117 .Xr zip_strerror 3
 118 .Sh HISTORY
 119 .Fn zip_close
 120 was added in libzip 0.6.
 121 .Sh AUTHORS
 122 .An -nosplit
 123 .An Dieter Baron Aq Mt dillo@nih.at
 124 and
 125 .An Thomas Klausner Aq Mt tk@giga.or.at
 126 .Sh CAVEATS
 127 Please note that all indices,
 128 .Xr zip_stat 3
 129 information and other data about the archive is invalid after
 130 .Nm .
 131 When you open the same file again, it will be a completely new
 132 .Vt zip_t
 133 structure.