From: Ken Hornstein <kenh@pobox.com>
Date: Thu, 14 Nov 2013 01:54:22 +0000 (-0500)
Subject: Document snprintb() a bit.
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/6a148103bee3eadc306623038e11ecbe9d3cf99b?ds=inline;hp=b271b4c2bb0bafebace4e86180adb68d66730fad

Document snprintb() a bit.
---

diff --git a/h/prototypes.h b/h/prototypes.h
index 0df91b1d..b1a53cde 100644
--- a/h/prototypes.h
+++ b/h/prototypes.h
@@ -186,7 +186,40 @@ void seq_setprev (struct msgs *);
 void seq_setunseen (struct msgs *, int);
 int showfile (char **, char *);
 int smatch(char *, struct swit *);
-char *snprintb (char *, size_t, unsigned, char *);
+
+/*
+ * Convert a set of bit flags to printable format.
+ *
+ * Arguments:
+ *
+ * buffer	- Buffer to output string to.
+ * size		- Size of buffer in bytes.  Buffer is always NUL terminated.
+ * flags	- Binary flags to output
+ * bitfield	- Textual representation of bits to output.  This string
+ *		  is in the following format:
+ *
+ *	Option byte 0x01 STRING1 0x02 STRING2 ....
+ *
+ * The first byte is an option byte to snprintb().  Currently the only option
+ * supported is 0x08, which indicates that the flags should be output in
+ * octal format; if the option byte is any other value, the flags will be
+ * output in hexadecimal.
+ *
+ * After the option bytes are series of text strings, prefixed by the number
+ * of the bit they correspond to.  For example, the bitfield string:
+ *
+ *	"\020\01FLAG1\02FLAG2\03FLAG3\04FLAG4"
+ *
+ * will output the following string if "flags" is set to 0x09:
+ *
+ *	0x2<FLAG1,FLAG4>
+ *
+ * You don't have to use octal in the bitfield string, that's just the
+ * convention currently used by the nmh code.  The order of flags in the
+ * bitfield string is not significant, but again, general convention is
+ * from least significant bit to most significant.
+ */
+char *snprintb (char *buffer, size_t size, unsigned flags, char *bitfield);
 int ssequal (char *, char *);
 int stringdex (char *, char *);
 char *trimcpy (char *);