Add some man pages. --HG-- branch : HEAD
diff --git a/TODO b/TODO index 11d68bd..869274f 100644 --- a/TODO +++ b/TODO
@@ -18,8 +18,6 @@ * sort zipint.h contents * documentation: zip_error_sys_type zip_file_get_error zip_get_error - zip_source_file zip_source_filep zip_source_function - zip_source_zip * don't allow the same filename twice in a zip (when adding/replacing) * regression tests * code review
diff --git a/man/zip_source_file.mdoc b/man/zip_source_file.mdoc new file mode 100644 index 0000000..a692bb2 --- /dev/null +++ b/man/zip_source_file.mdoc
@@ -0,0 +1,93 @@ +.\" $NiH: zip_source.mdoc,v 1.2 2004/11/17 21:55:14 wiz Exp $ +.\" +.\" zip_source_file.mdoc -- create data source from a file +.\" 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 November 4, 2004 +.Dt ZIP_SOURCE_FILE 3 +.Os +.Sh NAME +.Nm zip_source_file +.Nd create data source from a file +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.Ft int +.Fn zip_source_file "struct zip *archive" "const char *fname" "off_t start" "off_t len" +.Sh DESCRIPTION +The function +.Fn zip_source_file +creates a zip source from a file. +.Fn zip_source_filep +opens +.Ar fname +and reads +.Ar len +bytes from offset +.Ar start +from it. +If +.Ar len +is 0 or \-1, the whole file (starting from +.Ar start ) +is used. +.Sh RETURN VALUES +Upon successful completion, the created source is returned. +Otherwise, +.Dv NULL +is returned and the error code in +.Ar archive +is set to indicate the error. +.Sh ERRORS +.Fn zip_source_file +fails if: +.Bl -tag -width Er +.It Bq Er ZIP_ER_INVAL +.Ar fname , +.Ar start , +or +.Ar len +are invalid. +.It Bq Er ZIP_ER_MEMORY +Required memory could not be allocated. +.It Bq Er ZIP_ER_OPEN +Opening +.Ar fname +failed. +.El +.Sh SEE ALSO +.Xr zip_add 3 , +.Xr zip_replace 3 , +.Xr zip_source_data 3 , +.Xr zip_source_filep 3 , +.Xr zip_source_free 3 , +.Xr zip_source_function 3 , +.Xr zip_source_zip 3
diff --git a/man/zip_source_filep.mdoc b/man/zip_source_filep.mdoc new file mode 100644 index 0000000..cdacebd --- /dev/null +++ b/man/zip_source_filep.mdoc
@@ -0,0 +1,88 @@ +.\" $NiH: zip_source.mdoc,v 1.2 2004/11/17 21:55:14 wiz Exp $ +.\" +.\" zip_source_filep.mdoc -- create data source from a file stream +.\" 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 November 4, 2004 +.Dt ZIP_SOURCE_FILEP 3 +.Os +.Sh NAME +.Nm zip_source_filep +.Nd create data source from FILE * +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.Ft int +.Fn zip_source_filep "struct zip *archive" "FILE *file" "off_t start" "off_t len" +.Sh DESCRIPTION +The function +.Fn zip_source_filep +creates a zip source from a file stream. +.Fn zip_source_filep +reads +.Ar len +bytes from offset +.Ar start +from the open file stream +.Ar file . +If +.Ar len +is 0 or \-1, the whole file (starting from +.Ar start ) +is used. +.Sh RETURN VALUES +Upon successful completion, the created source is returned. +Otherwise, +.Dv NULL +is returned and the error code in +.Ar archive +is set to indicate the error. +.Sh ERRORS +.Fn zip_source_filep +fails if: +.Bl -tag -width Er +.It Bq Er ZIP_ER_INVAL +.Ar file , +.Ar start , +or +.Ar len +are invalid. +.It Bq Er ZIP_ER_MEMORY +Required memory could not be allocated. +.El +.Sh SEE ALSO +.Xr zip_add 3 , +.Xr zip_replace 3 , +.Xr zip_source_data 3 , +.Xr zip_source_file 3 , +.Xr zip_source_free 3 , +.Xr zip_source_function 3 , +.Xr zip_source_zip 3
diff --git a/man/zip_source_function.mdoc b/man/zip_source_function.mdoc new file mode 100644 index 0000000..4498d63 --- /dev/null +++ b/man/zip_source_function.mdoc
@@ -0,0 +1,114 @@ +.\" $NiH: zip_source.mdoc,v 1.2 2004/11/17 21:55:14 wiz Exp $ +.\" +.\" zip_source_function.mdoc -- create data source from function +.\" 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 November 4, 2004 +.Dt ZIP_SOURCE_FUNCTION 3 +.Os +.Sh NAME +.Nm zip_source_function +.Nd create data source from function +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.In zip.h +.Ft int +.Fn zip_source_function "struct zip *archive" "zip_read_func fn" "void *userdata" +.Sh DESCRIPTION +The function +.Fn zip_source_function +creates a zip source from an arbitrary given function +.Ar fn . +.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_source +.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 +.El +.Sh RETURN VALUES +Upon successful completion, the created source is returned. +Otherwise, +.Dv NULL +is returned and the error code in +.Ar archive +is set to indicate the error. +.Sh ERRORS +.Fn zip_source_function +fails if: +.Bl -tag -width Er +.It Bq Er ZIP_ER_MEMORY +Required memory could not be allocated. +.El +.Sh SEE ALSO +.Xr zip_add 3 , +.Xr zip_replace 3 , +.Xr zip_source_data 3 , +.Xr zip_source_file 3 , +.Xr zip_source_filep 3 , +.Xr zip_source_free 3 , +.Xr zip_source_zip 3
diff --git a/man/zip_source_zip.mdoc b/man/zip_source_zip.mdoc new file mode 100644 index 0000000..ad4b8da --- /dev/null +++ b/man/zip_source_zip.mdoc
@@ -0,0 +1,113 @@ +.\" $NiH: zip_source.mdoc,v 1.2 2004/11/17 21:55:14 wiz Exp $ +.\" +.\" zip_source_zip.mdoc -- create data source from zip file +.\" 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 November 4, 2004 +.Dt ZIP_SOURCE_ZIP 3 +.Os +.Sh NAME +.Nm zip_source_zip +.Nd create data source from zip file +.Sh LIBRARY +libzip (-lzip) +.Sh SYNOPSIS +.In zip.h +.Ft int +.Fn zip_source_zip "struct zip *archive" "struct zip *srcarchive" \ +"int srcidx" "int flags" "off_t start" "off_t len" +.Sh DESCRIPTION +The function +.Fn zip_source_zip +creates a zip source from a file in a zip archive. +The +.Ar srcarchive +argument is the (open) zip archive containing the source zip file +at index +.Ar srcidx . +.Ar len +bytes from offset +.Ar start +will be used in the zip_source. +If +.Ar len +is 0 or \-1, the whole file (starting from +.Ar start ) +is used. +If +.Ar start +is zero and +.Ar len +is \-1, the whole file will be copied without decompressing it. +If +.Ar flags +is +.Dv ZIP_FL_UNCHANGED , +.Fn zip_source_zip +will try to get the original data without any changes that may +have been made to +.Ar srcarchive +after opening it. +.Sh RETURN VALUES +Upon successful completion, the created source is returned. +Otherwise, +.Dv NULL +is returned and the error code in +.Ar archive +is set to indicate the error. +.Sh ERRORS +.Fn zip_source_zip +fails if: +.Bl -tag -width Er +.It Bq Er ZIP_ER_CHANGED +Unchanged data was requested, but it is not available. +.It Bq Er ZIP_ER_INVAL +.Ar srcarchive , +.Ar srcidx , +.Ar start , +or +.Ar len +are invalid. +.It Bq Er ZIP_ER_MEMORY +Required memory could not be allocated. +.El +Additionally, it can return all error codes from +.Fn zip_stat_index +and +.Fn zip_fopen_index . +.Sh SEE ALSO +.Xr zip_add 3 , +.Xr zip_replace 3 , +.Xr zip_source_data 3 , +.Xr zip_source_file 3 , +.Xr zip_source_filep 3 , +.Xr zip_source_free 3 , +.Xr zip_source_function 3