C wcstombs() Function – stdlib.h

wcstombs() Function

The wcstombs() function is declared in the header file <stdlib.h>.

The wcstombs() function converts a wide-character string into its corresponding multibyte string representation. This function is used when dealing with wide characters and performing locale-specific conversions, ensuring that the resulting multibyte sequence begins in the initial shift state.

---

Syntax of wcstombs()

size_t wcstombs(char *dest, const wchar_t *src, size_t max);

Parameters

Parameter	Description
dest	Pointer to an array of char elements large enough to hold the resulting multibyte sequence (up to max bytes).
src	Pointer to the wide-character string to be converted.
max	Maximum number of bytes to write to dest.

Note that if exactly max bytes are converted without encountering a null wide-character, the resulting multibyte string stored in dest will not be null-terminated. The behavior of wcstombs() depends on the LC_CTYPE category of the current C locale, which influences the interpretation of wide characters.

---

Return Value

The function returns the number of bytes written to dest, not including the terminating null character (if one is written). If an invalid wide character is encountered during conversion, wcstombs() returns (size_t)-1.

---

Examples for wcstombs()

Example 1: Basic Conversion from Wide-Character String to Multibyte String

This example demonstrates a straightforward conversion of a wide-character string to its multibyte equivalent.

Program

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    wchar_t wstr[] = L"Hello, World!";
    char mbs[50];
    size_t bytesConverted;

    bytesConverted = wcstombs(mbs, wstr, sizeof(mbs));
    if (bytesConverted == (size_t)-1) {
        printf("Conversion error occurred.\n");
    } else {
        printf("Converted multibyte string: %s\n", mbs);
        printf("Number of bytes converted: %zu\n", bytesConverted);
    }
    return 0;
}

Explanation:

1. A wide-character string wstr is defined with the content L”Hello, World!”.
2. An array mbs is allocated to store the resulting multibyte string.
3. The wcstombs() function converts wstr into a multibyte string, storing the result in mbs.
4. The program checks if the conversion was successful and prints the converted string along with the number of bytes converted.

Program Output:

Converted multibyte string: Hello, World!
Number of bytes converted: 13

Example 2: Conversion with Limited Buffer Size

This example shows how wcstombs() behaves when the maximum number of bytes specified is smaller than the full length of the converted string. Note that the resulting string may not be null-terminated.

Program

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    wchar_t wstr[] = L"Sample text for conversion";
    char mbs[10];  // Limited buffer size
    size_t bytesConverted;

    bytesConverted = wcstombs(mbs, wstr, sizeof(mbs));
    if (bytesConverted == (size_t)-1) {
        printf("Conversion error occurred.\n");
    } else {
        // Manually null-terminate if space allows
        if (bytesConverted < sizeof(mbs))
            mbs[bytesConverted] = '\0';
        else
            mbs[sizeof(mbs) - 1] = '\0';

        printf("Converted multibyte string: %s\n", mbs);
        printf("Number of bytes converted: %zu\n", bytesConverted);
    }
    return 0;
}

Explanation:

1. The wide-character string wstr is defined with a longer text.
2. An array mbs with a limited size of 10 bytes is used to store the converted string.
3. wcstombs() converts the wide-character string, but only up to 10 bytes are written.
4. A manual null termination is performed to ensure the string is properly terminated if space permits.
5. The program prints the truncated multibyte string and the number of bytes that were converted.

Program Output:

Converted multibyte string: Sample te
Number of bytes converted: 10

Example 3: Handling Conversion Error with Invalid Wide Character

This example illustrates error handling in wcstombs() when an invalid wide character is encountered during conversion.

Program

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main() {
    // Example wide-character string containing an invalid sequence (for demonstration purposes)
    wchar_t wstr[] = { L'H', L'e', L'l', L'l', L'o', 0xFFFF, L'!', L'\0' };
    char mbs[50];
    size_t bytesConverted;

    bytesConverted = wcstombs(mbs, wstr, sizeof(mbs));
    if (bytesConverted == (size_t)-1) {
        printf("Conversion error: Invalid wide character encountered.\n");
    } else {
        printf("Converted multibyte string: %s\n", mbs);
        printf("Number of bytes converted: %zu\n", bytesConverted);
    }
    return 0;
}

Explanation:

1. A wide-character string wstr is defined containing a deliberately invalid wide character (0xFFFF) to simulate a conversion error.
2. The wcstombs() function attempts to convert the string into a multibyte sequence.
3. If an invalid wide character is encountered, the function returns (size_t)-1 to signal an error.
4. The program checks for this error and prints an appropriate error message.

Program Output:

Conversion error: Invalid wide character encountered.