ICONV

Section: Linux Programmer's Manual (3)
Updated: 2001-11-15
Index JM Home Page roff page
 

名前

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

書式

#include <iconv.h>

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

説明

引き数 cd は、関数 iconv_open(3) を使って生成される 変換ディスクリプターでなければならない。

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

iconv() 関数は 1 度に 1 つのマルチバイト文字を変換する。 そして、各文字変換毎に、変換された入力バイトの数だけ *inbuf を増加させ、*inbytesleft を減少させる。 また、変換された出力バイトの数だけ *outbuf を増加させ、*outbytesleft を減少させる。 さらに、cd に含まれる変換状態を更新する。 変換は、次の 4 つの場合に停止する。

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

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

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

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

別のケースとしては、 「inbuf が NULL、または *inbuf が NULL である。 しかし、outbuf が NULL でなく、かつ *outbuf が NULL でない」 という場合がある。 この場合、 iconv() 関数は、cd の変換状態を初期状態にして、 対応するシフト文字列を *outbuf に保存しようとする。 最大 *outbytesleft バイトが、*outbuf を始めとして書き出される。 このリセットされた文字列に対して、出力バッファーに空きがない場合、 この関数は errnoE2BIG に設定し、 (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
入力に不完全なマルチバイト文字列があった。
 

準拠

POSIX.1-2001.  

関連項目

iconv_close(3), iconv_open(3)


 

Index

名前
書式
説明
返り値
エラー
準拠
関連項目

This document was created by man2html, using the manual pages.
Time: 04:31:45 GMT, November 19, 2007