1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" GNU glibc-2 source code and manual
.\" OpenGroup's Single UNIX specification
.\" http://www.UNIX-systems.org/online.html
.\"
.\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\" 2000-11-15 aeb, fixed prototype
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2000 Yuichi SATO
.\" all rights reserved.
.\" Translated 2000-07-11, Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\" Updated 2008-09-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.09
.\" Updated 2012-05-30, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH ICONV 3 2012\-05\-10 GNU "Linux Programmer's Manual"
.SH 名前
iconv \- 文字セット変換を行う
.SH 書式
.nf
\fB#include <iconv.h>\fP
.sp
\fBsize_t iconv(iconv_t \fP\fIcd\fP\fB,\fP
\fB char **\fP\fIinbuf\fP\fB, size_t *\fP\fIinbytesleft\fP\fB,\fP
\fB char **\fP\fIoutbuf\fP\fB, size_t *\fP\fIoutbytesleft\fP\fB);\fP
.fi
.SH 説明
\fBiconv\fP() 関数は、ある文字エンコーディングの文字シーケンス列を別の文字
エンコーディングの文字シーケンスに変換する。\fIcd\fP 引き数は変換ディスク
リプタ (conversion descriptor) であり、以前は \fBiconv_open\fP(3) を呼び出
すことで生成されていた。変換ディスクリプタは \fBiconv\fP() が変換に使用す
る文字エンコーディングを定義するものである。 \fIinbuf\fP 引き数は入力シー
ケンスの先頭バイトを指す変数のアドレスであり、\fIinbytesleft\fP は入力シー
ケンスのバッファのバイト数を示す。\fIoutbuf\fP 引き数は出力バッファで利用
できる先頭バイトを指す変数のアドレスであり、 \fIoutbytesleft\fP は出力
バッファのバイト数を示す。
.PP
主に使われるのは、 「\fIinbuf\fP が NULL でなく、かつ \fI*inbuf\fP が NULL でない」 という場合である。 この場合、
\fBiconv\fP() 関数は、 \fI*inbuf\fP で始まるマルチバイト文字列を \fI*outbuf\fP で始まるマルチバイト文字列に変換する。
\fI*inbuf\fP を先頭として最大 \fI*inbytesleft\fP バイトが読み込まれ、 \fI*outbuf\fP を先頭として最大
\fI*outbytesleft\fP バイトが書き出される。
.PP
\fBiconv\fP() 関数は 1 度に 1 つのマルチバイト文字を変換する。 そして、各文字変換毎に、変換された入力バイトの数だけ \fI*inbuf\fP
を増加させ、\fI*inbytesleft\fP を減少させる。 また、変換された出力バイトの数だけ \fI*outbuf\fP
を増加させ、\fI*outbytesleft\fP を減少させる。 さらに、\fIcd\fP に含まれる変換状態を更新する。
入力の文字エンコーディングがが状態を持つ場合、 \fBiconv\fP() 関数は入力バイトの列に対して変換にも対応しており、
バイト出力を伴わずに変換状態を更新することができる。 変換は、次の 4 つの場合に停止する。
.IP 1. 3
入力に無効なマルチバイト文字列があった場合。この場合、
関数は \fIerrno\fP を \fBEILSEQ\fP に設定し、 \fI(size_t)\ \-1\fP を返す。
\fI*inbuf\fP は、無効なマルチバイト文字列の先頭を指したままになる。
.IP 2.
入力バイト文字列が完全に変換され、\fI*inbytesleft\fP が 0 になった場合。
この場合、 \fBiconv\fP() は呼出しの間に非可逆変換が行われた回数を返す。
.IP 3.
入力に不完全なマルチバイト文字列があり、入力バイト文字列がその後で終了
している場合。この場合、関数は、\fIerrno\fP を \fBEINVAL\fP に設定し、
\fI(size_t)\ \-1\fP を返す。 \fI*inbuf\fP は、不完全なマルチバイト文字列の先頭
を指したままにされる。
.IP 4.
出力バッファーに次の変換された文字列のための空きがない場合。 この場合、
\fIerrno\fP が \fBE2BIG\fP に設定され、 \fI(size_t)\ \-1\fP が返される。
.PP
別のケースとしては、 「\fIinbuf\fP が NULL、または \fI*inbuf\fP が NULL である。 しかし、\fIoutbuf\fP が NULL
でなく、かつ \fI*outbuf\fP が NULL でない」 という場合がある。 この場合、 \fBiconv\fP() 関数は、\fIcd\fP
の変換状態を初期状態にして、 対応するシフト文字列を \fI*outbuf\fP に保存しようとする。 最大 \fI*outbytesleft\fP
バイトが、\fI*outbuf\fP を始めとして書き出される。 このリセットされた文字列に対して、出力バッファーに空きがない場合、 この関数は
\fIerrno\fP を \fBE2BIG\fP に設定し、 \fI(size_t)\ \-1\fP を返す。 それ以外の場合、この関数は、書き込まれたバイトの数だけ
\fI*outbuf\fP を増加させ、\fI*outbytesleft\fP を減少させる。
.PP
3 番目のケースしては、 「\fIinbuf\fP が NULL、または \fI*inbuf\fP が NULL である。 かつ、\fIoutbuf\fP が
NULL、または \fI*outbuf\fP が NULL である」 という場合がある。 この場合、 \fBiconv\fP() 関数は、\fIcd\fP
の変換状態を初期状態にする。
.SH 返り値
\fBiconv\fP() 関数は、呼出しの間に非可逆な方法で変換された文字数を返す。 つまり、可逆変換はカウントされない。 エラーの場合、この関数は
\fIerrno\fP を設定し、 \fI(size_t)\ \-1\fP を返す。
.SH エラー
他のいろいろなエラーのうちから、以下のエラーが起こりうる。
.TP
\fBE2BIG\fP
\fI*outbuf\fP に十分な空きがない。
.TP
\fBEILSEQ\fP
入力に無効なマルチバイト文字列があった。
.TP
\fBEINVAL\fP
入力に不完全なマルチバイト文字列があった。
.SH バージョン
この関数はバージョン 2.1 以降の glibc で利用可能である。
.SH 準拠
POSIX.1\-2001.
.SH 注意
\fIinbuf\fP と \fIoutbuf\fP は \fIchar\ **\fP 型だが、これらの変数が指す
オブジェクトが C の文字列、つまり文字の配列として解釈されることを意味
するわけではない。文字バイトシーケンスの解釈は変換関数の内部で行われる。
エンコーディングによっては、バイト 0 もマルチバイト文字の有効な
構成要素の場合がある。
\fBiconv\fP() の呼び出し元は、 \fBiconv\fP() に渡すポインタが、
必要な文字集合の文字にアクセスするのに適したものとなっていることを
保証しなければならない。これには、アライメントに関して厳しい制限が
あるプラットフォームにおいて正しいアライメントになっていることを
保証するといったことも含まれる。
.SH 関連項目
\fBiconv_close\fP(3), \fBiconv_open\fP(3)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。
|
