Manpages

名 前

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 つ の 場 合 に 停 止 す る 。

を EILSEQ に 設 定 し 、 (size_t) −1 を 返 す 。 *inbuf は 、 無 効 な マ ル チ バ イ ト 文 字 列 の 先 頭 を 指 し た ま ま に な る 。

こ の 場 合 、 iconv() は 呼 出 し の 間 に 非 可 逆 変 換 が 行 わ れ た 回 数 を 返 す 。

errno を EINVAL に 設 定 し 、 (size_t) −1 を 返 す 。 *inbuf は 、 不 完 全 な マ ル チ バ イ ト 文 字 列 の 先 頭 を 指 し た ま ま に さ れ る 。

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 を 返 す 。

エ ラ ー

他 の い ろ い ろ な エ ラ ー の う ち か ら 、 以 下 の エ ラ ー が 起 こ り う る 。

入 力 に 無 効 な マ ル チ バ イ ト 文 字 列 が あ っ た 。

バ ー ジ ョ ン

こ の 関 数 は バ ー ジ ョ ン 2.1 以 降 の glibc で 利 用 可 能 で あ る 。

属 性

マ ル チ ス レ ッ デ ィ ン グ (pthreads(7) 参 照 )

iconv() 関 数 は ス レ ッ ド セ ー フ で あ る 。

準 拠

POSIX.1−2001.

注 意

inbuf と outbuf は char ** 型 だ が 、 こ れ ら の 変 数 が 指 す オ ブ ジ ェ ク ト が C の 文 字 列 、 つ ま り 文 字 の 配 列 と し て 解 釈 さ れ る こ と を 意 味 す る わ け で は な い 。 文 字 バ イ ト シ ー ケ ン ス の 解 釈 は 変 換 関 数 の 内 部 で 行 わ れ る 。 エ ン コ ー デ ィ ン グ に よ っ て は 、 バ イ ト 0 も マ ル チ バ イ ト 文 字 の 有 効 な 構 成 要 素 の 場 合 が あ る 。

iconv() の 呼 び 出 し 元 は 、 iconv() に 渡 す ポ イ ン タ ー が 、 必 要 な 文 字 集 合 の 文 字 に ア ク セ ス す る の に 適 し た も の と な っ て い る こ と を 保 証 し な け れ ば な ら な い 。 こ れ に は 、 ア ラ イ メ ン ト に 関 し て 厳 し い 制 限 が あ る プ ラ ッ ト フ ォ ー ム に お い て 正 し い ア ラ イ メ ン ト に な っ て い る こ と を 保 証 す る と い っ た こ と も 含 ま れ る 。

関 連 項 目

iconv_close(3), iconv_open(3), iconvconfig(8)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man−pages プ ロ ジ ェ ク ト の リ リ ー ス 3.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。