![]()
|
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変数ではなく、関数の返り値で判別します。起こりうるエラーは次のとおりです。
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以外の値を返します。起こりうるエラーは次のとおりです。
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 |