C Standard Library wchar.h

What You’ll Learn

Most C text uses char strings. <wchar.h> adds wide characters (wchar_t) and functions parallel to string.h—wcslen instead of strlen, wprintf instead of printf. Wide strings help on Windows and in programs that must handle larger character sets than a single byte allows.

Definition and Usage

A wide string is an array of wchar_t ending with a null wide character. The L prefix creates wide literals: L"Hello". Functions mirror narrow string.h names with a w prefix or wcs infix.

wchar.h also converts between multibyte char strings (locale-dependent encoding) and wchar_t strings. Set the locale with setlocale from <locale.h> before conversion when handling non-ASCII text.

📝 Syntax

Include the header:

#include <wchar.h>

Types and macros

• wchar_t — wide character type (typedef in <stddef.h>)
• wint_t — can hold any wchar_t value or WEOF
• mbstate_t — conversion state for restartable multibyte functions
• WEOF — wide end-of-file indicator
• NULL — null pointer constant

Wide string functions (parallel to string.h)

• wcslen, wcscpy, wcsncpy, wcscat, wcsncat
• wcscmp, wcsncmp, wcschr, wcsstr
• wcspbrk, wcstok — tokenization (like strtok)

Conversion and I/O

• mbstowcs(dest, src, n) — multibyte char string to wide
• wcstombs(dest, src, n) — wide string to multibyte char
• wprintf, fwprintf, swprintf — wide formatted output
• wscanf, fgetws, fputws — wide input/output
• wcsftime — wide version of strftime from <time.h>

Typical wide string

wchar_t greeting[] = L"Hello";
size_t n = wcslen(greeting);
wprintf(L"Text: %ls (len %zu)\n", greeting, n);

Headers and linking

• #include <wchar.h> — often needs <stdio.h> for wprintf.
• #include <locale.h> for setlocale before mbstowcs/wcstombs.
• Compile: gcc program.c -std=c11 -o program.

Examples Gallery

Compile with gcc file.c -std=c11 -o program. Wide output may require a terminal that supports Unicode.

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

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

    setlocale(LC_ALL, "");

    wprintf(L"Wide string: %ls\n", wstr);
    wprintf(L"Length (wcslen): %zu\n", wcslen(wstr));

    converted = wcstombs(mbs, wstr, sizeof(mbs));
    if (converted == (size_t)(-1)) {
        fprintf(stderr, "wcstombs failed\n");
        return 1;
    }
    mbs[converted] = '\0';
    printf("Multibyte string: %s\n", mbs);

    return 0;
}

Wide string: Hello, World!
Length (wcslen): 13
Multibyte string: Hello, World!

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

int main(void) {
    wchar_t buf[32] = L"Hello, ";
    const wchar_t *name = L"Ada";

    wcscat(buf, name);
    wprintf(L"Greeting: %ls\n", buf);
    wprintf(L"Total length: %zu\n", wcslen(buf));

    return 0;
}

Greeting: Hello, Ada
Total length: 10

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

int main(void) {
    const char *narrow = "Cafe";
    wchar_t wide[32];
    size_t n;

    setlocale(LC_ALL, "");

    n = mbstowcs(wide, narrow, 32);
    if (n == (size_t)(-1)) {
        fprintf(stderr, "mbstowcs failed\n");
        return 1;
    }
    wide[n] = L'\0';

    wprintf(L"Wide: %ls (%zu chars)\n", wide, wcslen(wide));

    return 0;
}

Wide: Cafe (4 chars)

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

int main(void) {
    wchar_t path[] = L"C:\\Users\\Ada\\file.txt";
    wchar_t *slash;

    slash = wcschr(path, L'\\');
    while (slash != NULL) {
        wprintf(L"Backslash at index %td\n", slash - path);
        slash = wcschr(slash + 1, L'\\');
    }

    wchar_t *dot = wcsrchr(path, L'.');
    if (dot != NULL) {
        wprintf(L"Extension: %ls\n", dot);
    }

    return 0;
}

Backslash at index 2
Backslash at index 8
Backslash at index 12
Extension: .txt

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

int main(void) {
    const wchar_t *cmd = L"quit";
    wchar_t input[16] = L"quit";

    if (wcscmp(input, cmd) == 0) {
        wprintf(L"Command matched: exiting.\n");
    } else if (wcsncmp(input, L"help", 4) == 0) {
        wprintf(L"Help requested.\n");
    } else {
        wprintf(L"Unknown command: %ls\n", input);
    }

    return 0;
}

Command matched: exiting.

🚀 Common Use Cases

• Windows APIs — many functions take LPCWSTR wide strings.
• Internationalized CLI — messages in multiple scripts via wide I/O.
• File paths — Unicode paths on Windows with wide APIs.
• Bridging encodings — mbstowcs/wcstombs at system boundaries.
• Wide config files — read with fgetws, parse with wcstol.
• Localized dates — wcsftime with <time.h>.

📝 Notes

• sizeof(wchar_t) is 2 on many Windows builds, 4 on many Linux builds.
• wchar_t encoding is implementation-defined—not a portable Unicode type.
• iswalpha/towlower are in <wctype.h>, not wchar.h.
• wcstombs/mbstowcs return (size_t)-1 on invalid sequences.
• Wide strings must be null-terminated with L'\\0'.
• Modern cross-platform code often prefers UTF-8 char strings instead of wchar_t.

⚡ Optimization

Wide strings use more memory per character than UTF-8 ASCII text. Convert once at boundaries rather than per character in hot loops. If you only need ASCII, narrow strings are simpler and faster. Profile before adopting wide strings throughout a codebase.

💡 Best Practices