#include <iconv.h>
size_t iconv(iconv_t cd,
char **inbuf, size_t *inbytesleft,
char **outbuf, size_t *outbytesleft);
主に使われるのは、 「inbuf が NULL でなく、かつ *inbuf が NULL でない」 という場合である。 この場合、 iconv() 関数は、 *inbuf で始まるマルチバイト文字列を *outbuf で始まるマルチバイト文字列に変換する。 *inbuf を先頭として最大 *inbytesleft バイトが読み込まれ、 *outbuf を先頭として最大 *outbytesleft バイトが書き出される。
iconv() 関数は 1 度に 1 つのマルチバイト文字を変換する。 そして、各文字変換毎に、変換された入力バイトの数だけ *inbuf を増加させ、*inbytesleft を減少させる。 また、変換された出力バイトの数だけ *outbuf を増加させ、*outbytesleft を減少させる。 さらに、cd に含まれる変換状態を更新する。 入力の文字エンコーディングが状態を持つ場合、 iconv() 関数は入力バイトの列に対して変換にも対応しており、 バイト出力を伴わずに変換状態を更新することができる。 変換は、次の 4 つの場合に停止する。
別のケースとしては、 「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() | Thread safety | MT-Safe race:cd |
The iconv() function is MT-Safe, as long as callers arrange for mutual exclusion on the cd argument.
inbuf と outbuf は char ** 型だが、これらの変数が指す オブジェクトが C の文字列、つまり文字の配列として解釈されることを意味 するわけではない。文字バイトシーケンスの解釈は変換関数の内部で行われる。 エンコーディングによっては、バイト 0 もマルチバイト文字の有効な 構成要素の場合がある。
iconv() の呼び出し元は、 iconv() に渡すポインターが、 必要な文字集合の文字にアクセスするのに適したものとなっていることを 保証しなければならない。これには、アライメントに関して厳しい制限が あるプラットフォームにおいて正しいアライメントになっていることを 保証するといったことも含まれる。
[man1]
[man2]
[man3]
[man4]
[man5]
[man6]
[man7]
[man8]
[a]
[b]
[c]
[d]
[e]
[f]
[g]
[h]
[i]
[j]
[k]
[l]
[m]
[n]
[o]
[p]
[q]
[r]
[s]
[t]
[u]
[v]
[w]
[x]
[y]
[z]