man3/iconv_open.3

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