Page MenuHomeFreeBSD
Files F153681310

D51562.id159204.diff
No OneTemporary
Actions

D51562.id159204.diff
View Options

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 <kevans@FreeBSD.org>
+.\"
+.\" 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

File Metadata

Mime Type
text/plain
Expires
Thu, Apr 23, 9:29 PM (6 h, 33 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
32045759
Default Alt Text
D51562.id159204.diff (4 KB)

Event Timeline