CLEANUP: slz: clarify that the size promise applies to the stream, not to a call

The output size guarantee of slz_rfc1951_encode() reads as if it applied
to every call, but up to 31 bits are retained in the queue from one call
to the next (on 64-bit systems), so a call may emit a few bytes that
belong to the data of the previous ones, and a single call may emit up to
5 bytes more than expected. Let's just clarify this to avoid future
surprises.

It should be backported to 1.2 for API clarity.

This is libslz upstream commit 5fa0c8da22b7d0a6d67f287a5a2af6af8e6d2b85.

Note: no impact on running code, it's just a comment that may be backported
      if it helps with another patch's context.

diff --git a/src/slz.c b/src/slz.c
index 564e146c8465162d8d30b70b62e5c4e436a45c12..8478e554c612f623f7624264b55dcfe3c7707c83 100644 (file)
--- a/src/slz.c
+++ b/src/slz.c
@@ -540,9 +540,12 @@ static void reset_refs(union ref *refs, long count)
 /* Compresses <ilen> bytes from <in> into <out> according to RFC1951. The
  * output result may be up to 5 bytes larger than the input for each 65535
  * nput bytes, to which 2 extra bytes may be added to send the last chunk due
- * to BFINAL+EOB encoding (10 bits) when <more> is not set. The caller is
- * responsible for ensuring there is enough room in the output buffer for this.
- * The amount of output bytes is returned, and no CRC is computed.
+ * to BFINAL+EOB encoding (10 bits) when <more> is not set. This is a property
+ * of the whole stream, not of each call: since up to 31 bits are retained in
+ * the queue from one call to the next, a single call may emit up to 5 bytes
+ * more than its own share, which the following ones will not emit. The caller
+ * is responsible for ensuring there is enough room in the output buffer for
+ * this. The amount of output bytes is returned, and no CRC is computed.
  */
 long slz_rfc1951_encode(struct slz_stream *strm, unsigned char *out, const unsigned char *in, long ilen, int more)
 {