Documentation of <unistdio.h>.

1 files changed, 195 insertions, 0 deletions

diff --git a/doc/unistdio.texi b/doc/unistdio.texi
new file mode 100644
index 0000000..42a1eee
--- /dev/null
+++ b/doc/unistdio.texi
@@ -0,0 +1,195 @@
+@node unistdio.h
+@chapter Output with Unicode strings @code{<unistdio.h>}
+
+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