X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/d23763dae4f649cc29a923298e0232ffdf608744..98ff9295493ed2b990f30768e11b18b6bc65eaa4:/struct/buf.3.in

diff --git a/struct/buf.3.in b/struct/buf.3.in
index f3c2e7f..6a3a68c 100644
--- a/struct/buf.3.in
+++ b/struct/buf.3.in
@@ -77,8 +77,10 @@
 .\" @dbuf_put
 .\" @dbuf_fill
 .
+.\" @buf_align
 .\" @buf_alignskip
 .\" @buf_alignfill
+.\" @dbuf_align
 .\" @dbuf_alignskip
 .\" @dbuf_alignfill
 .
@@ -545,6 +547,7 @@ and taking a first argument of type
 .BI "int buf_put(buf *" b ", const void *" p ", size_t " sz );
 .BI "int buf_fill(buf *" b ", int " ch ", size_t " sz );
 .PP
+.BI "int buf_align(buf *" b ", size_t " m ", size_t " a ", size_t *" sz_out );
 .BI "int buf_alignskip(buf *" b ", size_t " m ", size_t " a );
 .BI "int buf_alignfill(buf *" b ", int " ch ", size_t " m ", size_t " a );
 .PP
@@ -850,16 +853,33 @@ to the buffer, as if by calling
 If it succeeds, it returns 0; otherwise it returns \-1.
 .PP
 The
-.B buf_alignskip
-function advances the buffer's position as little as possible,
+.B buf_align
+function tries to advance the buffer's position as little as possible,
 so as to cause the position to be
 .I a
 bytes more than a multiple of
-.IR m .
-If
+.IR m ;
+if
 .I m
-is zero then nothing is done.
-The buffer contents are not altered.
+is zero then no change is needed.
+If the buffer is broken, then
+.B buf_align
+immediately returns null.
+Otherwise, it sets
+.BI * sz_out
+to the number of bytes \(en possibly zero \(en
+by which the position would have to advance
+in order to achieve the requested alignment.
+If there is sufficient space remaining in the buffer,
+then the current position is advanced,
+and the old position is returned;
+otherwise, the buffer is broken and a null pointer is returned.
+The
+.B buf_alignskip
+function
+simply advances the buffer position
+until the designed alignment is achieved:
+the buffer contents are not altered.
 The related
 .B buf_alignfill
 function is similar, except that it advances the buffer position by writing
@@ -867,11 +887,17 @@ copies of the byte
 .IR ch ,
 as if by calling
 .BR memset (3).
-Use
+These functions return zero on success,
+or \-1 if the buffer lacked enough space
+or was already broken.
+Usually, it's best to use
 .B buf_alignskip
 for input and
 .B buf_alignfill
 for output.
+The primitive
+.B buf_align
+function can be used for either.
 .
 .SS "Formatted buffer access"
 The function