OSDN Git Service

(split) LDP: Update draft and release (from the previous commit)
[linuxjm/LDP_man-pages.git] / release / 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 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\e0\(aq) まで含めて完全に 変換された場合。この場合は終端の NULL
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 The program below illustrates the use of \fBmbstowcs\fP(), as well as some of
68 the wider character classification functions.  An example run is the
69 following:
70 .in +4n
71 .nf
72
73 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
74 Length of source string (excluding terminator):
75     8 bytes
76     6 multibyte characters
77
78 Wide character string is: Grüße! (6 characters)
79     G alpha upper
80     r alpha lower
81     ü alpha lower
82     ß alpha lower
83     e alpha lower
84     ! !alpha
85 .fi
86 .in
87 .SS プログラムのソース
88 .nf
89 #include <locale.h>
90 #include <wchar.h>
91 #include <stdio.h>
92 #include <string.h>
93 #include <stdlib.h>
94
95 int
96 main(int argc, char *argv[])
97 {
98     size_t mbslen;      /* Number of multibyte characters in source */
99     wchar_t *wcs;       /* Pointer to converted wide character string */
100     wchar_t *wp;
101
102     if (argc < 3) {
103         fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]);
104         exit(EXIT_FAILURE);
105     }
106
107     /* Apply the specified locale */
108
109     if (setlocale(LC_ALL, argv[1]) == NULL) {
110         perror("setlocale");
111         exit(EXIT_FAILURE);
112     }
113
114     /* Calculate the length required to hold argv[2] converted to
115        a wide character string */
116
117     mbslen = mbstowcs(NULL, argv[2], 0);
118     if (mbslen == (size_t) \-1) {
119         perror("mbstowcs");
120         exit(EXIT_FAILURE);
121     }
122
123     /* Describe the source string to the user */
124
125     printf("Length of source string (excluding terminator):\en");
126     printf("    %zu bytes\en", strlen(argv[2]));
127     printf("    %zu multibyte characters\en\en", mbslen);
128
129     /* Allocate wide character string of the desired size.  Add 1
130        to allow for terminating null wide character (L\(aq\e0\(aq). */
131
132     wcs = calloc(mbslen + 1, sizeof(wchar_t));
133     if (wcs == NULL) {
134         perror("calloc");
135         exit(EXIT_FAILURE);
136     }
137
138     /* Convert the multibyte character string in argv[2] to a
139        wide character string */
140
141     if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
142         perror("mbstowcs");
143         exit(EXIT_FAILURE);
144     }
145
146     printf("Wide character string is: %ls (%zu characters)\en",
147             wcs, mbslen);
148
149     /* Now do some inspection of the classes of the characters in
150        the wide character string */
151
152     for (wp = wcs; *wp != 0; wp++) {
153         printf("    %lc ", (wint_t) *wp);
154
155         if (!iswalpha(*wp))
156             printf("!");
157         printf("alpha ");
158
159         if (iswalpha(*wp)) {
160             if (iswupper(*wp))
161                 printf("upper ");
162
163             if (iswlower(*wp))
164                 printf("lower ");
165         }
166
167         putchar(\(aq\en\(aq);
168     }
169
170     exit(EXIT_SUCCESS);
171 }
172 .fi
173 .SH 関連項目
174 \fBmblen\fP(3), \fBmbsrtowcs\fP(3), \fBmbtowc\fP(3), \fBwctomb\fP(3), \fBwcstombs\fP(3)
175 .SH この文書について
176 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.63 の一部
177 である。プロジェクトの説明とバグ報告に関する情報は
178 http://www.kernel.org/doc/man\-pages/ に書かれている。