draft/man3/iconv_open.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   OpenGroup's Single UNIX specification
  11 .\"     http://www.UNIX-systems.org/online.html
  12 .\"
  13 .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
  14 .\" and //IGNORE extensions for 'tocode'.
  15 .\"
  16 .\" Japanese Version Copyright (c) 2000 Yuichi SATO
  17 .\"         all rights reserved.
  18 .\" Translated Tue Jul 11 19:02:58 JST 2000
  19 .\"         by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
  20 .\" Updated 2007-06-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.50
  21 .\"
  22 .\"WORD:        allocate        割り当てる
  23 .\"WORD:        descriptor      ディスクリプタ
  24 .\"WORD:        conversion      変換
  25 .\"WORD:        sequence        文字列
  26 .\"
  27 .TH ICONV_OPEN 3  2008-08-11 "GNU" "Linux Programmer's Manual"
  28 .\"O .SH NAME
  29 .SH 名前
  30 .\"O iconv_open \- allocate descriptor for character set conversion
  31 iconv_open \- 文字セット変換のためのディスクリプタを割り当てる
  32 .\"O .SH SYNOPSIS
  33 .SH 書式
  34 .nf
  35 .B #include <iconv.h>
  36 .sp
  37 .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
  38 .fi
  39 .\"O .SH DESCRIPTION
  40 .SH 説明
  41 .\"O The
  42 .\"O .BR iconv_open ()
  43 .\"O function allocates a conversion descriptor suitable
  44 .\"O for converting byte sequences from character encoding \fIfromcode\fP to
  45 .\"O character encoding \fItocode\fP.
  46 .BR iconv_open ()
  47 関数は、文字エンコーディング \fIfromcode\fP から
  48 文字エンコーディング \fItocode\fP へのバイト文字列変換に適した
  49 変換ディスクリプタを割り当てる。
  50 .PP
  51 .\"O The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
  52 .\"O combinations are system-dependent.
  53 .\"O For the GNU C library, the permitted
  54 .\"O values are listed by the \fBiconv \-\-list\fP command, and all combinations
  55 .\"O of the listed values are supported.
  56 \fIfromcode\fP と \fItocode\fP に使うことのできる値と、
  57 サポートされる組み合わせは、システムに依存する。
  58 GNU C ライブラリでは、使うことのできる値は
  59 \fBiconv \-\-list\fP コマンドでリストされ、
  60 リストされたすべての値の組み合わせがサポートされる。
  61 .\"O Furthermore the GNU C library and the
  62 .\"O GNU libiconv library support the following two suffixes:
  63 さらに、 GNU C ライブラリと GNU libiconv ライブラリでは、
  64 以下の接尾辞がサポートされている。
  65 .TP
  66 //TRANSLIT
  67 .\"O When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
  68 .\"O is activated.
  69 .\"O This means that when a character cannot be represented in the
  70 .\"O target character set, it can be approximated through one or several
  71 .\"O similarly looking characters.
  72 \fItocode\fP の後ろに文字列 "//TRANSLIT" が付いている場合、
  73 翻訳 (transliteration) が有効になる。この場合、
  74 変換先の文字セットで表現できない文字を、その文字と同じように見える
  75 文字 (複数文字の場合もある) で表現することができる。
  76 .TP
  77 //IGNORE
  78 .\"O When the string "//IGNORE" is appended to \fItocode\fP, characters that
  79 .\"O cannot be represented in the target character set will be silently discarded.
  80 \fItocode\fP の後ろに文字列 "//IGNORE" が付いている場合、
  81 変換先の文字セットで表現できない文字は黙って無視される。
  82 .PP
  83 .\"O The resulting conversion descriptor can be used with
  84 .\"O .BR iconv (3)
  85 .\"O any number of times.
  86 .\"O It remains valid until deallocated using
  87 .\"O .BR iconv_close (3).
  88 この関数を読んで得られた変換ディスクリプタは、
  89 .BR iconv (3)
  90 で
  91 何度でも使うことができる。
  92 これは
  93 .BR iconv_close (3)
  94 を使って解放されるまで有効である。
  95 .PP
  96 .\"O A conversion descriptor contains a conversion state.
  97 .\"O After creation using
  98 .\"O .BR iconv_open (),
  99 .\"O the state is in the initial state.
 100 .\"O Using
 101 .\"O .BR iconv (3)
 102 .\"O modifies the descriptor's conversion state.
 103 .\"O (This implies that a conversion
 104 .\"O descriptor can not be used in multiple threads simultaneously.)
 105 .\"O To bring the state back to the initial state, use
 106 .\"O .BR iconv (3)
 107 .\"O with NULL as \fIinbuf\fP argument.
 108 変換ディスクリプタは変換状態を持つ。
 109 .BR iconv_open ()
 110 を用いて生成された後、変換状態は初期状態である。
 111 .BR iconv (3)
 112 を使うことにより、ディスクリプタの変換状態が変更される。
 113 (変換ディスクリプタはマルチスレッドで
 114 同時に使うことができないことを意味している。)
 115 変換状態を初期状態に戻すには、
 116 \fIinbuf\fP 引き数を NULL として
 117 .BR iconv (3)
 118 を用いること。
 119 .\"O .SH "RETURN VALUE"
 120 .SH 返り値
 121 .\"O The
 122 .\"O .BR iconv_open ()
 123 .\"O function returns a freshly allocated conversion
 124 .\"O descriptor.
 125 .\"O In case of error, it sets \fIerrno\fP and returns
 126 .\"O .IR (iconv_t)\ \-1 .
 127 .BR iconv_open ()
 128 関数は、新たに割り当てられた変換ディスクリプタを返す。
 129 エラーの場合、この関数は \fIerrno\fP を設定し、
 130 .I (iconv_t)\ \-1
 131 を返す。
 132 .\"O .SH ERRORS
 133 .SH エラー
 134 .\"O The following error can occur, among others:
 135 .\"O .TP
 136 .\"O .B EINVAL
 137 .\"O The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
 138 .\"O implementation.
 139 他のいろいろなエラーのうち、以下のエラーが起こりうる。
 140 .TP
 141 .B EINVAL
 142 \fIfromcode\fP から \fItocode\fP への変換は、この実装ではサポートされていない。
 143 .\"O .SH VERSIONS
 144 .SH バージョン
 145 .\"O This function is available in glibc since version 2.1.
 146 この関数はバージョン 2.1 以降の glibc で利用可能である。
 147 .\"O .SH "CONFORMING TO"
 148 .SH 準拠
 149 UNIX98, POSIX.1-2001.
 150 .\"O .SH "SEE ALSO"
 151 .SH 関連項目
 152 .BR iconv (1),
 153 .BR iconv (3),
 154 .BR iconv_close (3)