htpf() - printf with HTML extensions

SYNOPSIS

#include "cgi.h"

int  htpf(fmt, ...)
int  htfpf(fp, fmt, ...)
int  htvfpf(fp, fmt, argp)
int  htspf(buf, fmt, ...)
int  htvspf(buf, fmt, argp)
int  htsnpf(buf, sz, fmt, ...)
int  htvsnpf(buf, sz, fmt, argp)

const char *fmt;
char       *buf;
FILE       *fp;
va_list     argp;
size_t      sz;

DESCRIPTION
The htpf() family of functions provide the same functionality as the corresponding printf() functions, with some additional features. A format string fmt is printed, with %-escape codes indicating what type the arguments are and how they should be printed. All of the following standard % codes are recognized: %d, %i, %u, %x, %X, %o, %c, %s, %e, %f, %g, %p, and %n, along with the usual flags for width, precision, etc.

The htpf(), htfpf(), and htvfpf() functions print to a file pointed to by fp (stdout in the case of htpf()). The htspf(), htvspf(), htsnpf(), and htvsnpf() functions print to a string buffer pointed to by buf, and '\0'-terminate the string. In the case of htsnpf() and htvsnpf(), sz indicates the size of the buffer (including the ending '\0'), which will not be written past; the other string functions assume the buffer is large enough.

All the functions return the total number of characters printed, or EOF on file error (for the file-printing variants). htsnpf() and htvsnpf() return the total number of characters, even if the buffer is too small: the extra characters are not printed but are included in the returned count. The output string is always '\0'-terminated (if sz is greater than 0); the final '\0' is not counted in the return count.

The additional % codes recognized by the htpf() family are:

• %b for binary output of an int

• %r for lowercase Roman numeral output

• %R for capital Roman numeral output

• %t for strftime()-style output of a time_t

• %T for GMT (Universal Time) output of a time_t

• %U for string output with URL escapement

• %H for string output with HTML escapement

All the standard flags, where applicable, can be given to these codes as well.

The %t and %T codes take a time_t parameter (e.g. like that returned by time()) and print it according to a strftime() format string: the default is like ctime() (without the newline). If the a flag is given, then the strftime() format string is taken to be the next argument (before the time_t). %T is like %t but prints by default in GMT (Universal Time).

The %U code takes a string (char *) parameter and prints it, applying URL escape codes where needed to make the string "safe" in a URL. The %H code is similar, but escapes for HTML (e.g. replacing < with < etc.).