doc/unistdio.texi

   1 @node unistdio.h
   2 @chapter Output with Unicode strings @code{<unistdio.h>}
   3
   4 @cindex formatted output
   5 @cindex output, formatted
   6 This include file declares functions for doing formatted output with Unicode
   7 strings.  It defines a set of functions similar to @code{fprintf} and
   8 @code{sprintf}, which are declared in @code{<stdio.h>}.
   9
  10 These functions work like the @code{printf} function family.
  11 In the format string:
  12 @itemize
  13 @item
  14 The format directive @samp{U} takes an UTF-8 string (@code{const uint8_t *}).
  15 @item
  16 The format directive @samp{lU} takes an UTF-16 string
  17 (@code{const uint16_t *}).
  18 @item
  19 The format directive @samp{llU} takes an UTF-32 string
  20 (@code{const uint32_t *}).
  21 @end itemize
  22
  23 A function name with an infix @samp{v} indicates that a @code{va_list} is
  24 passed instead of multiple arguments.
  25
  26 The functions @code{*sprintf} have a @var{buf} argument that is assumed to be
  27 large enough.
  28 (@emph{DANGEROUS!  Overflowing the buffer will crash the program.})
  29
  30 The functions @code{*snprintf} have a @var{buf} argument that is assumed to be
  31 @var{size} units large.  (@emph{DANGEROUS!  The resulting string might be
  32 truncated in the middle of a multibyte character.})
  33
  34 The functions @code{*asprintf} have a @var{resultp} argument.  The result will
  35 be freshly allocated and stored in @code{*resultp}.
  36
  37 The functions @code{*asnprintf} have a (@var{resultbuf}, @var{lengthp})
  38 argument pair.  If @var{resultbuf} is not NULL and the result fits into
  39 @code{*@var{lengthp}} units, it is put in @var{resultbuf}, and @var{resultbuf}
  40 is returned.  Otherwise, a freshly allocated string is returned.  In both
  41 cases, @code{*@var{lengthp}} is set to the length (number of units) of the
  42 returned string.  In case of error, NULL is returned and @code{errno} is set.
  43
  44 The following functions take an ASCII format string and return a result that
  45 is a @code{char *} string in locale encoding.
  46
  47 @deftypefun int ulc_sprintf (char *@var{buf}, const char *@var{format}, ...)
  48 @end deftypefun
  49
  50 @deftypefun int ulc_snprintf (char *@var{buf}, size_t size, const char *@var{format}, ...)
  51 @end deftypefun
  52
  53 @deftypefun int ulc_asprintf (char **@var{resultp}, const char *@var{format}, ...)
  54 @end deftypefun
  55
  56 @deftypefun {char *} ulc_asnprintf (char *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
  57 @end deftypefun
  58
  59 @deftypefun int ulc_vsprintf (char *@var{buf}, const char *@var{format}, va_list @var{ap})
  60 @end deftypefun
  61
  62 @deftypefun int ulc_vsnprintf (char *@var{buf}, size_t size, const char *@var{format}, va_list @var{ap})
  63 @end deftypefun
  64
  65 @deftypefun int ulc_vasprintf (char **@var{resultp}, const char *@var{format}, va_list @var{ap})
  66 @end deftypefun
  67
  68 @deftypefun {char *} ulc_vasnprintf (char *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, va_list @var{ap})
  69 @end deftypefun
  70
  71 The following functions take an ASCII format string and return a result in
  72 UTF-8 format.
  73
  74 @deftypefun int u8_sprintf (uint8_t *@var{buf}, const char *@var{format}, ...)
  75 @end deftypefun
  76 @deftypefun int u8_snprintf (uint8_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
  77 @end deftypefun
  78 @deftypefun int u8_asprintf (uint8_t **@var{resultp}, const char *@var{format}, ...)
  79 @end deftypefun
  80 @deftypefun {uint8_t *} u8_asnprintf (uint8_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
  81 @end deftypefun
  82 @deftypefun int u8_vsprintf (uint8_t *@var{buf}, const char *@var{format}, va_list ap)
  83 @end deftypefun
  84 @deftypefun int u8_vsnprintf (uint8_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
  85 @end deftypefun
  86 @deftypefun int u8_vasprintf (uint8_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
  87 @end deftypefun
  88 @deftypefun {uint8_t *} u8_vasnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @var{ap})
  89 @end deftypefun
  90
  91 The following functions take an UTF-8 format string and return a result in
  92 UTF-8 format.
  93
  94 @deftypefun int u8_u8_sprintf (uint8_t *@var{buf}, const uint8_t *@var{format}, ...)
  95 @end deftypefun
  96 @deftypefun int u8_u8_snprintf (uint8_t *@var{buf}, size_t @var{size}, const uint8_t *@var{format}, ...)
  97 @end deftypefun
  98 @deftypefun int u8_u8_asprintf (uint8_t **@var{resultp}, const uint8_t *@var{format}, ...)
  99 @end deftypefun
 100 @deftypefun {uint8_t *} u8_u8_asnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const uint8_t *@var{format}, ...)
 101 @end deftypefun
 102 @deftypefun int u8_u8_vsprintf (uint8_t *@var{buf}, const uint8_t *@var{format}, va_list @var{ap})
 103 @end deftypefun
 104 @deftypefun int u8_u8_vsnprintf (uint8_t *@var{buf}, size_t @var{size}, const uint8_t *@var{format}, va_list @var{ap})
 105 @end deftypefun
 106 @deftypefun int u8_u8_vasprintf (uint8_t **@var{resultp}, const uint8_t *@var{format}, va_list @var{ap})
 107 @end deftypefun
 108 @deftypefun {uint8_t *} u8_u8_vasnprintf (uint8_t *resultbuf, size_t *@var{lengthp}, const uint8_t *@var{format}, va_list @var{ap})
 109 @end deftypefun
 110
 111 The following functions take an ASCII format string and return a result in
 112 UTF-16 format.
 113
 114 @deftypefun int u16_sprintf (uint16_t *@var{buf}, const char *@var{format}, ...)
 115 @end deftypefun
 116 @deftypefun int u16_snprintf (uint16_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
 117 @end deftypefun
 118 @deftypefun int u16_asprintf (uint16_t **@var{resultp}, const char *@var{format}, ...)
 119 @end deftypefun
 120 @deftypefun {uint16_t *} u16_asnprintf (uint16_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
 121 @end deftypefun
 122 @deftypefun int u16_vsprintf (uint16_t *@var{buf}, const char *@var{format}, va_list ap)
 123 @end deftypefun
 124 @deftypefun int u16_vsnprintf (uint16_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
 125 @end deftypefun
 126 @deftypefun int u16_vasprintf (uint16_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
 127 @end deftypefun
 128 @deftypefun {uint16_t *} u16_vasnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @var{ap})
 129 @end deftypefun
 130
 131 The following functions take an UTF-16 format string and return a result in
 132 UTF-16 format.
 133
 134 @deftypefun int u16_u16_sprintf (uint16_t *@var{buf}, const uint16_t *@var{format}, ...)
 135 @end deftypefun
 136 @deftypefun int u16_u16_snprintf (uint16_t *@var{buf}, size_t @var{size}, const uint16_t *@var{format}, ...)
 137 @end deftypefun
 138 @deftypefun int u16_u16_asprintf (uint16_t **@var{resultp}, const uint16_t *@var{format}, ...)
 139 @end deftypefun
 140 @deftypefun {uint16_t *} u16_u16_asnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const uint16_t *@var{format}, ...)
 141 @end deftypefun
 142 @deftypefun int u16_u16_vsprintf (uint16_t *@var{buf}, const uint16_t *@var{format}, va_list @var{ap})
 143 @end deftypefun
 144 @deftypefun int u16_u16_vsnprintf (uint16_t *@var{buf}, size_t @var{size}, const uint16_t *@var{format}, va_list @var{ap})
 145 @end deftypefun
 146 @deftypefun int u16_u16_vasprintf (uint16_t **@var{resultp}, const uint16_t *@var{format}, va_list @var{ap})
 147 @end deftypefun
 148 @deftypefun {uint16_t *} u16_u16_vasnprintf (uint16_t *resultbuf, size_t *@var{lengthp}, const uint16_t *@var{format}, va_list @var{ap})
 149 @end deftypefun
 150
 151 The following functions take an ASCII format string and return a result in
 152 UTF-32 format.
 153
 154 @deftypefun int u32_sprintf (uint32_t *@var{buf}, const char *@var{format}, ...)
 155 @end deftypefun
 156 @deftypefun int u32_snprintf (uint32_t *@var{buf}, size_t @var{size}, const char *@var{format}, ...)
 157 @end deftypefun
 158 @deftypefun int u32_asprintf (uint32_t **@var{resultp}, const char *@var{format}, ...)
 159 @end deftypefun
 160 @deftypefun {uint32_t *} u32_asnprintf (uint32_t *@var{resultbuf}, size_t *@var{lengthp}, const char *@var{format}, ...)
 161 @end deftypefun
 162 @deftypefun int u32_vsprintf (uint32_t *@var{buf}, const char *@var{format}, va_list ap)
 163 @end deftypefun
 164 @deftypefun int u32_vsnprintf (uint32_t *@var{buf}, size_t @var{size}, const char *@var{format}, va_list @var{ap})
 165 @end deftypefun
 166 @deftypefun int u32_vasprintf (uint32_t **@var{resultp}, const char *@var{format}, va_list @var{ap})
 167 @end deftypefun
 168 @deftypefun {uint32_t *} u32_vasnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const char *@var{format}, va_list @var{ap})
 169 @end deftypefun
 170
 171 The following functions take an UTF-32 format string and return a result in
 172 UTF-32 format.
 173
 174 @deftypefun int u32_u32_sprintf (uint32_t *@var{buf}, const uint32_t *@var{format}, ...)
 175 @end deftypefun
 176 @deftypefun int u32_u32_snprintf (uint32_t *@var{buf}, size_t @var{size}, const uint32_t *@var{format}, ...)
 177 @end deftypefun
 178 @deftypefun int u32_u32_asprintf (uint32_t **@var{resultp}, const uint32_t *@var{format}, ...)
 179 @end deftypefun
 180 @deftypefun {uint32_t *} u32_u32_asnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const uint32_t *@var{format}, ...)
 181 @end deftypefun
 182 @deftypefun int u32_u32_vsprintf (uint32_t *@var{buf}, const uint32_t *@var{format}, va_list @var{ap})
 183 @end deftypefun
 184 @deftypefun int u32_u32_vsnprintf (uint32_t *@var{buf}, size_t @var{size}, const uint32_t *@var{format}, va_list @var{ap})
 185 @end deftypefun
 186 @deftypefun int u32_u32_vasprintf (uint32_t **@var{resultp}, const uint32_t *@var{format}, va_list @var{ap})
 187 @end deftypefun
 188 @deftypefun {uint32_t *} u32_u32_vasnprintf (uint32_t *resultbuf, size_t *@var{lengthp}, const uint32_t *@var{format}, va_list @var{ap})
 189 @end deftypefun
 190
 191 The following functions take an ASCII format string and produce output in
 192 locale encoding to a @code{FILE} stream.
 193
 194 @deftypefun int ulc_fprintf (FILE *@var{stream}, const char *@var{format}, ...)
 195 @end deftypefun
 196 @deftypefun int ulc_vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
 197 @end deftypefun