man/zip_set_file_compression.mdoc

   1 .\" zip_set_file_compression.mdoc -- set compression method and its flags
   2 .\" Copyright (C) 2012-2017 Dieter Baron and Thomas Klausner
   3 .\"
   4 .\" This file is part of libzip, a library to manipulate ZIP files.
   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_SET_FILE_COMPRESSION 3
  34 .Os
  35 .Sh NAME
  36 .Nm zip_set_file_compression
  37 .Nd set compression method for file in zip
  38 .Sh LIBRARY
  39 libzip (-lzip)
  40 .Sh SYNOPSIS
  41 .In zip.h
  42 .Ft int
  43 .Fn zip_set_file_compression "zip_t *archive" "zip_uint64_t index" "zip_int32_t comp" "zip_uint32_t comp_flags"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn zip_set_file_compression
  47 function sets the compression method for the file at position
  48 .Ar index
  49 in the zip archive to
  50 .Ar comp
  51 with the compression method specific
  52 .Ar comp_flags .
  53 The
  54 .Ar comp
  55 is the same as returned by
  56 .Xr zip_stat 3 .
  57 For the
  58 .Ar comp
  59 argument, currently only the following values are supported:
  60 .Bl -tag -width ZIP_CM_DEFLATE_XX
  61 .It Dv ZIP_CM_DEFAULT
  62 default compression; currently the same as
  63 .Dv ZIP_CM_DEFLATE .
  64 .It Dv ZIP_CM_STORE
  65 Store the file uncompressed.
  66 .It Dv ZIP_CM_BZIP2
  67 Compress the file using the
  68 .Xr bzip2 1
  69 algorithm.
  70 .It Dv ZIP_CM_DEFLATE
  71 Deflate the file with the
  72 .Xr zlib 3
  73 algorithm and default options
  74 .El
  75 .Pp
  76 .Em NOTE :
  77 Only the deflate and store methods can be assumed to be universally
  78 supported.
  79 .Pp
  80 The
  81 .Ar comp_flags
  82 argument defines the compression level, 1 being fastest compression
  83 and 9 highest.
  84 Allowed values are 0 (which uses the default compression for the
  85 algorithm) and 1-9, other values are undefined.
  86 Further compression method specific flags might be added over time.
  87 .Pp
  88 The current compression method for a file in a zip archive can be
  89 determined using
  90 .Xr zip_stat 3 .
  91 .Sh RETURN VALUES
  92 Upon successful completion 0 is returned.
  93 Otherwise, \-1 is returned and the error information in
  94 .Ar archive
  95 is set to indicate the error.
  96 .Sh ERRORS
  97 .Fn zip_set_file_compression
  98 fails if:
  99 .Bl -tag -width Er
 100 .It Bq Er ZIP_ER_COMPNOTSUPP
 101 Unsupported compression method requested.
 102 .It Bq Er ZIP_ER_INVAL
 103 .Ar index
 104 is not a valid file index in
 105 .Ar archive ,
 106 or the argument combination is invalid.
 107 .It Bq Er ZIP_ER_RDONLY
 108 Read-only zip file, no changes allowed.
 109 .El
 110 .Sh SEE ALSO
 111 .Xr libzip 3 ,
 112 .Xr zip_stat 3
 113 .Sh HISTORY
 114 .Fn zip_set_file_compression
 115 was added in libzip 0.11.
 116 .Sh AUTHORS
 117 .An -nosplit
 118 .An Dieter Baron Aq Mt dillo@nih.at
 119 and
 120 .An Thomas Klausner Aq Mt tk@giga.or.at