1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> 2<html> 3<!-- Created on March, 19 2013 by texi2html 1.78a --> 4<!-- 5Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) 6 Karl Berry <karl@freefriends.org> 7 Olaf Bachmann <obachman@mathematik.uni-kl.de> 8 and many others. 9Maintained by: Many creative people. 10Send bugs and suggestions to <texi2html-bug@nongnu.org> 11 12--> 13<head> 14<title>GNU libunistring: 6. Output with Unicode strings <unistdio.h></title> 15 16<meta name="description" content="GNU libunistring: 6. Output with Unicode strings <unistdio.h>"> 17<meta name="keywords" content="GNU libunistring: 6. Output with Unicode strings <unistdio.h>"> 18<meta name="resource-type" content="document"> 19<meta name="distribution" content="global"> 20<meta name="Generator" content="texi2html 1.78a"> 21<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 22<style type="text/css"> 23<!-- 24a.summary-letter {text-decoration: none} 25pre.display {font-family: serif} 26pre.format {font-family: serif} 27pre.menu-comment {font-family: serif} 28pre.menu-preformatted {font-family: serif} 29pre.smalldisplay {font-family: serif; font-size: smaller} 30pre.smallexample {font-size: smaller} 31pre.smallformat {font-family: serif; font-size: smaller} 32pre.smalllisp {font-size: smaller} 33span.roman {font-family:serif; font-weight:normal;} 34span.sansserif {font-family:sans-serif; font-weight:normal;} 35ul.toc {list-style: none} 36--> 37</style> 38 39 40</head> 41 42<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 43 44<table cellpadding="1" cellspacing="1" border="0"> 45<tr><td valign="middle" align="left">[<a href="libunistring_5.html#SEC17" title="Beginning of this chapter or previous chapter"> << </a>]</td> 46<td valign="middle" align="left">[<a href="libunistring_7.html#SEC19" title="Next chapter"> >> </a>]</td> 47<td valign="middle" align="left"> </td> 48<td valign="middle" align="left"> </td> 49<td valign="middle" align="left"> </td> 50<td valign="middle" align="left"> </td> 51<td valign="middle" align="left"> </td> 52<td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> 53<td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td> 54<td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td> 55<td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td> 56</tr></table> 57 58<hr size="2"> 59<a name="unistdio_002eh"></a> 60<a name="SEC18"></a> 61<h1 class="chapter"> <a href="libunistring.html#TOC18">6. Output with Unicode strings <code><unistdio.h></code></a> </h1> 62 63<p>This include file declares functions for doing formatted output with Unicode 64strings. It defines a set of functions similar to <code>fprintf</code> and 65<code>sprintf</code>, which are declared in <code><stdio.h></code>. 66</p> 67<p>These functions work like the <code>printf</code> function family. 68In the format string: 69</p><ul class="toc"> 70<li> 71The format directive ‘<samp>U</samp>’ takes an UTF-8 string (<code>const uint8_t *</code>). 72</li><li> 73The format directive ‘<samp>lU</samp>’ takes an UTF-16 string 74(<code>const uint16_t *</code>). 75</li><li> 76The format directive ‘<samp>llU</samp>’ takes an UTF-32 string 77(<code>const uint32_t *</code>). 78</li></ul> 79 80<p>A function name with an infix ‘<samp>v</samp>’ indicates that a <code>va_list</code> is 81passed instead of multiple arguments. 82</p> 83<p>The functions <code>*sprintf</code> have a <var>buf</var> argument that is assumed to be 84large enough. 85(<em>DANGEROUS! Overflowing the buffer will crash the program.</em>) 86</p> 87<p>The functions <code>*snprintf</code> have a <var>buf</var> argument that is assumed to be 88<var>size</var> units large. (<em>DANGEROUS! The resulting string might be 89truncated in the middle of a multibyte character.</em>) 90</p> 91<p>The functions <code>*asprintf</code> have a <var>resultp</var> argument. The result will 92be freshly allocated and stored in <code>*resultp</code>. 93</p> 94<p>The functions <code>*asnprintf</code> have a (<var>resultbuf</var>, <var>lengthp</var>) 95argument pair. If <var>resultbuf</var> is not NULL and the result fits into 96<code>*<var>lengthp</var></code> units, it is put in <var>resultbuf</var>, and <var>resultbuf</var> 97is returned. Otherwise, a freshly allocated string is returned. In both 98cases, <code>*<var>lengthp</var></code> is set to the length (number of units) of the 99returned string. In case of error, NULL is returned and <code>errno</code> is set. 100</p> 101<p>The following functions take an ASCII format string and return a result that 102is a <code>char *</code> string in locale encoding. 103</p> 104<dl> 105<dt><u>Function:</u> int <b>ulc_sprintf</b><i> (char *<var>buf</var>, const char *<var>format</var>, ...)</i> 106<a name="IDX179"></a> 107</dt> 108</dl> 109 110<dl> 111<dt><u>Function:</u> int <b>ulc_snprintf</b><i> (char *<var>buf</var>, size_t size, const char *<var>format</var>, ...)</i> 112<a name="IDX180"></a> 113</dt> 114</dl> 115 116<dl> 117<dt><u>Function:</u> int <b>ulc_asprintf</b><i> (char **<var>resultp</var>, const char *<var>format</var>, ...)</i> 118<a name="IDX181"></a> 119</dt> 120</dl> 121 122<dl> 123<dt><u>Function:</u> char * <b>ulc_asnprintf</b><i> (char *<var>resultbuf</var>, size_t *<var>lengthp</var>, const char *<var>format</var>, ...)</i> 124<a name="IDX182"></a> 125</dt> 126</dl> 127 128<dl> 129<dt><u>Function:</u> int <b>ulc_vsprintf</b><i> (char *<var>buf</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 130<a name="IDX183"></a> 131</dt> 132</dl> 133 134<dl> 135<dt><u>Function:</u> int <b>ulc_vsnprintf</b><i> (char *<var>buf</var>, size_t size, const char *<var>format</var>, va_list <var>ap</var>)</i> 136<a name="IDX184"></a> 137</dt> 138</dl> 139 140<dl> 141<dt><u>Function:</u> int <b>ulc_vasprintf</b><i> (char **<var>resultp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 142<a name="IDX185"></a> 143</dt> 144</dl> 145 146<dl> 147<dt><u>Function:</u> char * <b>ulc_vasnprintf</b><i> (char *<var>resultbuf</var>, size_t *<var>lengthp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 148<a name="IDX186"></a> 149</dt> 150</dl> 151 152<p>The following functions take an ASCII format string and return a result in 153UTF-8 format. 154</p> 155<dl> 156<dt><u>Function:</u> int <b>u8_sprintf</b><i> (uint8_t *<var>buf</var>, const char *<var>format</var>, ...)</i> 157<a name="IDX187"></a> 158</dt> 159</dl> 160<dl> 161<dt><u>Function:</u> int <b>u8_snprintf</b><i> (uint8_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, ...)</i> 162<a name="IDX188"></a> 163</dt> 164</dl> 165<dl> 166<dt><u>Function:</u> int <b>u8_asprintf</b><i> (uint8_t **<var>resultp</var>, const char *<var>format</var>, ...)</i> 167<a name="IDX189"></a> 168</dt> 169</dl> 170<dl> 171<dt><u>Function:</u> uint8_t * <b>u8_asnprintf</b><i> (uint8_t *<var>resultbuf</var>, size_t *<var>lengthp</var>, const char *<var>format</var>, ...)</i> 172<a name="IDX190"></a> 173</dt> 174</dl> 175<dl> 176<dt><u>Function:</u> int <b>u8_vsprintf</b><i> (uint8_t *<var>buf</var>, const char *<var>format</var>, va_list ap)</i> 177<a name="IDX191"></a> 178</dt> 179</dl> 180<dl> 181<dt><u>Function:</u> int <b>u8_vsnprintf</b><i> (uint8_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 182<a name="IDX192"></a> 183</dt> 184</dl> 185<dl> 186<dt><u>Function:</u> int <b>u8_vasprintf</b><i> (uint8_t **<var>resultp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 187<a name="IDX193"></a> 188</dt> 189</dl> 190<dl> 191<dt><u>Function:</u> uint8_t * <b>u8_vasnprintf</b><i> (uint8_t *resultbuf, size_t *<var>lengthp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 192<a name="IDX194"></a> 193</dt> 194</dl> 195 196<p>The following functions take an UTF-8 format string and return a result in 197UTF-8 format. 198</p> 199<dl> 200<dt><u>Function:</u> int <b>u8_u8_sprintf</b><i> (uint8_t *<var>buf</var>, const uint8_t *<var>format</var>, ...)</i> 201<a name="IDX195"></a> 202</dt> 203</dl> 204<dl> 205<dt><u>Function:</u> int <b>u8_u8_snprintf</b><i> (uint8_t *<var>buf</var>, size_t <var>size</var>, const uint8_t *<var>format</var>, ...)</i> 206<a name="IDX196"></a> 207</dt> 208</dl> 209<dl> 210<dt><u>Function:</u> int <b>u8_u8_asprintf</b><i> (uint8_t **<var>resultp</var>, const uint8_t *<var>format</var>, ...)</i> 211<a name="IDX197"></a> 212</dt> 213</dl> 214<dl> 215<dt><u>Function:</u> uint8_t * <b>u8_u8_asnprintf</b><i> (uint8_t *resultbuf, size_t *<var>lengthp</var>, const uint8_t *<var>format</var>, ...)</i> 216<a name="IDX198"></a> 217</dt> 218</dl> 219<dl> 220<dt><u>Function:</u> int <b>u8_u8_vsprintf</b><i> (uint8_t *<var>buf</var>, const uint8_t *<var>format</var>, va_list <var>ap</var>)</i> 221<a name="IDX199"></a> 222</dt> 223</dl> 224<dl> 225<dt><u>Function:</u> int <b>u8_u8_vsnprintf</b><i> (uint8_t *<var>buf</var>, size_t <var>size</var>, const uint8_t *<var>format</var>, va_list <var>ap</var>)</i> 226<a name="IDX200"></a> 227</dt> 228</dl> 229<dl> 230<dt><u>Function:</u> int <b>u8_u8_vasprintf</b><i> (uint8_t **<var>resultp</var>, const uint8_t *<var>format</var>, va_list <var>ap</var>)</i> 231<a name="IDX201"></a> 232</dt> 233</dl> 234<dl> 235<dt><u>Function:</u> uint8_t * <b>u8_u8_vasnprintf</b><i> (uint8_t *resultbuf, size_t *<var>lengthp</var>, const uint8_t *<var>format</var>, va_list <var>ap</var>)</i> 236<a name="IDX202"></a> 237</dt> 238</dl> 239 240<p>The following functions take an ASCII format string and return a result in 241UTF-16 format. 242</p> 243<dl> 244<dt><u>Function:</u> int <b>u16_sprintf</b><i> (uint16_t *<var>buf</var>, const char *<var>format</var>, ...)</i> 245<a name="IDX203"></a> 246</dt> 247</dl> 248<dl> 249<dt><u>Function:</u> int <b>u16_snprintf</b><i> (uint16_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, ...)</i> 250<a name="IDX204"></a> 251</dt> 252</dl> 253<dl> 254<dt><u>Function:</u> int <b>u16_asprintf</b><i> (uint16_t **<var>resultp</var>, const char *<var>format</var>, ...)</i> 255<a name="IDX205"></a> 256</dt> 257</dl> 258<dl> 259<dt><u>Function:</u> uint16_t * <b>u16_asnprintf</b><i> (uint16_t *<var>resultbuf</var>, size_t *<var>lengthp</var>, const char *<var>format</var>, ...)</i> 260<a name="IDX206"></a> 261</dt> 262</dl> 263<dl> 264<dt><u>Function:</u> int <b>u16_vsprintf</b><i> (uint16_t *<var>buf</var>, const char *<var>format</var>, va_list ap)</i> 265<a name="IDX207"></a> 266</dt> 267</dl> 268<dl> 269<dt><u>Function:</u> int <b>u16_vsnprintf</b><i> (uint16_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 270<a name="IDX208"></a> 271</dt> 272</dl> 273<dl> 274<dt><u>Function:</u> int <b>u16_vasprintf</b><i> (uint16_t **<var>resultp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 275<a name="IDX209"></a> 276</dt> 277</dl> 278<dl> 279<dt><u>Function:</u> uint16_t * <b>u16_vasnprintf</b><i> (uint16_t *resultbuf, size_t *<var>lengthp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 280<a name="IDX210"></a> 281</dt> 282</dl> 283 284<p>The following functions take an UTF-16 format string and return a result in 285UTF-16 format. 286</p> 287<dl> 288<dt><u>Function:</u> int <b>u16_u16_sprintf</b><i> (uint16_t *<var>buf</var>, const uint16_t *<var>format</var>, ...)</i> 289<a name="IDX211"></a> 290</dt> 291</dl> 292<dl> 293<dt><u>Function:</u> int <b>u16_u16_snprintf</b><i> (uint16_t *<var>buf</var>, size_t <var>size</var>, const uint16_t *<var>format</var>, ...)</i> 294<a name="IDX212"></a> 295</dt> 296</dl> 297<dl> 298<dt><u>Function:</u> int <b>u16_u16_asprintf</b><i> (uint16_t **<var>resultp</var>, const uint16_t *<var>format</var>, ...)</i> 299<a name="IDX213"></a> 300</dt> 301</dl> 302<dl> 303<dt><u>Function:</u> uint16_t * <b>u16_u16_asnprintf</b><i> (uint16_t *resultbuf, size_t *<var>lengthp</var>, const uint16_t *<var>format</var>, ...)</i> 304<a name="IDX214"></a> 305</dt> 306</dl> 307<dl> 308<dt><u>Function:</u> int <b>u16_u16_vsprintf</b><i> (uint16_t *<var>buf</var>, const uint16_t *<var>format</var>, va_list <var>ap</var>)</i> 309<a name="IDX215"></a> 310</dt> 311</dl> 312<dl> 313<dt><u>Function:</u> int <b>u16_u16_vsnprintf</b><i> (uint16_t *<var>buf</var>, size_t <var>size</var>, const uint16_t *<var>format</var>, va_list <var>ap</var>)</i> 314<a name="IDX216"></a> 315</dt> 316</dl> 317<dl> 318<dt><u>Function:</u> int <b>u16_u16_vasprintf</b><i> (uint16_t **<var>resultp</var>, const uint16_t *<var>format</var>, va_list <var>ap</var>)</i> 319<a name="IDX217"></a> 320</dt> 321</dl> 322<dl> 323<dt><u>Function:</u> uint16_t * <b>u16_u16_vasnprintf</b><i> (uint16_t *resultbuf, size_t *<var>lengthp</var>, const uint16_t *<var>format</var>, va_list <var>ap</var>)</i> 324<a name="IDX218"></a> 325</dt> 326</dl> 327 328<p>The following functions take an ASCII format string and return a result in 329UTF-32 format. 330</p> 331<dl> 332<dt><u>Function:</u> int <b>u32_sprintf</b><i> (uint32_t *<var>buf</var>, const char *<var>format</var>, ...)</i> 333<a name="IDX219"></a> 334</dt> 335</dl> 336<dl> 337<dt><u>Function:</u> int <b>u32_snprintf</b><i> (uint32_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, ...)</i> 338<a name="IDX220"></a> 339</dt> 340</dl> 341<dl> 342<dt><u>Function:</u> int <b>u32_asprintf</b><i> (uint32_t **<var>resultp</var>, const char *<var>format</var>, ...)</i> 343<a name="IDX221"></a> 344</dt> 345</dl> 346<dl> 347<dt><u>Function:</u> uint32_t * <b>u32_asnprintf</b><i> (uint32_t *<var>resultbuf</var>, size_t *<var>lengthp</var>, const char *<var>format</var>, ...)</i> 348<a name="IDX222"></a> 349</dt> 350</dl> 351<dl> 352<dt><u>Function:</u> int <b>u32_vsprintf</b><i> (uint32_t *<var>buf</var>, const char *<var>format</var>, va_list ap)</i> 353<a name="IDX223"></a> 354</dt> 355</dl> 356<dl> 357<dt><u>Function:</u> int <b>u32_vsnprintf</b><i> (uint32_t *<var>buf</var>, size_t <var>size</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 358<a name="IDX224"></a> 359</dt> 360</dl> 361<dl> 362<dt><u>Function:</u> int <b>u32_vasprintf</b><i> (uint32_t **<var>resultp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 363<a name="IDX225"></a> 364</dt> 365</dl> 366<dl> 367<dt><u>Function:</u> uint32_t * <b>u32_vasnprintf</b><i> (uint32_t *resultbuf, size_t *<var>lengthp</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 368<a name="IDX226"></a> 369</dt> 370</dl> 371 372<p>The following functions take an UTF-32 format string and return a result in 373UTF-32 format. 374</p> 375<dl> 376<dt><u>Function:</u> int <b>u32_u32_sprintf</b><i> (uint32_t *<var>buf</var>, const uint32_t *<var>format</var>, ...)</i> 377<a name="IDX227"></a> 378</dt> 379</dl> 380<dl> 381<dt><u>Function:</u> int <b>u32_u32_snprintf</b><i> (uint32_t *<var>buf</var>, size_t <var>size</var>, const uint32_t *<var>format</var>, ...)</i> 382<a name="IDX228"></a> 383</dt> 384</dl> 385<dl> 386<dt><u>Function:</u> int <b>u32_u32_asprintf</b><i> (uint32_t **<var>resultp</var>, const uint32_t *<var>format</var>, ...)</i> 387<a name="IDX229"></a> 388</dt> 389</dl> 390<dl> 391<dt><u>Function:</u> uint32_t * <b>u32_u32_asnprintf</b><i> (uint32_t *resultbuf, size_t *<var>lengthp</var>, const uint32_t *<var>format</var>, ...)</i> 392<a name="IDX230"></a> 393</dt> 394</dl> 395<dl> 396<dt><u>Function:</u> int <b>u32_u32_vsprintf</b><i> (uint32_t *<var>buf</var>, const uint32_t *<var>format</var>, va_list <var>ap</var>)</i> 397<a name="IDX231"></a> 398</dt> 399</dl> 400<dl> 401<dt><u>Function:</u> int <b>u32_u32_vsnprintf</b><i> (uint32_t *<var>buf</var>, size_t <var>size</var>, const uint32_t *<var>format</var>, va_list <var>ap</var>)</i> 402<a name="IDX232"></a> 403</dt> 404</dl> 405<dl> 406<dt><u>Function:</u> int <b>u32_u32_vasprintf</b><i> (uint32_t **<var>resultp</var>, const uint32_t *<var>format</var>, va_list <var>ap</var>)</i> 407<a name="IDX233"></a> 408</dt> 409</dl> 410<dl> 411<dt><u>Function:</u> uint32_t * <b>u32_u32_vasnprintf</b><i> (uint32_t *resultbuf, size_t *<var>lengthp</var>, const uint32_t *<var>format</var>, va_list <var>ap</var>)</i> 412<a name="IDX234"></a> 413</dt> 414</dl> 415 416<p>The following functions take an ASCII format string and produce output in 417locale encoding to a <code>FILE</code> stream. 418</p> 419<dl> 420<dt><u>Function:</u> int <b>ulc_fprintf</b><i> (FILE *<var>stream</var>, const char *<var>format</var>, ...)</i> 421<a name="IDX235"></a> 422</dt> 423</dl> 424<dl> 425<dt><u>Function:</u> int <b>ulc_vfprintf</b><i> (FILE *<var>stream</var>, const char *<var>format</var>, va_list <var>ap</var>)</i> 426<a name="IDX236"></a> 427</dt> 428</dl> 429<hr size="6"> 430<table cellpadding="1" cellspacing="1" border="0"> 431<tr><td valign="middle" align="left">[<a href="libunistring_5.html#SEC17" title="Beginning of this chapter or previous chapter"> << </a>]</td> 432<td valign="middle" align="left">[<a href="libunistring_7.html#SEC19" title="Next chapter"> >> </a>]</td> 433<td valign="middle" align="left"> </td> 434<td valign="middle" align="left"> </td> 435<td valign="middle" align="left"> </td> 436<td valign="middle" align="left"> </td> 437<td valign="middle" align="left"> </td> 438<td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> 439<td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td> 440<td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td> 441<td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td> 442</tr></table> 443<p> 444 <font size="-1"> 445 This document was generated on <i>March, 19 2013</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78a</i></a>. 446 </font> 447 <br> 448 449</p> 450</body> 451</html> 452