GNU Info

(libc.info)Non-reentrant String Conversion

---

Next: Shift State Prev: Non-reentrant Character Conversion Up: Non-reentrant Conversion

---

Enter node , (file) or (file)node

Non-reentrant Conversion of Strings
-----------------------------------

   For convenience the ISO C90 standard also defines functions to
convert entire strings instead of single characters.  These functions
suffer from the same problems as their reentrant counterparts from
Amendment 1 to ISO C90; see Note: Converting Strings.

 - Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
          size_t SIZE)
     The `mbstowcs' ("multibyte string to wide character string")
     function converts the null-terminated string of multibyte
     characters STRING to an array of wide character codes, storing not
     more than SIZE wide characters into the array beginning at WSTRING.
     The terminating null character counts towards the size, so if SIZE
     is less than the actual number of wide characters resulting from
     STRING, no terminating null character is stored.

     The conversion of characters from STRING begins in the initial
     shift state.

     If an invalid multibyte character sequence is found, the `mbstowcs'
     function returns a value of -1.  Otherwise, it returns the number
     of wide characters stored in the array WSTRING.  This number does
     not include the terminating null character, which is present if the
     number is less than SIZE.

     Here is an example showing how to convert a string of multibyte
     characters, allocating enough space for the result.

          wchar_t *
          mbstowcs_alloc (const char *string)
          {
            size_t size = strlen (string) + 1;
            wchar_t *buf = xmalloc (size * sizeof (wchar_t));
          
            size = mbstowcs (buf, string, size);
            if (size == (size_t) -1)
              return NULL;
            buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
            return buf;
          }


 - Function: size_t wcstombs (char *STRING, const wchar_t *WSTRING,
          size_t SIZE)
     The `wcstombs' ("wide character string to multibyte string")
     function converts the null-terminated wide character array WSTRING
     into a string containing multibyte characters, storing not more
     than SIZE bytes starting at STRING, followed by a terminating null
     character if there is room.  The conversion of characters begins in
     the initial shift state.

     The terminating null character counts towards the size, so if SIZE
     is less than or equal to the number of bytes needed in WSTRING, no
     terminating null character is stored.

     If a code that does not correspond to a valid multibyte character
     is found, the `wcstombs' function returns a value of -1.
     Otherwise, the return value is the number of bytes stored in the
     array STRING.  This number does not include the terminating null
     character, which is present if the number is less than SIZE.