EN JA
ICONV(3)
ICONV(3) FreeBSD Library Functions Manual ICONV(3)

名称

iconv_open, iconv_open_into, iconv_close, iconvコードセット (codeset) 変換関数

ライブラリ

Standard C Library (libc, -lc)

書式

#include < iconv.h>

iconv_t
iconv_open( const char *dstname, const char *srcname);

int
iconv_open_into( const char *dstname, const char *srcname, iconv_allocation_t *ptr);

int
iconv_close( iconv_t cd);

size_t
iconv( iconv_t cd, char ** restrict src, size_t * restrict srcleft, char ** restrict dst, size_t * restrict dstleft);

size_t
__iconv( iconv_t cd, const char ** restrict src, size_t * restrict srcleft, char ** restrict dst, size_t * restrict dstleft, uint32_t flags, size_t invalids);

解説

iconv_open() 関数は、コードセット srcname からコードセット dstname へのコンバータ (converter, 変換プログラム) をオープンし、その記述子を返します。引数 srcnamedstname は、現在のロケールのエンコード (符号化) を参照する、""と "char"を受け付けます。

iconv_open_into() は、あらかじめ割り付けられた空間で変換記述子を作成します。 iconv_allocation_t は、そのような空間を割り付けるとき、spaceholder タイプとして使用されます。 dstnamesrcname 引数は、 iconv_open() の場合と同じです。 ptr 引数は、あらかじめ割り付けられた空間への iconv_allocation_t のポインタです。

iconv_close() 関数は、指定されたコンバータ (converter) cd をクローズします。

iconv() 関数は、長さ *srcleft バイトのバッファ *src の文字列を変換して、サイズ *dstleft バイトのバッファ *dst に変換された文字列を格納します。 iconv() を呼び出した後に、 src, srcleft, dstdstleft によって指される値は、次のように更新されます:

*src
最後に取って来られた文字の直後のバイトへのポインタ。
*srcleft
ソースバッファの残りのバイトの数。
*dst
最後に格納された文字の直後のバイトへのポインタ。
*dstleft
宛先バッファの残りバイトの数。

*src によって指されている文字列がソースのコードセットの有効な文字でないバイトシーケンスを含んでいるなら、変換は、最後の成功した変換の直後で停止します。出力バッファが変換された文字を格納するには小さすぎるなら、変換は、また、同じ方法で停止します。これらの場合に、 src, srcleft, dstdstleft によって指された値は、最後の成功した変換の直後に状態を更新されます。

*src によって指される文字列がソースのコードセットの下で有効であるが、宛先のコードセットに変換することができない文字を含んでいるなら、文字は、宛先のコードセットに依存する“不正な文字”によって置き換えられます、例えば、‘?’そして、変換は、継続されます。 iconv() は、そのような“不正な変換”の数を返します。

iconv() の 2 つの特殊な場合があります:

src == NULL || *src == NULL
ソースおよび宛先のコードセットがステートフル (stateful, 処理状態を把握する) であるなら、 iconv() は、それらの初期状態に、これらを置きます。

dst*dst の両方が NULL でないなら、 iconv() は、 *dst によって指されるバッファの初期状態に切り替える宛先のためのシフトシーケンスを格納します。バッファのサイズは、上記のように dstleft で指される値によって指定されます。 iconv() は、バッファがシフトシーケンスを格納するために小さすぎるなら、失敗します。

他方では、 dst または *dst は、 NULL であるかもしれません。この場合に、初期状態に切り替える宛先のためのシフトシーケンスは、廃棄されます。

__iconv() 関数は、ちょうど iconv() のように動作しますが、 iconv() が失敗するなら、不正な文字のカウントは、そこで失われます。これは、 IEEE Std 1003.1-2008 (“POSIX.1”) の制限よりバグがないので、 __iconv() は、代替として提供されますが、非標準のインタフェースです。また、それは、現在、次のフラグを渡すことができる、フラグ引数があります:

__ICONV_F_HIDE_INVALID
エラーで返る代わりに、不正な文字をスキップします。

戻り値

iconv_open() が成功して完了すれば、変換記述子を返します。そうでなければ、 iconv_open() は、(iconv_t)-1 を返し、errno をエラーを示す値に設定します。

iconv_open_into() が成功して完了すれば、0 を返します。そうでなければ、 iconv_open_into() は、-1 を返し、errno をエラーを示す値に設定します。

iconv_close() が成功して完了すれば、0 を返します。そうでなければ、 iconv_close() は、-1 を返し、errno をエラーを示す値に設定します。

iconv() が成功して完了すれば、“不正な”変換の数を返します。そうでなければ、 iconv() は、(size_t)-1 を返し、errno をエラーを示す値に設定します。

エラー

iconv_open() 関数は、次の場合にエラーを引き起こします:
[ ENOMEM]
メモリが使い果たされた。
[ EINVAL]
srcnamedstname によって指定されたコンバータがありません。
iconv_open_into() 関数は、次の場合にエラーを引き起こします:
[ EINVAL]
srcnamedstname によって指定されたコンバータがありません。

iconv_close() 関数は、次の場合にエラーを引き起こします:

[ EBADF]
cd によって指定された変換記述子が無効です。

iconv() 関数は、次の場合にエラーを引き起こします:

[ EBADF]
cd によって指定された変換記述子が無効です。
[ EILSEQ]
*src によって指された文字列が、ソースのコードセットの有効な文字について記述しないバイト列を含んでいます。
[ E2BIG]
*dst に指された出力バッファが、結果の文字列を格納すには小さすぎます。
[ EINVAL]
*src によって指された文字列が、不完全な文字またはシフトシーケンスで終了しています。

規格

iconv_open(), iconv_close(), と iconv() 関数は、 IEEE Std 1003.1-2008 (“POSIX.1”) に適合しています。

iconv_open_into() 関数は、GNU に特有の拡張で、あらゆる標準の一部ではありません、したがって、その使用は、移植性を壊すかもしれません。 __iconv() 関数は、独自の拡張で、あらゆる標準の一部ではありません、したがって、その使用は、移植性を壊すかもしれません。

June 16, 2010 FreeBSD