Document zip_file_get_comment.
diff --git a/man/Makefile.am b/man/Makefile.am index db2f51b..87c4cc5 100644 --- a/man/Makefile.am +++ b/man/Makefile.am
@@ -21,6 +21,7 @@ zip_fclose.mdoc \ zip_fdopen.mdoc \ zip_file_add.mdoc \ + zip_file_get_comment.mdoc \ zip_file_rename.mdoc \ zip_file_strerror.mdoc \ zip_fopen.mdoc \
diff --git a/man/zip_file_get_comment.mdoc b/man/zip_file_get_comment.mdoc new file mode 100644 index 0000000..ad4c12b --- /dev/null +++ b/man/zip_file_get_comment.mdoc
@@ -0,0 +1,112 @@ +.\" zip_file_get_comment.mdoc -- get comment for file in zip +.\" Copyright (C) 2006-2012 Dieter Baron and Thomas Klausner +.\" +.\" This file is part of libzip, a library to manipulate ZIP files. +.\" The authors can be contacted at <libzip@nih.at> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" 3. The names of the authors may not be used to endorse or promote +.\" products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 23, 2012 +.Dt ZIP_FILE_GET_COMMENT 3 +.Os +.Sh NAME +.Nm zip_file_get_comment +.Nd get comment for file in zip +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.In zip.h +.Ft const char * +.Fn zip_file_get_comment "struct zip *archive" "zip_uint64_t index" "zip_uint32_t *lenp" \ +"zip_flags_t flags" +.Sh DESCRIPTION +The +.Fn zip_file_get_comment +function returns the comment for the file at position +.Ar index +in the zip archive. +The name is in UTF-8 encoding unless +.Dv ZIP_FL_NAME_RAW +was specified (see below). +This pointer should not be modified or +.Xr free 3 Ap d , +and becomes invalid when +.Ar archive +is closed. +If +.Ar lenp +is not +.Dv NULL , +the integer to which it points will be set to the length of the +comment. +If +.Ar flags +is set to +.Dv ZIP_FL_UNCHANGED , +the original unchanged comment is returned. +.Pp +Additionally, the following flags are supported: +.Bl -tag -width ZIP_FL_NAME_STRICTXX -offset indent +.It Dv ZIP_FL_NAME_RAW +Return the unmodified comment as it is in the ZIP archive. +.It Dv ZIP_FL_NAME_GUESS +(Default.) +Guess the encoding of the comment in the ZIP archive and convert it +to UTF-8, if necessary. +.It Dv ZIP_FL_NAME_STRICT +Follow the ZIP specification for file names and extend it to file comments, +expecting them to be encoded in CP-437 in the ZIP archive. +(ASCII is a subset of CP-437.) +Convert it to UTF-8. +.El +.Sh RETURN VALUES +Upon successful completion, a pointer to the comment is returned, +or +.Dv NULL +if there is no comment. +In case of an error, +.Dv NULL +is returned and the error code in +.Ar archive +is set to indicate the error. +.Sh ERRORS +.Fn zip_get_file_comment +fails if: +.Bl -tag -width Er +.It Bq Er ZIP_ER_INVAL +.Ar index +is not a valid file index in +.Ar archive . +.El +.Sh SEE ALSO +.Xr libzip 3 , +.Xr zip_file_set_comment 3 , +.Xr zip_get_archive_comment 3 +.Sh AUTHORS +.An -nosplit +.An Dieter Baron Aq dillo@giga.or.at +and +.An Thomas Klausner Aq tk@giga.or.at
diff --git a/man/zip_get_file_comment.mdoc b/man/zip_get_file_comment.mdoc index 8e19d76..3eabd1f 100644 --- a/man/zip_get_file_comment.mdoc +++ b/man/zip_get_file_comment.mdoc
@@ -29,7 +29,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd February 20, 2012 +.Dd June 23, 2012 .Dt ZIP_GET_FILE_COMMENT 3 .Os .Sh NAME @@ -44,65 +44,16 @@ .Sh DESCRIPTION The .Fn zip_get_file_comment -function returns the comment for the file at position -.Ar index -in the zip archive. -The name is in UTF-8 encoding unless -.Dv ZIP_FL_NAME_RAW -was specified (see below). -This pointer should not be modified or -.Xr free 3 Ap d , -and becomes invalid when -.Ar archive -is closed. -If +function is the obsolete version of +.Xr zip_file_get_comment 3 . +The only differences are the types of the .Ar lenp -is not -.Dv NULL , -the integer to which it points will be set to the length of the -comment. -If +and .Ar flags -is set to -.Dv ZIP_FL_UNCHANGED , -the original unchanged comment is returned. -.Pp -Additionally, the following flags are supported: -.Bl -tag -width ZIP_FL_NAME_STRICTXX -offset indent -.It Dv ZIP_FL_NAME_RAW -Return the unmodified comment as it is in the ZIP archive. -.It Dv ZIP_FL_NAME_GUESS -(Default.) -Guess the encoding of the comment in the ZIP archive and convert it -to UTF-8, if necessary. -.It Dv ZIP_FL_NAME_STRICT -Follow the ZIP specification for file names and extend it to file comments, -expecting them to be encoded in CP-437 in the ZIP archive. -(ASCII is a subset of CP-437.) -Convert it to UTF-8. -.El -.Sh RETURN VALUES -Upon successful completion, a pointer to the comment is returned, -or -.Dv NULL -if there is no comment. -In case of an error, -.Dv NULL -is returned and the error code in -.Ar archive -is set to indicate the error. -.Sh ERRORS -.Fn zip_get_file_comment -fails if: -.Bl -tag -width Er -.It Bq Er ZIP_ER_INVAL -.Ar index -is not a valid file index in -.Ar archive . -.El +arguments. .Sh SEE ALSO .Xr libzip 3 , -.Xr zip_get_archive_comment 3 +.Xr zip_file_get_comment 3 .Sh AUTHORS .An -nosplit .An Dieter Baron Aq dillo@giga.or.at