XAMBSTOWCS(3) BSD Programmer's Manual XAMBSTOWCS(3)
NAME
xambsntowcs, xambstowcs, xawcsntombs, xawcstombs - convert between multi-
byte and wide strings with checked allocation
SYNOPSIS
#include <mbfun.h>
wchar_t *
xambsntowcs(const char *s, size_t n);
wchar_t *
xambstowcs(const char *s);
char *
xawcsntombs(const wchar_t *s, size_t n);
char *
xawcstombs(const wchar_t *s);
DESCRIPTION
The xambsntowcs() and xambstowcs() functions convert the NUL-terminated
multibyte (MirOS OPTU-8 encoded) string s into a wide (MirOS OPTU-16
encoded) string, requesting just enough storage via calloc(3) from the
system to store the result, including a terminating WNUL character. The
xawcsntombs() and xawcstombs() functions convert the WNUL-terminated wide
(MirOS OPTU-16 encoded) string s into a multibyte (MirOS OPTU-8 encoded)
string, requesting just enough storage via malloc(3) from the system to
store the result, including a terminating NUL byte. The xambsntowcs() and
xawcsntombs() functions convert at most n characters; the xambstowcs()
and xawcstombs() functions convert the entire string.
RETURN VALUES
xambsntowcs() and xambstowcs() return the newly allocated wide character
string. xawcsntombs() and xawcstombs() return the newly allocated multi-
byte character string. Failure to allocate enough memory will terminate
the calling program, xmalloc style, with errorlevel 1 and an appropriate
error message. Passing a NULL pointer results in undefined behaviour.
SEE ALSO
mbsrtowcs(3), wcsrtombs(3)
HISTORY
The xambsntowcs, xambstowcs, xawcsntombs, and xawcstombs functions are
MirBSD BSD extensions and first appeared in MirBSD #11.
AUTHORS
Thorsten Glaser <tg@mirbsd.de> wrote the entire internationalisation im-
plementation in MirBSD. He is also the steward for the OPTU encoding.
CAVEATS
These functions were originally introduced without the leading 'x' but
renamed because they abort on memory allocation error, which is not suit-
able for a library. Eventually, the unprefixed versions shall be returned
to this library which will then return NULL on memory allocation error.
Future directions include switching to 21-bit UCS without notice.
MirBSD #10-current July 7, 2021 1