@@@ mostly bench docs

[mLib] / utils / align.3.in

diff --git a/utils/align.3.in b/utils/align.3.in
index b6e2a9c..a9b9893 100644 (file)
--- a/utils/align.3.in
+++ b/utils/align.3.in
@@ -30,6 +30,7 @@
 .\"--------------------------------------------------------------------------
 .TH align 3mLib "4 January 2009" "Straylight/Edgeware" "mLib utilities library"
 .\" @ALIGN
+.\" @ALIGNOF
 .
 .\"--------------------------------------------------------------------------
 .SH NAME
@@ -41,21 +42,52 @@ align \- alignment utilities
 .nf
 .B "#include <mLib/align.h>"
 .PP
-.BI "size_t ALIGN(size_t " sz ");"
+.B "union align { ...\& };"
+.PP
+.BI "void ALIGN(size_t &" sz ");"
+.BI "size_t ALIGNOF(" type );
 .fi
 .
 .\"--------------------------------------------------------------------------
 .SH DESCRIPTION
+.
+The
+.B "union align"
+type is (a reasonable guess at) a type with the
+implementation's most restrictive alignment requirements;
+i.e., if a pointer is suitably aligned for
+.B "union align"
+value,
+then it should be suitably aligned for any other value too.
+.PP
+The
+.B ALIGNOF
+macro returns the alignment required for the given
+.IR type ;
+i.e., if an address is suitably aligned for a
+.I type
+value if and only if it is a multiple of
+.BR ALIGNOF( type ) \fR.
+.PP
 The
 .B ALIGN
-macro returns the value of its argument
+macro rounds its argument
+.I sz
+up to the next multiple of
+.BR "ALIGNOF(union align)" :
+so, if
+.I sz
+is an offset from the start of a suitably aligned chunk of memory,
+e.g., returned by
+.BR malloc (3),
+then
+.BI ALIGN( sz )
+adjusts
 .I sz
-rounded up to the next multiple of the size of
-.BR "union align" ,
-which is defined as a union containing a selection of built-in types.
-The intent is to write fairly portable memory allocators, which must
-return correctly-aligned memory.
-.IR array .
+in place, including additional padding
+so that the new offset is also suitably aligned.
+The intent is to assist with writing fairly portable memory allocators,
+which must return correctly-aligned memory.
 .
 .\"--------------------------------------------------------------------------
 .SH "SEE ALSO"