.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated Tue Jan 11 00:56:04 JST 2000
.\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\"
.TH MBSTOWCS 3 2020\-11\-01 GNU "Linux Programmer's Manual"
.SH 名前
mbstowcs \- マルチバイト文字列をワイド文字列に変換する
.SH 書式
.nf
\fB#include <stdlib.h>\fP
.PP
\fBsize_t mbstowcs(wchar_t *\fP\fIdest\fP\fB, const char *\fP\fIsrc\fP\fB, size_t \fP\fIn\fP\fB);\fP
.fi
.SH 説明
If \fIdest\fP is not NULL, the \fBmbstowcs\fP()  function converts the multibyte
string \fIsrc\fP to a wide\-character string starting at \fIdest\fP.  At most \fIn\fP
wide characters are written to \fIdest\fP.  The sequence of characters in the
string \fIsrc\fP shall begin in the initial shift state.  The conversion can
stop for three reasons:
.IP 1. 3
不正なマルチバイト列に遭遇した。この場合には \fI(size_t)\ \-1\fP を返す。
.IP 2.
\fIn\fP 文字の L\(aq\e0\(aq 以外のワイド文字を \fIdest\fP に格納した場合。 この場合は \fI*src\fP
が次に変換されるマルチバイト列を指すようにして、 \fIdest\fP に書き込まれたワイド文字の数を返す。しかしこの指している 場所のシフト状態は失われる。
.IP 3.
マルチバイト文字列が終端のヌル文字 (\(aq\e0\(aq) まで含めて完全に変換された場合。この場合は終端のヌルワイド文字を除いて \fIdest\fP
に書き込まれた文字数を返す。
.PP
プログラマーは \fIdest\fP に最低でも \fIn\fP ワイド文字を書き込むこ とができる空間があることを保証しなければならない。
.PP
\fIdest\fP が NULL の場合、\fIn\fP は無視され、上記と同様の変換が 行われるが、変換されたワイド文字はメモリーに書き込まれず、変換先の上限
が存在しない。
.PP
上記の 2. の場合を避けるためにプログラマーは \fIn\fP が \fImbstowcs(NULL,src,0)+1\fP 以上であることを保証すべきである。
.SH 返り値
\fBmbstowcs\fP()  関数はワイド文字列に変換完了したワイド文字の数を返す。
終端のヌルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には \fI(size_t)\ \-1\fP を返す。
.SH 属性
この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
.TS
allbox;
lb lb lb
l l l.
インターフェース	属性	値
T{
\fBmbstowcs\fP()
T}	Thread safety	MT\-Safe
.TE
.SH 準拠
POSIX.1\-2001, POSIX.1\-2008, C99.
.SH 注意
\fBmbstowcs\fP()  の動作は現在のロケールの \fBLC_CTYPE\fP カテゴリーに依存している。
.PP
\fBmbsrtowcs\fP(3)  関数は同じ機能のより良いインターフェースを提供する。
.SH 例
下記のプログラムは \fBmbstowcs\fP() といくつかのワイド文字分類関数の使用方法を示したものである。実行例は以下のようになる。
.PP
.in +4n
.EX
$ ./t_mbstowcs de_DE.UTF\-8 Grüße!
Length of source string (excluding terminator):
    8 bytes
    6 multibyte characters

Wide character string is: Grüße! (6 characters)
    G alpha upper
    r alpha lower
    ü alpha lower
    ß alpha lower
    e alpha lower
    ! !alpha
.EE
.in
.SS プログラムのソース
\&
.EX
#include <wctype.h>
#include <locale.h>
#include <wchar.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

int
main(int argc, char *argv[])
{
    size_t mbslen;      /* Number of multibyte characters in source */
    wchar_t *wcs;       /* Pointer to converted wide character string */

    if (argc < 3) {
        fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]);
        exit(EXIT_FAILURE);
    }

    /* Apply the specified locale */

    if (setlocale(LC_ALL, argv[1]) == NULL) {
        perror("setlocale");
        exit(EXIT_FAILURE);
    }

    /* Calculate the length required to hold argv[2] converted to
       a wide character string */

    mbslen = mbstowcs(NULL, argv[2], 0);
    if (mbslen == (size_t) \-1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    /* Describe the source string to the user */

    printf("Length of source string (excluding terminator):\en");
    printf("    %zu bytes\en", strlen(argv[2]));
    printf("    %zu multibyte characters\en\en", mbslen);

    /* Allocate wide character string of the desired size.  Add 1
       to allow for terminating null wide character (L\(aq\e0\(aq). */

    wcs = calloc(mbslen + 1, sizeof(*wcs));
    if (wcs == NULL) {
        perror("calloc");
        exit(EXIT_FAILURE);
    }

    /* Convert the multibyte character string in argv[2] to a
       wide character string */

    if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    printf("Wide character string is: %ls (%zu characters)\en",
            wcs, mbslen);

    /* Now do some inspection of the classes of the characters in
       the wide character string */

    for (wchar_t *wp = wcs; *wp != 0; wp++) {
        printf("    %lc ", (wint_t) *wp);

        if (!iswalpha(*wp))
            printf("!");
        printf("alpha ");

        if (iswalpha(*wp)) {
            if (iswupper(*wp))
                printf("upper ");

            if (iswlower(*wp))
                printf("lower ");
        }

        putchar(\(aq\en\(aq);
    }

    exit(EXIT_SUCCESS);
}
.EE
.SH 関連項目
\fBmblen\fP(3), \fBmbsrtowcs\fP(3), \fBmbtowc\fP(3), \fBwcstombs\fP(3), \fBwctomb\fP(3)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。