manual/LDP_man-pages/release/man3/mbstowcs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  15 .\"         all rights reserved.
  16 .\" Translated Tue Jan 11 00:56:04 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH MBSTOWCS 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  20 .SH 名前
  21 mbstowcs \- マルチバイト文字列をワイド文字列に変換する
  22 .SH 書式
  23 .nf
  24 .B #include <stdlib.h>
  25 .sp
  26 .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
  27 .fi
  28 .SH 説明
  29 \fIdest\fP が NULL ポインターでなければ
  30 .BR mbstowcs ()
  31 関数は
  32 マルチバイト文字列 \fI*src\fP を \fIdest\fP から始まるワイド文字列に
  33 変換する。\fIdest\fP には最大で \fIn\fP 文字のワイド文字が
  34 書き込まれる。変換は初期状態で開始され、
  35 以下の三つのいずれかの条件で停止する:
  36 .IP 1. 3
  37 不正なマルチバイト列に遭遇した。この場合には
  38 .I (size_t)\ \-1
  39 を返す。
  40 .IP 2.
  41 \fIn\fP 文字の L\(aq\\0\(aq 以外のワイド文字を \fIdest\fP に格納した場合。
  42 この場合は \fI*src\fP が次に変換されるマルチバイト列を指すようにして、
  43 \fIdest\fP に書き込まれたワイド文字の数を返す。しかしこの指している
  44 場所のシフト状態は失われる。
  45 .IP 3.
  46 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\\0\(aq) まで含めて完全に
  47 変換された場合。この場合は終端の NULL ワイド文字を除いて
  48 \fIdest\fP に書き込まれた文字数を返す。
  49 .PP
  50 プログラマーは \fIdest\fP に最低でも \fIn\fP ワイド文字を書き込むこ
  51 とができる空間があることを保証しなければならない。
  52 .PP
  53 \fIdest\fP が NULL の場合、\fIn\fP は無視され、上記と同様の変換が
  54 行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
  55 が存在しない。
  56 .PP
  57 上記の 2. の場合を避けるためにプログラマーは \fIn\fP が
  58 \fImbstowcs(NULL,src,0)+1\fP 以上であることを保証すべきである。
  59 .SH 返り値
  60 .BR mbstowcs ()
  61 関数はワイド文字列に変換完了したワイド文字の数を返す。
  62 終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には
  63 .I (size_t)\ \-1
  64 を返す。
  65 .SH 準拠
  66 C99.
  67 .SH 注意
  68 .BR mbstowcs ()
  69 の動作は現在のロケールの
  70 .B LC_CTYPE
  71 カテゴリに依存している。
  72 .PP
  73 .BR mbsrtowcs (3)
  74 関数は同じ機能のより良いインターフェースを提供する。
  75 .SH 関連項目
  76 .BR mbsrtowcs (3),
  77 .BR wcstombs(3)