libjconv関数リファレンス

int
jconv_alloc_apply_iconv (iconv_t cd,
                         const char *buffer,
                         size_t len,
                         char **buffer_r,
                         size_t *len_r,
                         size_t *error_pos_r);

引数cdで示されるiconvハンドルを利用してコードセット変換を実行します。引数bufferには変換元のバッファ(nul文字を含んでいてもよく、nulで終わっていなくても構わない)を指定し、引数lenには変換元のバッファのバイト数を指定します。コードセット変換の結果はmallocによりヒープから確保されたメモリ領域に収納され、引数buffer_rの指す先へそのメモリ領域のアドレスが代入されます。そのメモリ領域のバイト数(変換結果のバイト数)は引数len_rの指す先へ代入されます。よって変換結果は、アドレス*buffer_rからの*len_rバイトに格納されています。変換結果は常に終端にnul文字がつけられます。もし変換が失敗した場合は、変換元バッファ中のエラー発生箇所のオフセットがerror_pos_rの指す先へ代入され、関数は0でない値を返します。よってbuffer + *error_pos_rがエラー発生箇所になります。変換が成功した場合はこの関数は0を返します。エラーが発生した場合でも途中までの変換結果が*buffer_rに書き込まれるため、この関数がエラーになったか否かにかかわらず*buffer_rがNULLでない場合はユーザがfreeしなければなりません。もし変換先のコードセットがステートフルなものであった場合は、この関数で得られる変換先のバッファには(必要なら)リセットシーケンスが書きこまれ、バッファの末では常に初期ステートになります。たとえば変換先のコードセットがISO-2022-JPの場合、変換元バッファの最後の文字がJIS-X-0208文字集合のものであっても、変換先のバッファの最後にはASCIIに戻すシーケンスが書きこまれます。この関数が失敗した場合、関数は0でない値を返します。発生したエラーの種類はerrno変数ではなく、関数の返り値で判別します。起こりうるエラーは次のとおりです。

ENOMEM: ヒープからメモリを取得するのに失敗した。メモリが不足している。
EILSEQ: 変換元バッファの中に、変換元コードセットとして不正なバイト列が見つかったか、変換先コードセットへ変換できない文字が見つかった。このとき*error_pos_rが、buffer中のエラーが発生したオフセットになる。
EINVAL: 変換元バッファの最後に不完全なバイト列が付いている。これはたとえば、変換元バッファの末尾が2バイト文字の1バイト目で終わっているときにおこる。
E2BIG: iconvが全く変換を実行しないにもかかわらず正常終了した。もしlenが0ではないにもかかわらずこのエラーが発生したなら、iconvの実装に問題がある。

int
jconv_alloc_conv (const char *src,
                  size_t src_len,
                  char **dest_r,
                  size_t *dest_len_r,
                  const char *const *src_codesets,
                  int num_src_codesets,
                  int *actual_codeset_r,
                  const char *dest_codeset);

srcとsrc_lenで示されるバッファのコードセットを変換し、結果を*dest_rと*dest_len_rに格納します。*dest_rはヒープから確保されます。src_codesetsとnum_src_codesetsで変換元コードセットの候補を指定し、dest_codesetには変換先コードセットを指定します。srcとsrc_lenで示されるバッファがsrc_codesetsの中のいずれかのコードセットとして正しいものであればこの関数は0を返し、*actual_codeset_rにはsrc_codesets中適合したコードセットの番号がセットされます。いずれのコードセットにも適合しなかった場合は0以外の値を返します。起こりうるエラーは次のとおりです。

ENOMEM: メモリが不足している。
EMFILE: プロセスが開けるファイル数の制限に達したためiconvハンドルが取得できない。
ENFILE: システムが開けるファイル数の制限に達したためiconvハンドルが取得できない。。
EINVAL: OSがサポートしていないコードセットを指定した。

そのほかにもjconv_alloc_apply_iconvが返すエラーをそのまま返すことがあります。EINVALは、OSがサポートしていないコードセットを指定したのが原因で起こることもあれば、jconv_alloc_apply_iconvがEINVALを返した(末尾に不完全なバイト列があった)ことによる場合もあります。もし*dest_rがNULLならば前者が原因で、NULLでないならば後者が原因です。

