man3/iconv_open.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   OpenGroup's Single UNIX specification
  13 .\"     http://www.UNIX-systems.org/online.html
  14 .\"
  15 .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
  16 .\" and //IGNORE extensions for 'tocode'.
  17 .\"
  18 .TH ICONV_OPEN 3  2015-08-08 "GNU" "Linux Programmer's Manual"
  19 .SH NAME
  20 iconv_open \- allocate descriptor for character set conversion
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <iconv.h>
  24 .sp
  25 .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR iconv_open ()
  30 function allocates a conversion descriptor suitable
  31 for converting byte sequences from character encoding
  32 .I fromcode
  33 to
  34 character encoding
  35 .IR tocode .
  36 .PP
  37 The values permitted for
  38 .IR fromcode
  39 and
  40 .I tocode
  41 and the supported
  42 combinations are system-dependent.
  43 For the GNU C library, the permitted
  44 values are listed by the
  45 .I "iconv \-\-list"
  46 command, and all combinations
  47 of the listed values are supported.
  48 Furthermore the GNU C library and the
  49 GNU libiconv library support the following two suffixes:
  50 .TP
  51 //TRANSLIT
  52 When the string "//TRANSLIT" is appended to
  53 .IR tocode ,
  54 transliteration
  55 is activated.
  56 This means that when a character cannot be represented in the
  57 target character set, it can be approximated through one or several
  58 similarly looking characters.
  59 .TP
  60 //IGNORE
  61 When the string "//IGNORE" is appended to
  62 .IR tocode ,
  63 characters that
  64 cannot be represented in the target character set will be silently discarded.
  65 .PP
  66 The resulting conversion descriptor can be used with
  67 .BR iconv (3)
  68 any number of times.
  69 It remains valid until deallocated using
  70 .BR iconv_close (3).
  71 .PP
  72 A conversion descriptor contains a conversion state.
  73 After creation using
  74 .BR iconv_open (),
  75 the state is in the initial state.
  76 Using
  77 .BR iconv (3)
  78 modifies the descriptor's conversion state.
  79 To bring the state back to the initial state, use
  80 .BR iconv (3)
  81 with NULL as
  82 .I inbuf
  83 argument.
  84 .SH RETURN VALUE
  85 The
  86 .BR iconv_open ()
  87 function returns a freshly allocated conversion
  88 descriptor.
  89 In case of error, it sets
  90 .I errno
  91 and returns
  92 .IR (iconv_t)\ \-1 .
  93 .SH ERRORS
  94 The following error can occur, among others:
  95 .TP
  96 .B EINVAL
  97 The conversion from
  98 .IR fromcode
  99 to
 100 .I tocode
 101 is not supported by the
 102 implementation.
 103 .SH VERSIONS
 104 This function is available in glibc since version 2.1.
 105 .SH ATTRIBUTES
 106 For an explanation of the terms used in this section, see
 107 .BR attributes (7).
 108 .TS
 109 allbox;
 110 lb lb lb
 111 l l l.
 112 Interface       Attribute       Value
 113 T{
 114 .BR iconv_open ()
 115 T}      Thread safety   MT-Safe locale
 116 .TE
 117
 118 .SH CONFORMING TO
 119 POSIX.1-2001, POSIX.1-2008, SUSv2.
 120 .SH SEE ALSO
 121 .BR iconv (1),
 122 .BR iconv (3),
 123 .BR iconv_close (3)