draft/man3/mbstowcs.3

   1 .\" t -*- coding: UTF-8 -*-
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\" %%%LICENSE_END
  11 .\"
  12 .\" References consulted:
  13 .\"   GNU glibc-2 source code and manual
  14 .\"   Dinkumware C library reference http://www.dinkumware.com/
  15 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  16 .\"   ISO/IEC 9899:1999
  17 .\"
  18 .\"*******************************************************************
  19 .\"
  20 .\" This file was generated with po4a. Translate the source file.
  21 .\"
  22 .\"*******************************************************************
  23 .\"
  24 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  25 .\"         all rights reserved.
  26 .\" Translated Tue Jan 11 00:56:04 JST 2000
  27 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  28 .\"
  29 .TH MBSTOWCS 3 2014\-03\-18 GNU "Linux Programmer's Manual"
  30 .SH 名前
  31 mbstowcs \- マルチバイト文字列をワイド文字列に変換する
  32 .SH 書式
  33 .nf
  34 \fB#include <stdlib.h>\fP
  35 .sp
  36 \fBsize_t mbstowcs(wchar_t *\fP\fIdest\fP\fB, const char *\fP\fIsrc\fP\fB, size_t \fP\fIn\fP\fB);\fP
  37 .fi
  38 .SH 説明
  39 \fIdest\fP が NULL でなければ \fBmbstowcs\fP()  関数は マルチバイト文字列 \fI*src\fP を \fIdest\fP
  40 から始まるワイド文字列に 変換する。\fIdest\fP には最大で \fIn\fP 文字のワイド文字が 書き込まれる。変換は初期状態で開始され、
  41 以下の三つのいずれかの条件で停止する:
  42 .IP 1. 3
  43 不正なマルチバイト列に遭遇した。この場合には \fI(size_t)\ \-1\fP を返す。
  44 .IP 2.
  45 \fIn\fP 文字の L\(aq\e0\(aq 以外のワイド文字を \fIdest\fP に格納した場合。 この場合は \fI*src\fP
  46 が次に変換されるマルチバイト列を指すようにして、 \fIdest\fP に書き込まれたワイド文字の数を返す。しかしこの指している 場所のシフト状態は失われる。
  47 .IP 3.
  48 マルチバイト文字列が終端のヌルワイド文字 (\(aq\e0\(aq) まで含めて完全に 変換された場合。この場合は終端のヌルワイド文字を除いて
  49 \fIdest\fP に書き込まれた文字数を返す。
  50 .PP
  51 プログラマーは \fIdest\fP に最低でも \fIn\fP ワイド文字を書き込むこ とができる空間があることを保証しなければならない。
  52 .PP
  53 \fIdest\fP が NULL の場合、\fIn\fP は無視され、上記と同様の変換が 行われるが、変換されたワイド文字はメモリーに書き込まれず、変換先の上限
  54 が存在しない。
  55 .PP
  56 上記の 2. の場合を避けるためにプログラマーは \fIn\fP が \fImbstowcs(NULL,src,0)+1\fP 以上であることを保証すべきである。
  57 .SH 返り値
  58 \fBmbstowcs\fP()  関数はワイド文字列に変換完了したワイド文字の数を返す。
  59 終端のヌルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には \fI(size_t)\ \-1\fP を返す。
  60 .SH 準拠
  61 C99.
  62 .SH 注意
  63 \fBmbstowcs\fP()  の動作は現在のロケールの \fBLC_CTYPE\fP カテゴリーに依存している。
  64 .PP
  65 \fBmbsrtowcs\fP(3)  関数は同じ機能のより良いインターフェースを提供する。
  66 .SH 例
  67 下記のプログラムは \fBmbstowcs\fP() といくつかのワイド文字分類関数の使用方法を示したものである。実行例は以下のようになる。
  68 .in +4n
  69 .nf
  70
  71 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
  72 Length of source string (excluding terminator):
  73     8 bytes
  74     6 multibyte characters
  75
  76 Wide character string is: Grüße! (6 characters)
  77     G alpha upper
  78     r alpha lower
  79     ü alpha lower
  80     ß alpha lower
  81     e alpha lower
  82     ! !alpha
  83 .fi
  84 .in
  85 .SS プログラムのソース
  86 .nf
  87 #include <locale.h>
  88 #include <wchar.h>
  89 #include <stdio.h>
  90 #include <string.h>
  91 #include <stdlib.h>
  92
  93 int
  94 main(int argc, char *argv[])
  95 {
  96     size_t mbslen;      /* Number of multibyte characters in source */
  97     wchar_t *wcs;       /* Pointer to converted wide character string */
  98     wchar_t *wp;
  99
 100     if (argc < 3) {
 101         fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]);
 102         exit(EXIT_FAILURE);
 103     }
 104
 105     /* Apply the specified locale */
 106
 107     if (setlocale(LC_ALL, argv[1]) == NULL) {
 108         perror("setlocale");
 109         exit(EXIT_FAILURE);
 110     }
 111
 112     /* Calculate the length required to hold argv[2] converted to
 113        a wide character string */
 114
 115     mbslen = mbstowcs(NULL, argv[2], 0);
 116     if (mbslen == (size_t) \-1) {
 117         perror("mbstowcs");
 118         exit(EXIT_FAILURE);
 119     }
 120
 121     /* Describe the source string to the user */
 122
 123     printf("Length of source string (excluding terminator):\en");
 124     printf("    %zu bytes\en", strlen(argv[2]));
 125     printf("    %zu multibyte characters\en\en", mbslen);
 126
 127     /* Allocate wide character string of the desired size.  Add 1
 128        to allow for terminating null wide character (L\(aq\e0\(aq). */
 129
 130     wcs = calloc(mbslen + 1, sizeof(wchar_t));
 131     if (wcs == NULL) {
 132         perror("calloc");
 133         exit(EXIT_FAILURE);
 134     }
 135
 136     /* Convert the multibyte character string in argv[2] to a
 137        wide character string */
 138
 139     if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
 140         perror("mbstowcs");
 141         exit(EXIT_FAILURE);
 142     }
 143
 144     printf("Wide character string is: %ls (%zu characters)\en",
 145             wcs, mbslen);
 146
 147     /* Now do some inspection of the classes of the characters in
 148        the wide character string */
 149
 150     for (wp = wcs; *wp != 0; wp++) {
 151         printf("    %lc ", (wint_t) *wp);
 152
 153         if (!iswalpha(*wp))
 154             printf("!");
 155         printf("alpha ");
 156
 157         if (iswalpha(*wp)) {
 158             if (iswupper(*wp))
 159                 printf("upper ");
 160
 161             if (iswlower(*wp))
 162                 printf("lower ");
 163         }
 164
 165         putchar(\(aq\en\(aq);
 166     }
 167
 168     exit(EXIT_SUCCESS);
 169 }
 170 .fi
 171 .SH 関連項目
 172 \fBmblen\fP(3), \fBmbsrtowcs\fP(3), \fBmbtowc\fP(3), \fBwctomb\fP(3), \fBwcstombs\fP(3)
 173 .SH この文書について
 174 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 175 である。プロジェクトの説明とバグ報告に関する情報は
 176 http://www.kernel.org/doc/man\-pages/ に書かれている。