draft/man3/mbsnrtowcs.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 .\"
  13 .\"*******************************************************************
  14 .\"
  15 .\" This file was generated with po4a. Translate the source file.
  16 .\"
  17 .\"*******************************************************************
  18 .TH MBSNRTOWCS 3 2011\-10\-01 GNU "Linux Programmer's Manual"
  19 .SH 名前
  20 mbsnrtowcs \- マルチバイト文字列をワイド文字列に変換する
  21 .SH 書式
  22 .nf
  23 \fB#include <wchar.h>\fP
  24 .sp
  25 \fBsize_t mbsnrtowcs(wchar_t *\fP\fIdest\fP\fB, const char **\fP\fIsrc\fP\fB,\fP
  26 \fB                  size_t \fP\fInms\fP\fB, size_t \fP\fIlen\fP\fB, mbstate_t *\fP\fIps\fP\fB);\fP
  27 .fi
  28 .sp
  29 .in -4n
  30 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  31 .in
  32 .sp
  33 \fBmbsnrtowcs\fP():
  34 .PD 0
  35 .ad l
  36 .RS 4
  37 .TP  4
  38 glibc 2.10 以降:
  39 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  40 .TP
  41 glibc 2.10 より前:
  42 _GNU_SOURCE
  43 .RE
  44 .ad
  45 .PD
  46 .SH 説明
  47 \fBmbsnrtowcs\fP()  関数は \fBmbsrtowcs\fP(3)  関数に似ているが 変換するバイト数が \fI*src\fP から始まる
  48 \fInms\fP バイトに制限されている 点が異なっている。
  49 .PP
  50 \fIdest\fP が NULL ポインターでなければ \fBmbsnrtowcs\fP()  関数は \fI*src\fP からのマルチバイト文字列の最大
  51 \fInms\fP までを \fIdest\fP からのワイド文字列に変換する。 最大 \fIlen\fP 文字のワイド文字が \fIdest\fP に書き込まれる。
  52 同時にシフト状態 \fI*ps\fP を更新する。 変換は \fImbrtowc(dest, *src, n, ps)\fP
  53 を、この呼び出しが成功する限り、繰り返し実行したのと実質的に同様である。 ここでの \fIn\fP は正の数であり、繰り返しごとに \fIdest\fP が 1
  54 増加させられ、 \fI*src\fP が消費したバイト数だけ増加させられる。変換は以下の三つの いずれかの条件で停止する:
  55 .IP 1. 3
  56 不正なマルチバイト列に遭遇した。この場合には \fI*src\fP は不正な マルチバイト列を指すようにして、 \fI(size_t)\ \-1\fP
  57 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
  58 .IP 2.
  59 \fInms\fP 制限によって強制的に停止するか、\fIlen\fP 文字の L\(aq\e0\(aq 以外の ワイド文字を \fIdest\fP
  60 に格納した場合。この場合は \fI*src\fP は 次に変換されるマルチバイト列を指すようにして、\fIdest\fP に書き込まれた ワイド文字の数を返す。
  61 .IP 3.
  62 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\e0\(aq)  まで含めて完全に変換された場合。 (この時、副作用として \fI*ps\fP
  63 が初期状態に戻される。)  この場合は \fI*src\fP には NULL が設定され、 \fIdest\fP に書き込まれた文字数 (終端の NULL
  64 ワイド文字は含まれない) を返す。
  65 .PP
  66 \fIdest\fP が NULL の場合、\fIlen\fP は無視され、上記と同様の変換が 行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
  67 が存在しない。
  68 .PP
  69 上記のどちらの場合でも、\fIps\fP が NULL ポインターならば、代りに mbsnrtowcs 関数のみが使用する静的で名前のない状態が使用される。
  70 .PP
  71 プログラマーは \fIdest\fP に最低でも \fIlen\fP ワイド文字を書き込むこ とができる空間があることを保証しなければならない。
  72 .SH 返り値
  73 \fBmbsnrtowcs\fP()  関数はワイド文字列に変換完了したワイド文字の数を返す。
  74 終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には \fI(size_t)\ \-1\fP を返し、\fIerrno\fP に \fBEILSEQ\fP
  75 を設定する。
  76 .SH 準拠
  77 POSIX.1\-2008.
  78 .SH 注意
  79 \fBmbsnrtowcs\fP()  の動作は現在のロケールの \fBLC_CTYPE\fP カテゴリに依存している。
  80 .PP
  81 \fIps\fP に NULL を渡した際の動作はマルチスレッドセーフでない。
  82 .SH 関連項目
  83 \fBiconv\fP(3), \fBmbsrtowcs\fP(3)