Add man page for the zip_add* functions. XXX: needs more work, but describes the basics. --HG-- branch : HEAD
diff --git a/man/zip_add.mdoc b/man/zip_add.mdoc new file mode 100644 index 0000000..c761a0c --- /dev/null +++ b/man/zip_add.mdoc
@@ -0,0 +1,173 @@ +.\" $NiH: zip_delete.mdoc,v 1.4 2003/10/03 23:26:00 dillo Exp $ +.\" +.\" zip_add.mdoc -- add files to zip archive +.\" Copyright (C) 2004 Dieter Baron and Thomas Klausner +.\" +.\" This file is part of libzip, a library to manipulate ZIP archives. +.\" The authors can be contacted at <nih@giga.or.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 July 4, 2004 +.Dt ZIP_ADD 3 +.Os +.Sh NAME +.Nm zip_add , +.Nm zip_add_data , +.Nm zip_add_file , +.Nm zip_add_filep , +.Nm zip_add_zip +.Nd add file to zip archive +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.In zip.h +.Ft int +.Fn zip_add "struct zip *zf" "const char *name" "zip_read_func fn" \ +"void *state" +.Ft int +.Fn zip_add_data "struct zip *zf" "const char *name" "const void *data" \ +"off_t len" "int freep" +.Ft int +.Fn zip_add_file "struct zip *zf" "const char *name" "const char *fname" \ +"off_t start" "off_t len" +.Ft int +.Fn zip_add_filep "struct zip *zf" "const char *name" "FILE *file" \ +"off_t start" "off_t len" +.Ft int +.Fn zip_add_zip "struct zip *zf" "const char *name" "struct zip *srczf" \ +"int srcidx" "int flags" "off_t start" "off_t len" +.Sh DESCRIPTION +The functions +.Fn zip_add , +.Fn zip_add_data , +.Fn zip_add_file , +.Fn zip_add_filep , +and +.Fn zip_add_zip +provide various ways to add a file to a zip archive. +The argument +.Ar zf +describes the zip archive to which the file should be added, and +.Ar name +is its name in the zip archive. +The other arguments describe the input file, depending on the function. +.Bl -tag -width XzipXaddXfilepXX +.It Fn zip_add +.Ar fn +is a user-supplied function of the following type: +.Bd -literal +typedef ssize_t (*zip_read_func)(void *state, + void *data, size_t len, enum zip_cmd cmd); +.Ed +.Pp +.Ar fn +will be called by the library with the +.Fn zip_add +.Ar state +argument as the first argument, a buffer +.Ar data +of size +.Ar len +for the data as second and third arguments when actually +reading data, and +.Ar cmd +as the fourth argument. +.Ar cmd +can be any of the following: +.Bl -tag -width XZIPXCMDXCLOSEXX -offset indent +.It Dv ZIP_CMD_OPEN +Prepare for reading. +.It Dv ZIP_CMD_READ +Read data into the buffer +.Ar data +of size +.Ar len. +.It Dv ZIP_CMD_CLOSE +Reading is done, close the input file. +.It Dv ZIP_CMD_STAT +Get meta information for the input file. +.\" XXX: format? +.It Dv ZIP_CMD_ERROR +Get error information. +.\" XXX: more detail +.It Dv ZIP_CMD_FREE +Cleanup and free resources. +.\" XXX: more detail when this is called +.El +.It Fn zip_add_data +The data for the file is supplied directly in the buffer +.Ar data +of size +.Ar len. +If +.Ar freep +is set, the library will +.Fn free +.Ar data +when it does not need it any longer. +.It Fn zip_add_file +Read +.Ar len +bytes from offset +.Ar start +from the file +.Ar name +in the file system. +.It Fn zip_add_filep +Read +.Ar len +bytes from offset +.Ar start +from the the open file stream +.Ar file . +.It Fn zip_add_zip +Add +.Ar len +bytes starting from the offset +.Ar start +from the file +.Ar srcidx +in the zip archive +.Ar srczf . +.\" XXX: describe flags +.El +.Sh RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, \-1 is returned and the global variable +.Va zip_err +is set to indicate the error. +.\".Sh ERRORS +.\".Fn zip_delete +.\"fails if: +.\".Bl -tag -width Er +.\".It Bq Er ZERR_INVAL +.\".Ar index +.\"is not a valid file index in +.\".Ar archive . +.\".El +.Sh SEE ALSO +.Xr zip_replace 3