Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/gzio.9
- This file was added.
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org> | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" 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. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd February 14, 2015 | |||||
.Dt GZIO 9 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm gzio | |||||
.Nd a callback interface for the zlib compression library | |||||
.Sh SYNOPSIS | |||||
.Cd "options GZIO" | |||||
.Pp | |||||
.In sys/gzio.h | |||||
.Bd -literal | |||||
typedef int (*gzio_cb)(void *base, size_t len, off_t off, void *arg); | |||||
.Ed | |||||
.Pp | |||||
.Ft struct gzio_stream * | |||||
.Fn gzio_init "gzio_cb cb" "enum gzio_mode mode" "size_t bufsz" "int level" "void *arg" | |||||
.Ft int | |||||
.Fn gzio_write "struct gzio_stream *s" "void *data" "u_int len" | |||||
.Ft int | |||||
.Fn gzio_flush "struct gzio_stream *s" | |||||
.Ft void | |||||
.Fn gzio_fini "struct gzio_stream *s" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm | |||||
interface is a simple wrapper for the zlib library. | |||||
It currently only supports compression of a data stream. | |||||
A | |||||
.Ft struct gzio_stream | |||||
stores state for the stream and is allocated and freed using | |||||
.Fn gzio_init | |||||
and | |||||
.Fn gzio_fini | |||||
respectively. | |||||
As data is written to the stream using | |||||
.Fn gzio_write , | |||||
the caller-provided callback is invoked, making the processed data available. | |||||
The callback is only invoked when the stream's internal buffer is full; to | |||||
force the processing of partially-buffered data, use | |||||
.Fn gzio_flush . | |||||
Finally, | |||||
.Fn gzio_fini | |||||
is used to free a flushed stream. | |||||
.Pp | |||||
The | |||||
.Fn gzio_init | |||||
rpaulo: The description of gzio_init should move up because: it's the first function and you just wrote… | |||||
markjAuthorUnsubmitted Not Done Inline ActionsOk. I tried to write it so that the first paragraph was a summary of all the functions, and then subsequent paragraphs described the arguments of gzio_init() and friends. It's kind of confusing though, I'll rework it. markj: Ok. I tried to write it so that the first paragraph was a summary of all the functions, and… | |||||
function allocates a new stream with callback | |||||
.Va cb , | |||||
and an internal buffer of size | |||||
.Va bufsz . | |||||
The | |||||
.Va mode | |||||
parameter must be | |||||
.Dv GZIO_DEFLATE . | |||||
The | |||||
.Va level | |||||
parameter is a zlib parameter which determines the compression level used; | |||||
valid values are 0-9 inclusive, and -1, which tells zlib to use its default | |||||
compression level. | |||||
Larger values give better compression ratios at the cost of CPU time and | |||||
memory usage. | |||||
Note that all memory needed by | |||||
.Nm | |||||
is allocated in | |||||
.Fn gzio_init . | |||||
In particular, memory will not be allocated when writing to a stream. | |||||
Finally, | |||||
.Va arg | |||||
is an opaque argument that is passed to | |||||
.Va cb . | |||||
.Fn gzio_init | |||||
will return | |||||
.Dv NULL | |||||
if an error occurs during stream initialization. | |||||
.Pp | |||||
The | |||||
.Fn gzio_write | |||||
and | |||||
.Fn gzio_flush | |||||
functions write data to be compressed to a | |||||
.Dv GZIO_DEFLATE | |||||
stream. | |||||
If the callback returns a non-zero value, these functions will return it to | |||||
the caller. | |||||
If an error occurs during compression, | |||||
.Dv EIO will be returned. | |||||
.Fn gzio_flush | |||||
should be called exactly once for a given stream. | |||||
.Sh SEE ALSO | |||||
.Xr zlib 3 , | |||||
.Xr core 5 |
The description of gzio_init should move up because: it's the first function and you just wrote "Finally" in line 67.