original/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  2008-08-11 "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 \fIfromcode\fP to
  32 character encoding \fItocode\fP.
  33 .PP
  34 The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
  35 combinations are system-dependent.
  36 For the GNU C library, the permitted
  37 values are listed by the \fBiconv \-\-list\fP command, and all combinations
  38 of the listed values are supported.
  39 Furthermore the GNU C library and the
  40 GNU libiconv library support the following two suffixes:
  41 .TP
  42 //TRANSLIT
  43 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
  44 is activated.
  45 This means that when a character cannot be represented in the
  46 target character set, it can be approximated through one or several
  47 similarly looking characters.
  48 .TP
  49 //IGNORE
  50 When the string "//IGNORE" is appended to \fItocode\fP, characters that
  51 cannot be represented in the target character set will be silently discarded.
  52 .PP
  53 The resulting conversion descriptor can be used with
  54 .BR iconv (3)
  55 any number of times.
  56 It remains valid until deallocated using
  57 .BR iconv_close (3).
  58 .PP
  59 A conversion descriptor contains a conversion state.
  60 After creation using
  61 .BR iconv_open (),
  62 the state is in the initial state.
  63 Using
  64 .BR iconv (3)
  65 modifies the descriptor's conversion state.
  66 (This implies that a conversion
  67 descriptor can not be used in multiple threads simultaneously.)
  68 To bring the state back to the initial state, use
  69 .BR iconv (3)
  70 with NULL as \fIinbuf\fP argument.
  71 .SH RETURN VALUE
  72 The
  73 .BR iconv_open ()
  74 function returns a freshly allocated conversion
  75 descriptor.
  76 In case of error, it sets \fIerrno\fP and returns
  77 .IR (iconv_t)\ \-1 .
  78 .SH ERRORS
  79 The following error can occur, among others:
  80 .TP
  81 .B EINVAL
  82 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
  83 implementation.
  84 .SH VERSIONS
  85 This function is available in glibc since version 2.1.
  86 .SH CONFORMING TO
  87 UNIX98, POSIX.1-2001.
  88 .SH SEE ALSO
  89 .BR iconv (1),
  90 .BR iconv (3),
  91 .BR iconv_close (3)