@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 @bullet
@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@tie{}*@var{buf}, const@tie{}char@tie{}*@var{format}, ...)
@end deftypefun

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

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

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

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

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

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

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