draft/man3/wcsnrtombs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"
  15 .\"*******************************************************************
  16 .\"
  17 .\" This file was generated with po4a. Translate the source file.
  18 .\"
  19 .\"*******************************************************************
  20 .TH WCSNRTOMBS 3 2011\-10\-16 GNU "Linux Programmer's Manual"
  21 .SH 名前
  22 wcsnrtombs \- ワイド文字文字列をマルチバイト文字列に変換する
  23 .SH 書式
  24 .nf
  25 \fB#include <wchar.h>\fP
  26 .sp
  27 \fBsize_t wcsnrtombs(char *\fP\fIdest\fP\fB, const wchar_t **\fP\fIsrc\fP\fB, size_t \fP\fInwc\fP\fB,\fP
  28 \fB                  size_t \fP\fIlen\fP\fB, mbstate_t *\fP\fIps\fP\fB);\fP
  29 .fi
  30 .sp
  31 .in -4n
  32 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  33 .in
  34 .sp
  35 \fBwcsnrtombs\fP():
  36 .PD 0
  37 .ad l
  38 .RS 4
  39 .TP  4
  40 glibc 2.10 以降:
  41 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  42 .TP
  43 glibc 2.10 より前:
  44 _GNU_SOURCE
  45 .RE
  46 .ad
  47 .PD
  48 .SH 説明
  49 \fBwcsnrtombs\fP()  関数は、 \fBwcsrtombs\fP()  関数に似ている。ただし、 変換されるワイド文字の数が(\fI*src\fP
  50 から数えて) \fInwc\fP 文字に制限 されている点が異なる。
  51 .PP
  52 \fIdest\fP が NULL ポインタでなければ、 \fBwcsnrtombs\fP()  関数は ワイド文字文字列の最大 \fInwc\fP 個までのワイド文字を
  53 \fIdest\fP から 始まるマルチバイト文字列に変換する。\fIdest\fP には最大 \fIlen\fP バイ トまで書き込まれる。シフト状態 \fI*ps\fP
  54 は更新される。実際の効果とし ては、この変換は以下の動作と同じになる: \fIwcrtomb(dest, *src, ps)\fP を呼び、成功が返ったら
  55 \fIdest\fP を書き込んだバイト数だけ増やし、\fI*src\fP を 1 増やす。 そして、wcrtomb が成功を返す限りこれを繰り返す。
  56 変換が止まる理由は 3 つ考えられる:
  57 .IP 1. 3
  58 A wide character has been encountered that can not be represented as a
  59 multibyte sequence (according to the current locale).  In this case \fI*src\fP
  60 is left pointing to the invalid wide character, \fI(size_t)\ \-1\fP is returned,
  61 and \fIerrno\fP is set to \fBEILSEQ\fP.
  62 .IP 2.
  63 \fInwc\fP wide characters have been converted without encountering a null wide
  64 character (L\(aq\e0\(aq), or the length limit forces a stop.  In this case
  65 \fI*src\fP is left pointing to the next wide character to be converted, and the
  66 number of bytes written to \fIdest\fP is returned.
  67 .IP 3.
  68 The wide\-character string has been completely converted, including the
  69 terminating null wide character (which has the side effect of bringing back
  70 \fI*ps\fP to the initial state).  In this case \fI*src\fP is set to NULL, and the
  71 number of bytes written to \fIdest\fP, excluding the terminating null byte
  72 (\(aq\e0\(aq), is returned.
  73 .PP
  74 \fIdest\fP が NULL ならば \fIlen\fP は無視されて前述のように変換が行わ
  75 れるが、変換されたバイトデータはメモリに書き出されない点と、出力先の長 さの制限がない点が異なる。
  76 .PP
  77 上記のいずれの場合も、\fIps\fP が NULL ポインタならば、\fBwcsnrtombs\fP() 関数
  78 だけが知っている静的な匿名の状態がシフト状態の代わりに用いられる。
  79 .PP
  80 プログラマは少なくとも \fIlen\fP バイトの領域を \fIdest\fP に確保しな ければならない。
  81 .SH 返り値
  82 \fBwcsrtombs\fP()  は、変換して得られたマルチバイト列のバイト数を返す。 これには終端の null バイトは含まれない。
  83 変換できないワイド文字に出会った場合には \fI(size_t)\ \-1\fP が返され、 \fIerrno\fP に \fBEILSEQ\fP が設定される。
  84 .SH 準拠
  85 POSIX.1\-2008.
  86 .SH 注意
  87 \fBwcsnrtombs\fP()  の動作は現在のロケールの \fBLC_CTYPE\fP カテゴリに依存する。
  88 .PP
  89 \fIps\fP に NULL を渡した際の動作はマルチスレッドセーフでない。
  90 .SH 関連項目
  91 \fBiconv\fP(3), \fBwcsrtombs\fP(3)
  92 .SH この文書について
  93 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
  94 である。プロジェクトの説明とバグ報告に関する情報は
  95 http://www.kernel.org/doc/man\-pages/ に書かれている。