draft/man3/iconv.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 .\"   OpenGroup's Single UNIX specification
  11 .\"     http://www.UNIX-systems.org/online.html
  12 .\"
  13 .\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
  14 .\" 2000-11-15 aeb, fixed prototype
  15 .\"
  16 .\"*******************************************************************
  17 .\"
  18 .\" This file was generated with po4a. Translate the source file.
  19 .\"
  20 .\"*******************************************************************
  21 .TH ICONV 3 2008\-09\-08 GNU "Linux Programmer's Manual"
  22 .SH 名前
  23 iconv \- 文字セット変換を行う
  24 .SH 書式
  25 .nf
  26 \fB#include <iconv.h>\fP
  27 .sp
  28 \fBsize_t iconv(iconv_t \fP\fIcd\fP\fB,\fP
  29 \fB             char **\fP\fIinbuf\fP\fB, size_t *\fP\fIinbytesleft\fP\fB,\fP
  30 \fB             char **\fP\fIoutbuf\fP\fB, size_t *\fP\fIoutbytesleft\fP\fB);\fP
  31 .fi
  32 .SH 説明
  33 引き数 \fIcd\fP は、関数 \fBiconv_open\fP(3)  を使って生成される 変換ディスクリプターでなければならない。
  34 .PP
  35 主に使われるのは、 「\fIinbuf\fP が NULL でなく、かつ \fI*inbuf\fP が NULL でない」 という場合である。 この場合、
  36 \fBiconv\fP()  関数は、 \fI*inbuf\fP で始まるマルチバイト文字列を \fI*outbuf\fP で始まるマルチバイト文字列に変換する。
  37 \fI*inbuf\fP を先頭として最大 \fI*inbytesleft\fP バイトが読み込まれ、 \fI*outbuf\fP を先頭として最大
  38 \fI*outbytesleft\fP バイトが書き出される。
  39 .PP
  40 \fBiconv\fP()  関数は 1 度に 1 つのマルチバイト文字を変換する。 そして、各文字変換毎に、変換された入力バイトの数だけ \fI*inbuf\fP
  41 を増加させ、\fI*inbytesleft\fP を減少させる。 また、変換された出力バイトの数だけ \fI*outbuf\fP
  42 を増加させ、\fI*outbytesleft\fP を減少させる。 さらに、\fIcd\fP に含まれる変換状態を更新する。
  43 入力の文字エンコーディングがが状態を持つ場合、 \fBiconv\fP()  関数は入力バイトの列に対して変換にも対応しており、
  44 バイト出力を伴わずに変換状態を更新することができる。 変換は、次の 4 つの場合に停止する。
  45 .PP
  46 1. 入力に無効なマルチバイト文字列があった場合。 この場合、関数は \fIerrno\fP を \fBEILSEQ\fP に設定し、 \fI(size_t)\ \-1\fP を返す。 \fI*inbuf\fP は、無効なマルチバイト文字列の先頭を指したままになる。
  47 .PP
  48 2. 入力バイト文字列が完全に変換され、\fI*inbytesleft\fP が 0 になった場合。 この場合、 \fBiconv\fP()
  49 は、呼出しの間に非可逆変換が行われた回数を返す。
  50 .PP
  51 3. 入力に不完全なマルチバイト文字列があり、 入力バイト文字列がその後で終了している場合。 この場合、関数は、\fIerrno\fP を \fBEINVAL\fP
  52 に設定し、 \fI(size_t)\ \-1\fP を返す。 \fI*inbuf\fP は、不完全なマルチバイト文字列の先頭を指したままにされる。
  53 .PP
  54 4. 出力バッファーに次の変換された文字列のための空きがない場合。 この場合、\fIerrno\fP が \fBE2BIG\fP に設定され、
  55 \fI(size_t)\ \-1\fP が返される。
  56 .PP
  57 別のケースとしては、 「\fIinbuf\fP が NULL、または \fI*inbuf\fP が NULL である。 しかし、\fIoutbuf\fP が NULL
  58 でなく、かつ \fI*outbuf\fP が NULL でない」 という場合がある。 この場合、 \fBiconv\fP()  関数は、\fIcd\fP
  59 の変換状態を初期状態にして、 対応するシフト文字列を \fI*outbuf\fP に保存しようとする。 最大 \fI*outbytesleft\fP
  60 バイトが、\fI*outbuf\fP を始めとして書き出される。 このリセットされた文字列に対して、出力バッファーに空きがない場合、 この関数は
  61 \fIerrno\fP を \fBE2BIG\fP に設定し、 \fI(size_t)\ \-1\fP を返す。 それ以外の場合、この関数は、書き込まれたバイトの数だけ
  62 \fI*outbuf\fP を増加させ、\fI*outbytesleft\fP を減少させる。
  63 .PP
  64 3 番目のケースしては、 「\fIinbuf\fP が NULL、または \fI*inbuf\fP が NULL である。 かつ、\fIoutbuf\fP が
  65 NULL、または \fI*outbuf\fP が NULL である」 という場合がある。 この場合、 \fBiconv\fP()  関数は、\fIcd\fP
  66 の変換状態を初期状態にする。
  67 .SH 返り値
  68 \fBiconv\fP()  関数は、呼出しの間に非可逆な方法で変換された文字数を返す。 つまり、可逆変換はカウントされない。 エラーの場合、この関数は
  69 \fIerrno\fP を設定し、 \fI(size_t)\ \-1\fP を返す。
  70 .SH エラー
  71 他のいろいろなエラーのうちから、以下のエラーが起こりうる。
  72 .TP
  73 \fBE2BIG\fP
  74 \fI*outbuf\fP に十分な空きがない。
  75 .TP
  76 \fBEILSEQ\fP
  77 入力に無効なマルチバイト文字列があった。
  78 .TP
  79 \fBEINVAL\fP
  80 入力に不完全なマルチバイト文字列があった。
  81 .SH バージョン
  82 この関数はバージョン 2.1 以降の glibc で利用可能である。
  83 .SH 準拠
  84 POSIX.1\-2001.
  85 .SH 関連項目
  86 \fBiconv_close\fP(3), \fBiconv_open\fP(3)