.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" 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.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   OpenGroup's Single UNIX specification
.\"     http://www.UNIX-systems.org/online.html
.\"
.\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
.\" and //IGNORE extensions for 'tocode'.
.\"
.\" Japanese Version Copyright (c) 2000 Yuichi SATO
.\"         all rights reserved.
.\" Translated Tue Jul 11 19:02:58 JST 2000
.\"         by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\" Updated 2007-06-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.50
.\"
.\"WORD:	allocate	割り当てる
.\"WORD:	descriptor	ディスクリプタ
.\"WORD:	conversion	変換
.\"WORD:	sequence	文字列
.\"
.TH ICONV_OPEN 3  2008-08-11 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O iconv_open \- allocate descriptor for character set conversion
iconv_open \- 文字セット変換のためのディスクリプタを割り当てる
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <iconv.h>
.sp
.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
.fi
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .BR iconv_open ()
.\"O function allocates a conversion descriptor suitable
.\"O for converting byte sequences from character encoding \fIfromcode\fP to
.\"O character encoding \fItocode\fP.
.BR iconv_open ()
関数は、文字エンコーディング \fIfromcode\fP から
文字エンコーディング \fItocode\fP へのバイト文字列変換に適した
変換ディスクリプタを割り当てる。
.PP
.\"O The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
.\"O combinations are system-dependent.
.\"O For the GNU C library, the permitted
.\"O values are listed by the \fBiconv \-\-list\fP command, and all combinations
.\"O of the listed values are supported.
\fIfromcode\fP と \fItocode\fP に使うことのできる値と、
サポートされる組み合わせは、システムに依存する。
GNU C ライブラリでは、使うことのできる値は
\fBiconv \-\-list\fP コマンドでリストされ、
リストされたすべての値の組み合わせがサポートされる。
.\"O Furthermore the GNU C library and the
.\"O GNU libiconv library support the following two suffixes:
さらに、 GNU C ライブラリと GNU libiconv ライブラリでは、
以下の接尾辞がサポートされている。
.TP
//TRANSLIT
.\"O When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
.\"O is activated.
.\"O This means that when a character cannot be represented in the
.\"O target character set, it can be approximated through one or several
.\"O similarly looking characters.
\fItocode\fP の後ろに文字列 "//TRANSLIT" が付いている場合、
翻訳 (transliteration) が有効になる。この場合、
変換先の文字セットで表現できない文字を、その文字と同じように見える
文字 (複数文字の場合もある) で表現することができる。
.TP
//IGNORE
.\"O When the string "//IGNORE" is appended to \fItocode\fP, characters that
.\"O cannot be represented in the target character set will be silently discarded.
\fItocode\fP の後ろに文字列 "//IGNORE" が付いている場合、
変換先の文字セットで表現できない文字は黙って無視される。
.PP
.\"O The resulting conversion descriptor can be used with
.\"O .BR iconv (3)
.\"O any number of times.
.\"O It remains valid until deallocated using
.\"O .BR iconv_close (3).
この関数を読んで得られた変換ディスクリプタは、
.BR iconv (3)
で
何度でも使うことができる。
これは
.BR iconv_close (3)
を使って解放されるまで有効である。
.PP
.\"O A conversion descriptor contains a conversion state.
.\"O After creation using
.\"O .BR iconv_open (),
.\"O the state is in the initial state.
.\"O Using
.\"O .BR iconv (3)
.\"O modifies the descriptor's conversion state.
.\"O (This implies that a conversion
.\"O descriptor can not be used in multiple threads simultaneously.)
.\"O To bring the state back to the initial state, use
.\"O .BR iconv (3)
.\"O with NULL as \fIinbuf\fP argument.
変換ディスクリプタは変換状態を持つ。
.BR iconv_open ()
を用いて生成された後、変換状態は初期状態である。
.BR iconv (3)
を使うことにより、ディスクリプタの変換状態が変更される。
(変換ディスクリプタはマルチスレッドで
同時に使うことができないことを意味している。)
変換状態を初期状態に戻すには、
\fIinbuf\fP 引き数を NULL として
.BR iconv (3)
を用いること。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O The
.\"O .BR iconv_open ()
.\"O function returns a freshly allocated conversion
.\"O descriptor.
.\"O In case of error, it sets \fIerrno\fP and returns
.\"O .IR (iconv_t)\ \-1 .
.BR iconv_open ()
関数は、新たに割り当てられた変換ディスクリプタを返す。
エラーの場合、この関数は \fIerrno\fP を設定し、
.I (iconv_t)\ \-1
を返す。
.\"O .SH ERRORS
.SH エラー
.\"O The following error can occur, among others:
.\"O .TP
.\"O .B EINVAL
.\"O The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
.\"O implementation.
他のいろいろなエラーのうち、以下のエラーが起こりうる。
.TP
.B EINVAL
\fIfromcode\fP から \fItocode\fP への変換は、この実装ではサポートされていない。
.\"O .SH VERSIONS
.SH バージョン
.\"O This function is available in glibc since version 2.1.
この関数はバージョン 2.1 以降の glibc で利用可能である。
.\"O .SH "CONFORMING TO"
.SH 準拠
UNIX98, POSIX.1-2001.
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR iconv (1),
.BR iconv (3),
.BR iconv_close (3)