document deflateUsed()

text mostly from upstream, the function will soon be added to libz.

ok jmc

diff --git a/lib/libz/compress.3 b/lib/libz/compress.3
index b5d1e74..18a8ac1 100644 (file)
--- a/lib/libz/compress.3
+++ b/lib/libz/compress.3
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: compress.3,v 1.30 2024/07/25 17:25:59 tb Exp $
+.\"    $OpenBSD: compress.3,v 1.31 2024/07/25 17:29:51 tb Exp $
 .\"
 .\"  Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler
 .\"
@@ -42,6 +42,7 @@
 .Nm deflateTune ,
 .Nm deflateBound ,
 .Nm deflatePending ,
+.Nm deflateUsed ,
 .Nm deflatePrime ,
 .Nm deflateSetHeader ,
 .Nm inflateInit2 ,
@@ -138,6 +139,8 @@ Advanced functions
 .Ft int
 .Fn deflatePending "z_streamp strm" "unsigned *pending" "int *bits"
 .Ft int
+.Fn deflateUsed "z_streamp strm" "int *bits"
+.Ft int
 .Fn deflatePrime "z_streamp strm" "int bits" "int value"
 .Ft int
 .Fn deflateSetHeader "z_streamp strm" "gz_headerp head"
@@ -1516,6 +1519,25 @@ if success, or
 if the source stream state was inconsistent.
 .It Xo
 .Fa int
+.Fn deflateUsed "z_streamp strm" "int *bits" ;
+.Xc
+.Pp
+.Fn deflateUsed
+returns in
+.Pf * Fa bits
+the most recent number of deflate bits used in the last byte
+when flushing to a byte boundary.
+The result is in the range 1..8, or 0 if there has not yet been a flush.
+This helps determine the location of the last bit of a deflate stream.
+.Pp
+.Fn deflateUsed
+returns
+.Dv Z_OK
+if success, or
+.Dv Z_STREAM_ERROR
+if the source stream state was inconsistent.
+.It Xo
+.Fa int
 .Fn deflatePrime "z_streamp strm" "int bits" "int value" ;
 .Xc
 .Pp