MirBSD manpage: xambsntowcs(3), xambstowcs(3), xawcsntombs(3), xawcstombs(3)

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