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
で利用可能である。
この節で使用されている用語の説明については、
attributes(7) を参照。
| インターフェース |
属性 |
値 |
|
iconv() |
Thread safety |
MT-Safe race:cd |
The
iconv() function is MT-Safe, as long as callers arrange for mutual
exclusion on the
cd argument.
POSIX.1-2001, POSIX.1-2008.
In each series of calls to
iconv(), the last should be one with
inbuf or
*inbuf equal to NULL, in order to flush out any
partially converted input.
inbuf と
outbuf は
char **
型だが、これらの変数が指す
オブジェクトが C
の文字列、つまり文字の配列として解釈されることを意味
するわけではない。文字バイトシーケンスの解釈は変換関数の内部で行われる。
エンコーディングによっては、バイト
0
もマルチバイト文字の有効な
構成要素の場合がある。
iconv() の呼び出し元は、
iconv()
に渡すポインターが、
必要な文字集合の文字にアクセスするのに適したものとなっていることを
保証しなければならない。これには、アライメントに関して厳しい制限が
あるプラットフォームにおいて正しいアライメントになっていることを
保証するといったことも含まれる。
iconv_close(3),
iconv_open(3),
iconvconfig(8)
この man ページは Linux
man-pages
プロジェクトのリリース
5.10
の一部である。プロジェクトの説明とバグ報告に関する情報は
https://www.kernel.org/doc/man-pages/
に書かれている。