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