| | 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) |
projects / thirdparty / man-pages.git / blame_incremental