diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -65,6 +65,7 @@ cd.9 \ cdefs.9 \ cnv.9 \ + compressor.9 \ condvar.9 \ config_intrhook.9 \ contigmalloc.9 \ @@ -879,6 +880,13 @@ cnv.9 cnvlist_take_nvlist_array.9 \ cnv.9 cnvlist_take_string.9 \ cnv.9 cnvlist_take_string_array.9 +MLINKS+=compressor.9 compressor_avail.9 \ + compressor.9 compressor_fini.9 \ + compressor.9 compressor_flush.9 \ + compressor.9 compressor_format.9 \ + compressor.9 compressor_init.9 \ + compressor.9 compressor_reset.9 \ + compressor.9 compressor_write.9 MLINKS+=condvar.9 cv_broadcast.9 \ condvar.9 cv_broadcastpri.9 \ condvar.9 cv_destroy.9 \ diff --git a/share/man/man9/compressor.9 b/share/man/man9/compressor.9 new file mode 100644 --- /dev/null +++ b/share/man/man9/compressor.9 @@ -0,0 +1,160 @@ +.\" +.\" Copyright (c) 2025 Kyle Evans +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd July 26, 2025 +.Dt COMPRESSOR 9 +.Os +.Sh NAME +.Nm compressor , +.Nm compressor_avail , +.Nm compressor_fini , +.Nm compressor_flush , +.Nm compressor_format , +.Nm compressor_init , +.Nm compressor_reset , +.Nm compressor_write +.Nd kernel compression API +.Sh SYNOPSIS +.In sys/compressor.h +.Bd -literal +#define COMPRESS_GZIP 1 +#define COMPRESS_ZSTD 2 + +typedef int (*compressor_cb_t)(void *, size_t, off_t, void *); +.Ed +.Pp +.Ft bool +.Fn compressor_avail "int format" +.Ft "struct compressor *" +.Fn compressor_init "compressor_cb_t cb" "int format" "size_t maxiosize" \ + "int level" "void *arg" +.Ft int +.Fn compressor_format "const struct compressor *stream" +.Ft void +.Fn compressor_reset "void" +.Ft int +.Fn compressor_write "struct compressor *stream" "void *data" "size_t len" +.Ft int +.Fn compressor_flush "struct compressor *stream" +.Ft int +.Fn compressor_fini "struct compressor *stream" +.Sh DESCRIPTION +The +.Nm +API provides a uniform streaming interface to the different compression +algorithms offered by the kernel. +The following compression formats may be available for use: +.Bl -tag -width indent +.It COMPRESS_GZIP +Gzip support may be enabled with +.Dq "options GZIO" +in the kernel +.Xr config 5 . +Gzip support is provided by +.Xr zlib 3 . +.Pp +This compression format is enabled by default in the +.Pa GENERIC +kernel. +.It COMPRESS_ZSTD +Zstd support may be enabled with +.Dq "options ZSTDIO" +in the kernel +.Xr config 5 . +.Pp +This compression format is enabled by default in the +.Pa GENERIC +kernel. +.El +.Pp +Despite a format's presence in +.Pa GENERIC , +.Nm +consumers should not assume the presence of any particular compression format. +The +.Fn compressor_avail +function may be used to check the availability of the desired format. +.Pp +The +.Fn compressor_init +function is used to initialize and obtain a compressor handle, a +.Vt "struct compressor *" . +The +.Fa cb +supplied will receive as arguments the compressed buffer, the length of data +available, the offset into the output stream, and the opaque handle that the +caller has passed to +.Fn compressor_init . +.Pp +The +.Fa format +must be one of the +.Dv COMPRESS +constants described above. +The +.Fa maxiosize +specifies the maximum output buffer size, and the +.Fa level +argument defines the compression level, as understood by the compression format +chosen. +.Pp +.Fn compressor_init +may fail and return NULL if the requested +.Fa format +is not available, or if initialization of the compression context fails. +Note that +.Fn compressor_init +may sleep to allocate memory. +.Pp +The +.Fn compressor_format +call extracts the above +.Dv COMPRESS +constant associated with this compressor handle. +.Pp +The +.Fn compressor_reset +function resets the underlying compression stream state. +.Pp +The +.Fn compressor_write +function writes compressed data into the stream. +Passing a +.Dv NULL +.Fa data +argument will flush the underlying stream, but use of +.Fn compressor_flush +is recommended instead. +Data will be written to the +.Fa cb +that was passed to +.Fn compressor_init +as it becomes available. +Returns 0 on success, or an +.Xr errno 2 +on failure. +.Pp +The +.Fn compressor_flush +function flushes the underlying stream. +Returns 0 on success, or an +.Xr errno 2 +on failure. +.Pp +The +.Fn compressor_fini +frees the compressor handle. +The underlying stream will not be flushed, the caller is responsible for doing +so if desired. +.Pp +Note that the +.Nm +interface is suitable for use after a panic, with the notable exception that +.Fn compressor_init +would not be able to allocate memory and must not be used. +.Sh SEE ALSO +.Xr errno 2 , +.Xr zlib 3 , +.Xr config 5