summaryrefslogtreecommitdiff
path: root/doc/unistdio.texi
blob: c4e62b1598c9c6ab666625c4655c150d1c2aaa56 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
@node unistdio.h
@chapter Output with Unicode strings @code{<unistdio.h>}

@cindex formatted output
@cindex output, formatted
This include file declares functions for doing formatted output with Unicode
strings.  It defines a set of functions similar to @code{fprintf} and
@code{sprintf}, which are declared in @code{<stdio.h>}.

These functions work like the @code{printf} function family.
In the format string:
@itemize @bullet
@item
The format directive @samp{U} takes an UTF-8 string (@code{const uint8_t *}).
@item
The format directive @samp{lU} takes an UTF-16 string
(@code{const uint16_t *}).
@item
The format directive @samp{llU} takes an UTF-32 string
(@code{const uint32_t *}).
@item
The format directive @samp{n} is not supported, for security reasons.
@end itemize

A function name with an infix @samp{v} indicates that a @code{va_list} is
passed instead of multiple arguments.

The functions @code{*sprintf} have a @var{buf} argument that is assumed to be
large enough.
(@emph{DANGEROUS!  Overflowing the buffer will crash the program.})

The functions @code{*snprintf} have a @var{buf} argument that is assumed to be
@var{size} units large.  (@emph{DANGEROUS!  The resulting string might be
truncated in the middle of a multibyte character.})

The functions @code{*asprintf} have a @var{resultp} argument.  The result will
be freshly allocated and stored in @code{*resultp}.

The functions @code{*asnprintf} have a (@var{resultbuf}, @var{lengthp})
argument pair.  If @var{resultbuf} is not NULL and the result fits into
@code{*@var{lengthp}} units, it is put in @var{resultbuf}, and @var{resultbuf}
is returned.  Otherwise, a freshly allocated string is returned.  In both
cases, @code{*@var{lengthp}} is set to the length (number of units) of the
returned string.  In case of error, NULL is returned and @code{errno} is set.

The following functions take an ASCII format string and return a result that
is a @code{char *} string in locale encoding.

@deftypefun int ulc_sprintf (char@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun

@deftypefun int ulc_snprintf (char@tie{}*@var{buf}, size_t@tie{}size, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun

@deftypefun int ulc_asprintf (char@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun

@deftypefun {char *} ulc_asnprintf (char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun

@deftypefun int ulc_vsprintf (char@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

@deftypefun int ulc_vsnprintf (char@tie{}*@var{buf}, size_t@tie{}size, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

@deftypefun int ulc_vasprintf (char@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

@deftypefun {char *} ulc_vasnprintf (char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an ASCII format string and return a result in
UTF-8 format.

@deftypefun int u8_sprintf (uint8_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_snprintf (uint8_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_asprintf (uint8_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint8_t *} u8_asnprintf (uint8_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_vsprintf (uint8_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, va_list@tie{}ap)
@end deftypefun
@deftypefun int u8_vsnprintf (uint8_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u8_vasprintf (uint8_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint8_t *} u8_vasnprintf (uint8_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an UTF-8 format string and return a result in
UTF-8 format.

@deftypefun int u8_u8_sprintf (uint8_t@tie{}*@var{buf}, const@tie{}uint8_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_snprintf (uint8_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint8_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_asprintf (uint8_t@tie{}**@var{resultp}, const@tie{}uint8_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint8_t *} u8_u8_asnprintf (uint8_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint8_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_vsprintf (uint8_t@tie{}*@var{buf}, const@tie{}uint8_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u8_u8_vsnprintf (uint8_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint8_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u8_u8_vasprintf (uint8_t@tie{}**@var{resultp}, const@tie{}uint8_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint8_t *} u8_u8_vasnprintf (uint8_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint8_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an ASCII format string and return a result in
UTF-16 format.

@deftypefun int u16_sprintf (uint16_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_snprintf (uint16_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_asprintf (uint16_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint16_t *} u16_asnprintf (uint16_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_vsprintf (uint16_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, va_list@tie{}ap)
@end deftypefun
@deftypefun int u16_vsnprintf (uint16_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u16_vasprintf (uint16_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint16_t *} u16_vasnprintf (uint16_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an UTF-16 format string and return a result in
UTF-16 format.

@deftypefun int u16_u16_sprintf (uint16_t@tie{}*@var{buf}, const@tie{}uint16_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_snprintf (uint16_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint16_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_asprintf (uint16_t@tie{}**@var{resultp}, const@tie{}uint16_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint16_t *} u16_u16_asnprintf (uint16_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint16_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_vsprintf (uint16_t@tie{}*@var{buf}, const@tie{}uint16_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u16_u16_vsnprintf (uint16_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint16_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u16_u16_vasprintf (uint16_t@tie{}**@var{resultp}, const@tie{}uint16_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint16_t *} u16_u16_vasnprintf (uint16_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint16_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an ASCII format string and return a result in
UTF-32 format.

@deftypefun int u32_sprintf (uint32_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_snprintf (uint32_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_asprintf (uint32_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint32_t *} u32_asnprintf (uint32_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_vsprintf (uint32_t@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, va_list@tie{}ap)
@end deftypefun
@deftypefun int u32_vsnprintf (uint32_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u32_vasprintf (uint32_t@tie{}**@var{resultp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint32_t *} u32_vasnprintf (uint32_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an UTF-32 format string and return a result in
UTF-32 format.

@deftypefun int u32_u32_sprintf (uint32_t@tie{}*@var{buf}, const@tie{}uint32_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_snprintf (uint32_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint32_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_asprintf (uint32_t@tie{}**@var{resultp}, const@tie{}uint32_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun {uint32_t *} u32_u32_asnprintf (uint32_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint32_t@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_vsprintf (uint32_t@tie{}*@var{buf}, const@tie{}uint32_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u32_u32_vsnprintf (uint32_t@tie{}*@var{buf}, size_t@tie{}@var{size}, const@tie{}uint32_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun int u32_u32_vasprintf (uint32_t@tie{}**@var{resultp}, const@tie{}uint32_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun
@deftypefun {uint32_t *} u32_u32_vasnprintf (uint32_t@tie{}*resultbuf, size_t@tie{}*@var{lengthp}, const@tie{}uint32_t@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun

The following functions take an ASCII format string and produce output in
locale encoding to a @code{FILE} stream.

@deftypefun int ulc_fprintf (FILE@tie{}*@var{stream}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun
@deftypefun int ulc_vfprintf (FILE@tie{}*@var{stream}, const@tie{}char@tie{}*@var{format}, va_list@tie{}@var{ap})
@end deftypefun