man/zip_file_get_comment.man

   1 .TH "ZIP_FILE_GET_COMMENT" "3" "September 19, 2013" "NiH" "Library Functions Manual"
   2 .nh
   3 .if n .ad l
   4 .SH "NAME"
   5 \fBzip_file_get_comment\fR
   6 \- get comment for file in zip
   7 .SH "LIBRARY"
   8 libzip (-lzip)
   9 .SH "SYNOPSIS"
  10 \fB#include <zip.h>\fR
  11 .sp
  12 \fIconst char *\fR
  13 .PD 0
  14 .HP 4n
  15 \fBzip_file_get_comment\fR(\fIzip_t\ *archive\fR, \fIzip_uint64_t\ index\fR, \fIzip_uint32_t\ *lenp\fR, \fIzip_flags_t\ flags\fR);
  16 .PD
  17 .SH "DESCRIPTION"
  18 The
  19 \fBzip_file_get_comment\fR()
  20 function returns the comment for the file at position
  21 \fIindex\fR
  22 in the zip archive.
  23 The name is in UTF-8 encoding unless
  24 \fRZIP_FL_ENC_RAW\fR
  25 was specified (see below).
  26 This pointer should not be modified or
  27 free(3)'d,
  28 and becomes invalid when
  29 \fIarchive\fR
  30 is closed.
  31 If
  32 \fIlenp\fR
  33 is not
  34 \fRNULL\fR,
  35 the integer to which it points will be set to the length of the
  36 comment.
  37 If
  38 \fIflags\fR
  39 is set to
  40 \fRZIP_FL_UNCHANGED\fR,
  41 the original unchanged comment is returned.
  42 .PP
  43 Additionally, the following
  44 \fIflags\fR
  45 are supported:
  46 .RS 6n
  47 .TP 21n
  48 \fRZIP_FL_ENC_RAW\fR
  49 Return the unmodified comment as it is in the ZIP archive.
  50 .TP 21n
  51 \fRZIP_FL_ENC_GUESS\fR
  52 (Default.)
  53 Guess the encoding of the comment in the ZIP archive and convert it
  54 to UTF-8, if necessary.
  55 .TP 21n
  56 \fRZIP_FL_ENC_STRICT\fR
  57 Follow the ZIP specification for file names and extend it to file
  58 comments, expecting them to be encoded in CP-437 in the ZIP archive
  59 (except if it is a UTF-8 comment from the special extra field).
  60 Convert it to UTF-8.
  61 .RE
  62 \fINote\fR:
  63 ASCII is a subset of both CP-437 and UTF-8.
  64 .SH "RETURN VALUES"
  65 Upon successful completion, a pointer to the comment is returned,
  66 or
  67 \fRNULL\fR
  68 if there is no comment.
  69 In case of an error,
  70 \fRNULL\fR
  71 is returned and the error code in
  72 \fIarchive\fR
  73 is set to indicate the error.
  74 .SH "ERRORS"
  75 \fBzip_file_get_comment\fR()
  76 fails if:
  77 .TP 19n
  78 [\fRZIP_ER_INVAL\fR]
  79 \fIindex\fR
  80 is not a valid file index in
  81 \fIarchive\fR.
  82 .SH "SEE ALSO"
  83 libzip(3),
  84 zip_file_set_comment(3),
  85 zip_get_archive_comment(3)
  86 .SH "AUTHORS"
  87 Dieter Baron <\fIdillo@nih.at\fR>
  88 and
  89 Thomas Klausner <\fItk@giga.or.at\fR>