summaryrefslogtreecommitdiff
path: root/doc/unistdio.texi
blob: e1fb9cfa41cf3884c19cfefa2e1367cfaa0aa5d3 (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
@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
@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 *}).
@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 *@var{buf}, const char *@var{format}, ...)
@end deftypefun

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

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

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

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

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

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

@deftypefun {char *} ulc_vasnprintf (char *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, va_list @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 *@var{buf}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u8_snprintf (uint8_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u8_asprintf (uint8_t **@var{resultp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun {uint8_t *} u8_asnprintf (uint8_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u8_vsprintf (uint8_t *@var{buf}, const char *@var{format}, va_list ap)
@end deftypefun
@deftypefun int u8_vsnprintf (uint8_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u8_vasprintf (uint8_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint8_t *} u8_vasnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @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 *@var{buf}, const uint8_t *@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_snprintf (uint8_t *@var{buf}, size_t @var{size}, const uint8_t *@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_asprintf (uint8_t **@var{resultp}, const uint8_t *@var{format}, ...)
@end deftypefun
@deftypefun {uint8_t *} u8_u8_asnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const uint8_t *@var{format}, ...)
@end deftypefun
@deftypefun int u8_u8_vsprintf (uint8_t *@var{buf}, const uint8_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u8_u8_vsnprintf (uint8_t *@var{buf}, size_t @var{size}, const uint8_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u8_u8_vasprintf (uint8_t **@var{resultp}, const uint8_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint8_t *} u8_u8_vasnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const uint8_t *@var{format}, va_list @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 *@var{buf}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u16_snprintf (uint16_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u16_asprintf (uint16_t **@var{resultp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun {uint16_t *} u16_asnprintf (uint16_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u16_vsprintf (uint16_t *@var{buf}, const char *@var{format}, va_list ap)
@end deftypefun
@deftypefun int u16_vsnprintf (uint16_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u16_vasprintf (uint16_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint16_t *} u16_vasnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @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 *@var{buf}, const uint16_t *@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_snprintf (uint16_t *@var{buf}, size_t @var{size}, const uint16_t *@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_asprintf (uint16_t **@var{resultp}, const uint16_t *@var{format}, ...)
@end deftypefun
@deftypefun {uint16_t *} u16_u16_asnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const uint16_t *@var{format}, ...)
@end deftypefun
@deftypefun int u16_u16_vsprintf (uint16_t *@var{buf}, const uint16_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u16_u16_vsnprintf (uint16_t *@var{buf}, size_t @var{size}, const uint16_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u16_u16_vasprintf (uint16_t **@var{resultp}, const uint16_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint16_t *} u16_u16_vasnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const uint16_t *@var{format}, va_list @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 *@var{buf}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u32_snprintf (uint32_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u32_asprintf (uint32_t **@var{resultp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun {uint32_t *} u32_asnprintf (uint32_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int u32_vsprintf (uint32_t *@var{buf}, const char *@var{format}, va_list ap)
@end deftypefun
@deftypefun int u32_vsnprintf (uint32_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u32_vasprintf (uint32_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint32_t *} u32_vasnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @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 *@var{buf}, const uint32_t *@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_snprintf (uint32_t *@var{buf}, size_t @var{size}, const uint32_t *@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_asprintf (uint32_t **@var{resultp}, const uint32_t *@var{format}, ...)
@end deftypefun
@deftypefun {uint32_t *} u32_u32_asnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const uint32_t *@var{format}, ...)
@end deftypefun
@deftypefun int u32_u32_vsprintf (uint32_t *@var{buf}, const uint32_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u32_u32_vsnprintf (uint32_t *@var{buf}, size_t @var{size}, const uint32_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun int u32_u32_vasprintf (uint32_t **@var{resultp}, const uint32_t *@var{format}, va_list @var{ap})
@end deftypefun
@deftypefun {uint32_t *} u32_u32_vasnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const uint32_t *@var{format}, va_list @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 *@var{stream}, const char *@var{format}, ...)
@end deftypefun
@deftypefun int ulc_vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
@end deftypefun