From 6a148103bee3eadc306623038e11ecbe9d3cf99b Mon Sep 17 00:00:00 2001 From: Ken Hornstein Date: Wed, 13 Nov 2013 20:54:22 -0500 Subject: [PATCH 1/1] Document snprintb() a bit. --- h/prototypes.h | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) 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 + * + * 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 *); -- 2.48.1