名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用例 | ファイル | 属性 | 関連項目
#include <iconv.h>extern size_t iconv(iconv_t cd, const char **restrict inbuf, size_t *restrict inbytesleft, char **restrict outbuf, size_t *restrict outbytesleft);
#include <iconv.h>size_t iconv(iconv_t cd, char **restrict inbuf, size_t *restrict inbytesleft, char **restrict outbuf, size_t *restrict outbytesleft);
iconv() 関数は、inbuf で指定された配列内にある一連の文字のコードセットを変換します。具体的には、各文字を他のコードセットの対応する文字に変換し、結果を outbuf で指定された配列に書き出します。入力側と出力側のコードセットは、変換記述子 cd を返した iconv_open( ) 呼び出し中に指定されていたものです。inbuf 引数は、入力バッファ中の先頭文字を指す変数を指します。inbytesleft は、変換対象となるバッファの終端までのバイト数を表す変数を指します。outbuf 引数は、出力バッファ内で使用可能な先頭バイトを指す変数を指します。outbytesleft は、出力バッファの終端までの使用可能なバイト数を表す変数を指します。
状態に依存するエンコーディングでは、変換記述子 cd は、inbuf が NULL ポインタである呼び出しまたは inbuf が NULL ポインタを指している呼び出しにより、初期のシフト状態に置かれます。このようにして iconv() が呼び出されたとき、outbuf が NULL ポインタでも NULL ポインタへのポインタでもない場合、outbytesleft が正の値を指していれば、iconv() はバイトシーケンスを出力バッファに書き込み、それにより出力バッファは初期のシフト状態に変更されます。リセットシーケンス全体を格納するのに必要なスペースが出力バッファ中になければ、iconv() は errno を E2BIG に設定して異常終了します。その後、inbuf が NULL ポインタでもなく NULL ポインタへのポインタでもない iconv() を呼び出すと、その時点の変換記述子に対して変換が行われます。
入力側の一連のバイトが、指定されたコードセット中の正当な文字を表していない場合には、最後に正しく変換された文字までで 変換が終了します。入力バッファ中のデータが、文字やシフトシーケンスの途中で終わってしまっている場合には、最後に正しく変換されたバイトまでで 変換が終了します。出力バッファが変換後のデータをすべて格納するのに十分な大きさでない場合、オーバーフローを起こすバイトの直前までで変換が終了します。inbuf がポイントする変数は、正しく変換された最後のバイトの直後のバイトを 指すように更新されます。inbytesleft が示す値は、入力バッファ内に残されている未変換のバイト数を表す ように減算されます。outbuf が指す変数は、変換して出力されたデータの最終バイトの次のバイトをポイントするように更新されます。outbytesleft が示す値は、出力バッファ中で使用可能な残りバイト数を表すように減算されます。状態に依存するエンコーディングのために、変換記述子は、最後に正しく変換されたバイトシーケンスの変換終了時に有効だったシフト状態を表すように更新されます。
正当ではあるが対応する文字が出力側コードセットにない、という文字を入力バッファ中に検出した場合、iconv() はシステムが定義したその文字を変換します。
iconv() 関数は、引数で示された変数を更新して、どこまで変換が行われたかを 表すようにします。また、出力側コードセットに該当する文字が存在しなかった変換の数を返します。入力バッファ中の文字列全体が変換されれば、inbytesleft が指す値は 0 となります。前述した理由のいずれかにより変換が途中で停止した場合には、inbytesleft の値は 0 以外となり、状況を表す値が errno に設定されます。エラーが発生した場合、iconv() はエラーの状況を表す値を errno に設定して (size_t)–1 の値を返します。
iconv() 関数は、以下のいずれかの場合に異常終了します。
入力側のコードセットに属さないバイトが入力バッファ中に見つかり、変換を終了した
出力バッファ中に十分なスペースがないため、変換を終了した
入力バッファのデータが文字またはシフトシーケンスの途中で終わったため、変換を終了した
iconv() は、以下のいずれかの場合に異常終了することがあります。
cd 引数が、正しく、しかもオープンされている変換記述子を表していない
#include <stdio.h> #include <errno.h> #include <string.h> #include <iconv.h> #include <stdlib.h> /* * For state-dependent encodings, changes the state of the conversion * descriptor to initial shift state. Also, outputs the byte sequence * to change the state to initial state. * This code is assuming the iconv call for initializing the state * won't fail due to lack of space in the output buffer. */ #define INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft) \ { \ fptr = NULL; \ ileft = 0; \ tptr = to; \ oleft = BUFSIZ; \ (void) iconv(cd, &fptr, &ileft, &tptr, &oleft); \ (void) fwrite(to, 1, BUFSIZ - oleft, stdout); \ } int main(int argc, char **argv) { iconv_t cd; char from[BUFSIZ], to[BUFSIZ]; char *from_code, *to_code; char *tptr; const char *fptr; size_t ileft, oleft, num, ret; if (argc != 3) { (void) fprintf(stderr, "Usage: %s from_codeset to_codeset\\n", argv[0]); return (1); } from_code = argv[1]; to_code = argv[2]; cd = iconv_open((const char *)to_code, (const char *)from_code); if (cd == (iconv_t)-1) { /* * iconv_open failed */ (void) fprintf(stderr, "iconv_open(%s, %s) failed\\n", to_code, from_code); return (1); } ileft = 0; while ((ileft += (num = fread(from + ileft, 1, BUFSIZ - ileft, stdin))) > 0) { if (num == 0) { /* * Input buffer still contains incomplete character * or sequence. However, no more input character. */ /* * Initializes the conversion descriptor and outputs * the sequence to change the state to initial state. */ INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); (void) iconv_close(cd); (void) fprintf(stderr, "Conversion error\\n"); return (1); } fptr = from; for (;;) { tptr = to; oleft = BUFSIZ; ret = iconv(cd, &fptr, &ileft, &tptr, &oleft); if (ret != (size_t)-1) { /* * iconv succeeded */ /* * Outputs converted characters */ (void) fwrite(to, 1, BUFSIZ - oleft, stdout); break; } /* * iconv failed */ if (errno == EINVAL) { /* * Incomplete character or shift sequence */ /* * Outputs converted characters */ (void) fwrite(to, 1, BUFSIZ - oleft, stdout); /* * Copies remaining characters in input buffer * to the top of the input buffer. */ (void) memmove(from, fptr, ileft); /* * Tries to fill input buffer from stdin */ break; } else if (errno == E2BIG) { /* * Lack of space in output buffer */ /* * Outputs converted characters */ (void) fwrite(to, 1, BUFSIZ - oleft, stdout); /* * Tries to convert remaining characters in * input buffer with emptied output buffer */ continue; } else if (errno == EILSEQ) { /* * Illegal character or shift sequence */ /* * Outputs converted characters */ (void) fwrite(to, 1, BUFSIZ - oleft, stdout); /* * Initializes the conversion descriptor and * outputs the sequence to change the state to * initial state. */ INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); (void) iconv_close(cd); (void) fprintf(stderr, "Illegal character or sequence\\n"); return (1); } else if (errno == EBADF) { /* * Invalid conversion descriptor. * Actually, this shouldn't happen here. */ (void) fprintf(stderr, "Conversion error\\n"); return (1); } else { /* * This errno is not defined */ (void) fprintf(stderr, "iconv error\\n"); return (1); } } } /* * Initializes the conversion descriptor and outputs * the sequence to change the state to initial state. */ INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); (void) iconv_close(cd); return (0); }
32 ビット用の変換モジュール
64 ビット SPARC 用の変換モジュール
64 ビット amd64 用の変換モジュール
変換バイナリテーブル
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
---|---|
MT レベル | MT-Safe |
インタフェースの安定性 | 標準 |