man/zip_get_name.man

   1 .TH "ZIP_GET_NAME" "3" "December 18, 2017" "NiH" "Library Functions Manual"
   2 .nh
   3 .if n .ad l
   4 .SH "NAME"
   5 \fBzip_get_name\fR
   6 \- get name of file by index
   7 .SH "LIBRARY"
   8 libzip (-lzip)
   9 .SH "SYNOPSIS"
  10 \fB#include <zip.h>\fR
  11 .sp
  12 \fIconst char *\fR
  13 .br
  14 .PD 0
  15 .HP 4n
  16 \fBzip_get_name\fR(\fIzip_t\ *archive\fR, \fIzip_uint64_t\ index\fR, \fIzip_flags_t\ flags\fR);
  17 .PD
  18 .SH "DESCRIPTION"
  19 The
  20 \fBzip_get_name\fR()
  21 function returns the name of the file at position
  22 \fIindex\fR
  23 in
  24 \fIarchive\fR.
  25 The name is in UTF-8 encoding unless
  26 \fRZIP_FL_ENC_RAW\fR
  27 was specified (see below).
  28 .PP
  29 If
  30 \fIflags\fR
  31 is set to
  32 \fRZIP_FL_UNCHANGED\fR,
  33 the original unchanged filename is returned.
  34 The returned string must not be modified or freed, and becomes invalid when
  35 \fIarchive\fR
  36 is closed.
  37 .PP
  38 Additionally, the following
  39 \fIflags\fR
  40 are supported:
  41 .RS 6n
  42 .TP 21n
  43 \fRZIP_FL_ENC_RAW\fR
  44 Return the unmodified names as it is in the ZIP archive.
  45 .TP 21n
  46 \fRZIP_FL_ENC_GUESS\fR
  47 (Default.)
  48 Guess the encoding of the name in the ZIP archive and convert it
  49 to UTF-8, if necessary.
  50 .TP 21n
  51 \fRZIP_FL_ENC_STRICT\fR
  52 Follow the ZIP specification and expect CP-437 encoded names in
  53 the ZIP archive (except if they are explicitly marked as UTF-8).
  54 Convert it to UTF-8.
  55 .RE
  56 \fINote\fR:
  57 ASCII is a subset of both CP-437 and UTF-8.
  58 .SH "RETURN VALUES"
  59 Upon successful completion, a pointer to the name is returned.
  60 Otherwise,
  61 \fRNULL\fR
  62 and the error code in
  63 \fIarchive\fR
  64 is set to indicate the error.
  65 .SH "ERRORS"
  66 \fBzip_get_name\fR()
  67 fails if:
  68 .TP 19n
  69 [\fRZIP_ER_DELETED\fR]
  70 \fIindex\fR
  71 refers to a file that has been deleted
  72 (see
  73 zip_delete(3)).
  74 .TP 19n
  75 [\fRZIP_ER_INVAL\fR]
  76 \fIindex\fR
  77 is not a valid file index in
  78 \fIarchive\fR,
  79 or
  80 \fIindex\fR
  81 points to an added file and
  82 \fRZIP_FL_UNCHANGED\fR
  83 is set.
  84 .TP 19n
  85 [\fRZIP_ER_MEMORY\fR]
  86 Required memory could not be allocated.
  87 .SH "SEE ALSO"
  88 libzip(3),
  89 zip_name_locate(3)
  90 .SH "HISTORY"
  91 \fBzip_get_name\fR()
  92 was added in libzip 0.6.
  93 In libzip 0.10 the type of
  94 \fIindex\fR
  95 was changed from
  96 \fIint\fR
  97 to
  98 \fIzip_uint64_t\fR.
  99 In libzip 0.11 the type of
 100 \fIflags\fR
 101 was changed from
 102 \fIint\fR
 103 to
 104 \fIzip_flags_t\fR.
 105 .SH "AUTHORS"
 106 Dieter Baron <\fIdillo@nih.at\fR>
 107 and
 108 Thomas Klausner <\fItk@giga.or.at\fR>