]> pd.if.org Git - pdclib/blob - man3/_cbprintf.3
flushbuffer: make EOL conversion code more robust against I/O errors
[pdclib] / man3 / _cbprintf.3
1 .\" This file is part of the Public Domain C Library (PDCLib).
2 .\" Permission is granted to use, modify, and / or redistribute at will.
3 .\"
4 .Dd
5 .Dt _CBPRINTF 3
6 .Os
7 .\"
8 .Sh NAME
9 .Nm _cbprintf ,
10 .Nm _vcbprintf ,
11 .Nm _cbwprintf ,
12 .Nm _vcbwprintf
13 .Nd formatted output conversion by callback
14 .\"
15 .Sh SYNOPSIS
16 .In stdio.h
17 .Fn "int _cbprintf"   "void *p" "size_t (*cb)(void *p, const char    *buf, size_t size)" "const char *fmt" "..."
18 .Fn "int _vcbprintf"  "void *p" "size_t (*cb)(void *p, const char    *buf, size_t size)" "const char *fmt" "va_list ap"
19 .Pp
20 .In wchar.h
21 .Fn "int _cbwprintf"  "void *p" "size_t (*cb)(void *p, const wchar_t *buf, size_t size)" "const wchar_t *fmt" "..."
22 .Fn "int _vcbwprintf" "void *p" "size_t (*cb)(void *p, const wchar_t *buf, size_t size)" "const wchar_t *fmt" "va_list ap"
23 .\"
24 .Sh DESCRIPTION
25 These functions permit the
26 .Fn printf
27 string formatting functionality to be reused outside the C standard library,
28 without the limitation of using the
29 .Fn sprintf
30 function for this process, that the whole formatted string must exist in memory
31 at once.
32 .Pp
33 .\"
34 These functions shall exhibit the same behaviour and conversion specifiers as
35 the
36 .Xr printf 3
37 function, except they shall perform their output by calling the
38 .Fa cb
39 callback, passing the characters to be output as the
40 .Fa buf
41 parameter, and the count of such characters as
42 .Fa size .
43 .Pp
44 .\"
45 The implementation is permitted to invoke
46 .Fa cb
47 with a non-zero number of characters as many times as it deems necessary
48 necessary. That is, the implementation may decide to call it only once it has
49 finished conversion of the entire string, or it may call it multiple times as it
50 incrementally performs a conversion (it would be legal for an implementation to
51 invoke the callback for every character produced).
52 .Pp
53 .\"
54 During all invocations, the callback will be passed as
55 .Fa p
56 the same value as was passed to the function.
57 .Pp
58 .\"
59 The callback shall return
60 .Fa size
61 on success, or any other value on failure
62 .\"
63 .Sh RETURN VALUES
64 The functions shall return the number of characters produced by the conversion
65 on success, or a negative number on failure. If the number of characters
66 converted exceeds
67 .Dv INT_MAX ,
68 then
69 .Dv INT_MAX
70 shall be returned.
71 .\"
72 .Sh EXAMPLES
73 Using
74 .Fn _vcbprintf
75 to reimplement printf
76 .Bd -literal -offset indent
77 static size_t do_output(void *p, const char *buf, size_t size)
78 {
79     return fwrite(buf, 1, size, (FILE *) p);
80 }
81
82 int myprintf(const char *fmt, ...)
83 {
84     va_list ap;
85     va_start(ap, fmt);
86     return _vcbprintf(stdout, do_output, ap);
87     va_end(ap);
88 }
89 .Ed
90 .\"
91 .Sh ERRORS
92 This function shall not affect errno, however the callbacks it invokes may
93 .\"
94 .Sh SEE ALSO
95 .Xr printf 3
96 .\"
97 .Sh RATIONALE
98 Sensible implementations of the ISO C standard library implement an analogous
99 system internally, permitting them to share their implementation of formatting
100 between
101 .Xr printf 3
102 and
103 .Xr sprintf 3 .
104 Therefore, implementing a callback based variant is not of substantial
105 complexity.
106 .Pp
107 These functions permit the reuse of this functionality by applications and
108 libraries (for example, a logging library) without the need to reimplement it,
109 and without the aforementioned memory limitation imposed by
110 .Xr sprintf 3 .
111 .\"
112 .Sh HISTORY
113 This nonstandard extension was first defined by PDCLib.