int
jconv_alloc_conv_autodetect (const char *src,
                             size_t src_len,
                             char **dest_r,
                             size_t *dest_len_r,
                             const char *const *src_codesets,
                             int num_src_codesets,
                             int *actual_codeset_r,
                             const char *dest_codeset);

この関数はほとんどjconv_alloc_convと同じ動作をしますが、dest_codesetにNULLを許すのと、num_src_codesetsに0を許す点だけが異なります。dest_codesetがNULLの場合は、jconv_info_get_current_codeset関数の返す値を指定したのと同じことになります。num_src_codesetsが0の場合は、src_codesetsとnum_src_codesetsにjconv_info_get_pref_codesets関数で得られるコードセットのリストを指定したのと同じことになります。

char *
jconv_strdup_conv_autodetect (const char *src,
                              const char *dest_codeset,
                              const char *src_codeset,
                              ...);

この関数はjconv_alloc_conv_autodetectとほぼ同等の機能を持ちますが、扱うバッファが常に文字列(nulで終了するようなバイト列へのポインタ)である点が異なります。この関数はコードセット変換が成功するとヒープから確保された文字列を返し、コードセット変換に失敗するとstrdup(src)を返します。ヒープメモリが不足した場合はNULLを返します。変換元コードセットは可変長引数を使って指定します。この関数への最後の引数は必ずNULLでなくてはなりません。この関数はnul終端文字列を対象としているため、nul文字を含むことがあるコードセット(UCS2など。厳密にはUTF8もnul文字を含むことがある)は変換元や変換先のコードセットとして利用できません。またエラーが発生しても原因を知る方法がありません。

char *
jconv_strdup_conv_fullauto (const char *src);

この関数はjconv_strdup_conv_autodetect(src, NULL, NULL)と同等です。

char *
convert_kanji_auto (const char *src);

この関数はjconv_strdup_conv_fullauto(src)と同等です。古いバージョンとの互換性のために残してあります。

char *
convert_kanji (const char *src, const char *dest_codeset);

この関数はjconv_strdup_conv_autodetect(src, dest_codeset, NULL)と同等です。古いバージョンとの互換性のために残してあります。

char *
convert_kanji_strict (const char *src,
                      const char *dest_codeset,
                      const char *src_codeset);

この関数はjconv_strdup_conv_autodetect(src, dest_codeset, src_codeset, NULL)と同等です。古いバージョンとの互換性のために残してあります。

void
jconv_info_init (const char *conffile);

この関数はjconv_info_get_current_codesetやjconv_info_get_pref_codesetsが返すテーブルを初期化します。テーブルのデータはconffileで示されるファイルから読み取られ、現在のロカール(setlocaleで設定されたロカール)にしたがってjconv_info_get_current_codesetやjconv_info_get_pref_codesetsの返すべき値がセットされます。よってこの関数はsetlocaleでロカールを設定した後に呼び出すべきです。conffileがNULLの場合は/etc/libjconv/default.confが指定されたのと同じことになります。この関数はマルチスレッドセーフではありません。libjconvのコードセット変換関数(jconv_alloc_conv_autodetectなど)は、もしjconv_info_initがまだ実行されていないなら、jconv_info_init(NULL)を内部で暗黙のうちに呼び出してテーブルを初期化します。もしあらかじめjconv_info_initを明示的に呼んでいれば、jconv_alloc_conv_autodetectなどのコードセット変換関数は全てマルチスレッドセーフになります。なおjconv_alloc_apply_iconvとjconv_alloc_convはjconv_info_get_current_codesetやjconv_info_get_pref_codsetsを利用しないため常にマルチスレッドセーフです。

const char *
jconv_info_get_current_codeset (void);

現在のロカールのマルチバイト文字列のコードセットの名前を返します。

const char *const *
jconv_info_get_pref_codesets (int *num_codesets_r);

現在のロカールと関係の深いコードセットのリストを返します。返されるコードセットの個数が*num_codesets_rにセットされます。

Akira Higuchi