c('Sfprintf')

Availability:C-language interface function

int Sfprintf(IOSTREAM *s, const char *fm, ...)

Similar to POSIX fprintf(). This function largely accepts the same % escape sequences. The % character is followed by numeric arguments and modifier characters. The generic format of this is described by the regular expression [+-0 #]*(\d*|\*)(.(\d*|\*))?. Here, + implies right alignment, - left alignment, 0 0-padding and, a space white-space padding and # modified output. The two optional numerical arguments are separated by a full stop and may be * to get them from the argument list. The first numerical argument specifies the field width and the second the precision for floating point numbers.

This sequence is followed by optional type information. For integers this is one of l (long), ll (long long) or z (size_t). For strings this is one of L (ISO Latin 1), U (UTF-8) or W (wchar_t*).

Finally we come to the format specifier. This is one of

%
Emit the % character itself.

c
Emit a Unicode code point.

p
Emit a pointer.

d

i
Emit a a signed integer as decimal. The l (long), ll (long long) or z (size_t) denote the size.

o

u

x

X
Emit a a unsigned integer as octal, decimal or hexadecimal.

f

e

E

g

G
Emit a double.

s
Emit a 0-terminated string.

Unlike the POSIX fprintf(), this function, and the related functions (Svprintf(), etc.) returns the number of characters written. Due to multibyte encodings the number of bytes written can be more. On error, it returns a negative value; in some cases there is extra information (e.g., in errno) but it cannot be relied on.

Each call to Sfprintf() is atomic in the sense that another thread that calls Sfprintf() on the same stream will block. If you wish to do a series of print statements without any other thread interleaving, you should call PL_acquire_stream() and use its returned IOSTREAM* value, then call PL_release_stream() at the end of the print statements.