document commands more fully
improve and fleshen out
--HG--
branch : HEAD
diff --git a/man/zip_source_function.mdoc b/man/zip_source_function.mdoc
index 8dd6501..b395b44 100644
--- a/man/zip_source_function.mdoc
+++ b/man/zip_source_function.mdoc
@@ -1,4 +1,4 @@
-.\" $NiH: zip_source_function.mdoc,v 1.1 2004/11/18 16:48:08 wiz Exp $
+.\" $NiH: zip_source_function.mdoc,v 1.2 2004/11/18 17:26:54 wiz Exp $
.\"
.\" zip_source_function.mdoc -- create data source from function
.\" Copyright (C) 2004 Dieter Baron and Thomas Klausner
@@ -31,7 +31,7 @@
.\" 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
+.Dd December 10, 2004
.Dt ZIP_SOURCE_FUNCTION 3
.Os
.Sh NAME
@@ -46,50 +46,75 @@
.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:
+creates a zip source from the user-provided function
+.Ar fn ,
+which must be 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
+When called by the library, the first argument is the
.Ar state
-argument as the first argument, a buffer
+argument supplied to
+.Fn zip_source_function .
+The next two arguments are 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:
+when data is expected to be returned, or else
+.Dv NULL
+and 0.
+The last argument,
+.Ar cmd ,
+specifies which action the function should perform:
.Bl -tag -width XZIPXCMDXCLOSEXX -offset indent
.It Dv ZIP_CMD_OPEN
-Prepare for reading.
+Prepare for reading. Return 0 on success, \-1 on error.
.It Dv ZIP_CMD_READ
Read data into the buffer
.Ar data
of size
-.Ar len.
+.Ar len .
+Return the number of bytes placed into
+.Ar data
+on success, \-1 on error.
.It Dv ZIP_CMD_CLOSE
-Reading is done, close the input file.
+Reading is done.
.It Dv ZIP_CMD_STAT
Get meta information for the input file.
-.\" XXX: format?
+.Ar data
+points to a struct zip_stat, which should be filled in. Return 0 on
+succeess, \-1 on error.
.It Dv ZIP_CMD_ERROR
Get error information.
-.\" XXX: more detail
+.Ar data
+points to an array of two ints, which should be filled with the libzip
+error code and the corresponding system error code for the error that
+occurred. Return 0.
+.\" XXX: we should document all error codes somewhere
.It Dv ZIP_CMD_FREE
-Cleanup and free resources.
-.\" XXX: more detail when this is called
+Clean up and free all resources. Return 0.
.El
-.El
+.Pp
+The library will always issue
+.Dv ZIP_CMD_OPEN
+before issuing
+.Dv ZIP_CMD_READ .
+When it no longer wishes to read from this source, it will issue
+.Dv ZIP_CMD_READ .
+If the library wishes to read the data again, it will issue
+.Dv ZIP_CMD_OPEN
+a second time. If the function is unable to provide
+the data again, it should return \-1.
+.Pp
+.Dv ZIP_CMD_STAT
+can be issued at any time.
+.Dv ZIP_CMD_ERROR
+will only be issued in response to the function
+returning \-1.
+.Dv ZIP_CMD_FREE
+will be the last command issued.
.Sh RETURN VALUES
Upon successful completion, the created source is returned.
Otherwise,
