manual/LDP_man-pages/draft/man3/wcsrtombs.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 .\"   ISO/IEC 9899:1999
  15 .\"
  16 .\"*******************************************************************
  17 .\"
  18 .\" This file was generated with po4a. Translate the source file.
  19 .\"
  20 .\"*******************************************************************
  21 .\"
  22 .\" Translated Sat Oct 23 15:38:11 JST 1999
  23 .\"           by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
  24 .\"
  25 .TH WCSRTOMBS 3 2019\-03\-06 GNU "Linux Programmer's Manual"
  26 .SH 名前
  27 wcsrtombs \- ワイド文字文字列をマルチバイト文字列に変換する
  28 .SH 書式
  29 .nf
  30 \fB#include <wchar.h>\fP
  31 .PP
  32 \fBsize_t wcsrtombs(char *\fP\fIdest\fP\fB, const wchar_t **\fP\fIsrc\fP\fB,\fP
  33 \fB                 size_t \fP\fIlen\fP\fB, mbstate_t *\fP\fIps\fP\fB);\fP
  34 .fi
  35 .SH 説明
  36 \fIdest\fP が NULL でなければ、 \fBwcsrtombs\fP()  関数は ワイド文字文字列 \fI*src\fP を \fIdest\fP
  37 が指すマルチバイト文字列 に変換する。最大 \fIlen\fP バイトまでが \fIdest\fP に書き込まれる。 シフト状態 \fI*ps\fP
  38 は更新される。実際の効果としては、この変換は以下 の動作と同じになる: \fIwcrtomb(dest, *src, ps)\fP を呼び、成功が返ったら、
  39 \fIdest\fP を書き込んだバイト数だけ増やし、\fI*src\fP を 1 増やす。 そして、wcrtomb が成功を返す限りこれを繰り返す。
  40 変換が止まる理由は 3 つ考えられる:
  41 .IP 1. 3
  42 (現在のロケールに基づいて)マルチバイト列で表現できないワイド文字に 出会った場合。この場合は、\fI*src\fP は不正なワイド文字を指した状態になり、
  43 \fI(size_t)\ \-1\fP が返され、\fIerrno\fP に \fBEILSEQ\fP が設定される。
  44 .IP 2.
  45 長さの制限により変換が止められた場合。この場合には、\fI*src\fP は次に 変換されるべきワイド文字列を指した状態になり、\fIdest\fP に書き込まれ
  46 たバイト数が返される。
  47 .IP 3.
  48 ワイド文字列が終端のヌルワイド文字 (L\(aq\e0\(aq) も含めて全て 変換された場合。この際、\fI*ps\fP
  49 が初期状態に戻るという副作用がある。 この場合には \fI*src\fP に NULL が設定され、\fIdest\fP に書き込まれた バイト数が返される
  50 (終端のヌルバイト (L\(aq\e0\(aq) は数えない)。
  51 .PP
  52 \fIdest\fP が NULL ならば \fIlen\fP は無視されて前述のように変換が行わ
  53 れるが、変換されたバイトデータはメモリーに書き出されない点と、出力先の長 さの制限がない点が異なる。
  54 .PP
  55 上記のいずれの場合も、\fIps\fP が NULL ならば、\fBwcsrtombs\fP() 関数
  56 だけが知っている静的な匿名の状態がシフト状態の代わりに用いられる。
  57 .PP
  58 プログラマは少なくとも \fIlen\fP バイトの領域を \fIdest\fP に確保しな ければならない。
  59 .SH 返り値
  60 \fBwcsrtombs\fP()  は、変換して得られたマルチバイト列のバイト数を返す。 これには終端の null バイトは含まれない。
  61 変換できないワイド文字に出会った場合には \fI(size_t)\ \-1\fP が返され、 \fIerrno\fP に \fBEILSEQ\fP が設定される。
  62 .SH 属性
  63 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
  64 .TS
  65 allbox;
  66 lb lb lbw28
  67 l l l.
  68 インターフェース        属性  値
  69 T{
  70 \fBwcsrtombs\fP()
  71 T}      Thread safety   MT\-Unsafe race:wcsrtombs/!ps
  72 .TE
  73 .sp 1
  74 .SH 準拠
  75 POSIX.1\-2001, POSIX.1\-2008, C99.
  76 .SH 注意
  77 \fBwcsrtombs\fP()  の動作は現在のロケールの \fBLC_CTYPE\fP カテゴリーに依存する。
  78 .PP
  79 \fIps\fP に NULL を渡した際の動作はマルチスレッドセーフでない。
  80 .SH 関連項目
  81 \fBiconv\fP(3), \fBmbsinit\fP(3), \fBwcrtomb\fP(3), \fBwcsnrtombs\fP(3), \fBwcstombs\fP(3)
  82 .SH この文書について
  83 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
  84 \%https://www.kernel.org/doc/man\-pages/ に書かれている。