Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
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/ に書かれている。