diff options
Diffstat (limited to 'doc/unistdio.texi')
| -rw-r--r-- | doc/unistdio.texi | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/doc/unistdio.texi b/doc/unistdio.texi new file mode 100644 index 00000000..e1fb9cfa --- /dev/null +++ b/doc/unistdio.texi @@ -0,0 +1,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 |