名前

       iconv - 文字セット変換を行う

書式

       #include <iconv.h>

       size_t iconv(iconv_t cd,
                    char **inbuf, size_t *inbytesleft,
                    char **outbuf, size_t *outbytesleft);

説明

       iconv()  関数は、ある文字エンコーディングの文字シーケンス列を別の文字 エンコーディングの文
       字シーケンスに変換する。cd 引き数は変換ディスク リプタ (conversion descriptor)  であり、以
       前は  iconv_open(3) を呼び出 すことで生成されていた。変換ディスクリプターは iconv() が変換
       に使用す る文字エンコーディングを定義するものである。 inbuf 引き数は入力シー  ケンスの先頭
       バイトを指す変数のアドレスであり、inbytesleft  は入力シー ケンスのバッファーのバイト数を示
       す。outbuf    引き数は出力バッファーで利用    できる先頭バイトを指す変数のアドレスであり、
       outbytesleft は出力 バッファーのバイト数を示す。

       主に使われるのは、 「inbuf が NULL でなく、かつ *inbuf が NULL でない」 という場合である。
       この場合、 iconv()  関数は、 *inbuf で始まるマルチバイト文字列を *outbuf  で始まるマルチバ
       イト文字列に変換する。  *inbuf  を先頭として最大 *inbytesleft バイトが読み込まれ、 *outbuf
       を先頭として最大 *outbytesleft バイトが書き出される。

       iconv()  関数は 1 度に 1 つのマルチバイト文字を変換する。 そして、各文字変換毎に、変換され
       た入力バイトの数だけ *inbuf を増加させ、*inbytesleft を減少させる。 また、変換された出力バ
       イトの数だけ *outbuf を増加させ、*outbytesleft を減少させる。 さらに、cd  に含まれる変換状
       態を更新する。  入力の文字エンコーディングがが状態を持つ場合、 iconv()  関数は入力バイトの
       列に対して変換にも対応しており、 バイト出力を伴わずに変換状態を更新することができる。 変換
       は、次の 4 つの場合に停止する。

       1. 入力に無効なマルチバイト文字列があった場合。この場合、  関数は  errno  を EILSEQ に設定
          し、 (size_t) -1 を返す。 *inbuf は、無効なマルチバイト文字列の先頭を指したままになる。

       2. 入力バイト文字列が完全に変換され、*inbytesleft が 0 になった場合。  この場合、  iconv()
          は呼出しの間に非可逆変換が行われた回数を返す。

       3. 入力に不完全なマルチバイト文字列があり、入力バイト文字列がその後で終了 している場合。こ
          の場合、関数は、errno を EINVAL に設定し、 (size_t) -1 を返す。 *inbuf は、不完全なマル
          チバイト文字列の先頭 を指したままにされる。

       4. 出力バッファーに次の変換された文字列のための空きがない場合。  この場合、 errno が E2BIG
          に設定され、 (size_t) -1 が返される。

       別のケースとしては、 「inbuf が NULL、または *inbuf が  NULL  である。  しかし、outbuf  が
       NULL  でなく、かつ  *outbuf  が  NULL でない」 という場合がある。 この場合、 iconv()  関数
       は、cd の変換状態を初期状態にして、 対応するシフト文字列を *outbuf に保存しようとする。 最
       大 *outbytesleft バイトが、*outbuf を始めとして書き出される。 このリセットされた文字列に対
       して、出力バッファーに空きがない場合、 この関数は errno を E2BIG に設定し、 (size_t) -1 を
       返す。     それ以外の場合、この関数は、書き込まれたバイトの数だけ     *outbuf     を増加さ
       せ、*outbytesleft を減少させる。

       3 番目のケースしては、 「inbuf が NULL、または *inbuf が  NULL  である。  かつ、outbuf  が
       NULL、または *outbuf が NULL である」 という場合がある。 この場合、 iconv()  関数は、cd の
       変換状態を初期状態にする。

返り値

       iconv()  関数は、呼出しの間に非可逆な方法で変換された文字数を返す。 つまり、可逆変換はカウ
       ントされない。 エラーの場合、この関数は errno を設定し、 (size_t) -1 を返す。

エラー

       他のいろいろなエラーのうちから、以下のエラーが起こりうる。

       E2BIG  *outbuf に十分な空きがない。

       EILSEQ 入力に無効なマルチバイト文字列があった。

       EINVAL 入力に不完全なマルチバイト文字列があった。

バージョン

       この関数はバージョン 2.1 以降の glibc で利用可能である。

属性

   マルチスレッディング (pthreads(7) 参照)
       iconv() 関数はスレッドセーフである。

準拠

       POSIX.1-2001.

注意

       inbuf  と outbuf は char ** 型だが、これらの変数が指す オブジェクトが C の文字列、つまり文
       字の配列として解釈されることを意味  するわけではない。文字バイトシーケンスの解釈は変換関数
       の内部で行われる。  エンコーディングによっては、バイト 0 もマルチバイト文字の有効な 構成要
       素の場合がある。

       iconv() の呼び出し元は、 iconv() に渡すポインターが、 必要な文字集合の文字にアクセスするの
       に適したものとなっていることを  保証しなければならない。これには、アライメントに関して厳し
       い制限が あるプラットフォームにおいて正しいアライメントになっていることを 保証するといった
       ことも含まれる。

関連項目

       iconv_close(3), iconv_open(3), iconvconfig(8)

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。