1iconv(3C)                Standard C Library Functions                iconv(3C)
2
3
4

NAME

6       iconv - code conversion function
7

SYNOPSIS

9   Default
10       #include <iconv.h>
11
12       extern size_t iconv(iconv_t cd, const char **restrict inbuf,
13            size_t *restrict inbytesleft, char **restrict outbuf,
14            size_t *restrict outbytesleft);
15
16
17   SUSv3
18       #include <iconv.h>
19
20       size_t iconv(iconv_t cd, char **restrict inbuf,
21            size_t *restrict inbytesleft, char **restrict outbuf,
22            size_t *restrict outbytesleft);
23
24

DESCRIPTION

26       The  iconv() function converts the sequence of characters from one code
27       set,  in the array specified by inbuf, into a sequence of corresponding
28       characters  in  another code set, in the array specified by outbuf. The
29       code sets are those specified in the iconv_open()  call  that  returned
30       the  conversion descriptor, cd. The inbuf argument points to a variable
31       that points to the first character in the input buffer and  inbytesleft
32       indicates the number of bytes to the end of the buffer to be converted.
33       The outbuf argument points to a  variable  that  points  to  the  first
34       available byte in the output buffer and outbytesleft indicates the num‐
35       ber of the available bytes to the end of the buffer.
36
37
38       For state-dependent encodings, the conversion descriptor cd  is  placed
39       into  its  initial  shift  state  by  a  call for which inbuf is a null
40       pointer, or for which inbuf points to a null pointer. When  iconv()  is
41       called  in  this way, and if  outbuf is not a null pointer or a pointer
42       to a null pointer, and outbytesleft points to a positive value, iconv()
43       will  place,  into  the output buffer,  the byte sequence to change the
44       output buffer to its initial shift state.  If the output buffer is  not
45       large  enough  to hold the entire reset sequence, iconv() will fail and
46       set  errno to E2BIG. Subsequent calls with inbuf as other than  a  null
47       pointer  or  a  pointer to a null pointer cause the  conversion to take
48       place from the current state of the conversion descriptor.
49
50
51       If a sequence of input bytes does not form a  valid  character  in  the
52       specified  code  set, conversion stops  after the previous successfully
53       converted character. If the input buffer ends with an incomplete  char‐
54       acter  or  shift sequence, conversion stops after the previous success‐
55       fully converted bytes. If the output buffer is not large enough to hold
56       the  entire  converted  input, conversion stops just prior to the input
57       bytes that would cause the output  buffer  to  overflow.  The  variable
58       pointed  to by inbuf is updated to point to the byte following the last
59       byte successfully used in the conversion.   The  value  pointed  to  by
60       inbytesleft  is  decremented  to  reflect the number of bytes still not
61       converted in the input buffer. The variable pointed  to  by  outbuf  is
62       updated  to point to the byte following the last byte of converted out‐
63       put data. The value  pointed  to  by  outbytesleft  is  decremented  to
64       reflect  the  number of bytes still available in the output buffer. For
65       state-dependent encodings, the  conversion  descriptor  is  updated  to
66       reflect  the shift state in effect at the end of the last  successfully
67       converted byte sequence.
68
69
70       If  iconv() encounters a character in the input buffer that  is  legal,
71       but  for which an identical character does not exist in the target code
72       set,  iconv() performs an  implementation-defined  conversion  on  this
73       character.
74

RETURN VALUES

76       The  iconv() function updates the variables pointed to by the arguments
77       to reflect the extent of the conversion and returns the number of  non-
78       identical  conversions  performed.   If  the entire string in the input
79       buffer is converted, the value pointed to by inbytesleft will be 0.  If
80       the  input conversion is stopped due to any conditions mentioned above,
81       the value pointed to by  inbytesleft will be non-zero and  errno is set
82       to indicate the condition.  If an error occurs iconv() returns (size_t)
83       −1 and sets errno to indicate the error.
84

ERRORS

86       The iconv() function will fail if:
87
88       EILSEQ    Input conversion stopped due to an input byte that  does  not
89                 belong to the input code set.
90
91
92       E2BIG     Input  conversion  stopped due to lack of space in the output
93                 buffer.
94
95
96       EINVAL    Input conversion stopped due to an incomplete   character  or
97                 shift sequence at the end of the input buffer.
98
99
100
101       The iconv() function may fail if:
102
103       EBADF    The cd argument is not a valid open conversion descriptor.
104
105

EXAMPLES

107       Example 1 Using the iconv() Functions
108
109
110       The following example uses the iconv() functions:
111
112
113         #include <stdio.h>
114         #include <errno.h>
115         #include <string.h>
116         #include <iconv.h>
117         #include <stdlib.h>
118
119         /*
120          * For state-dependent encodings, changes the state of the
121          * conversion descriptor to initial shift state.  Also, outputs
122          * the byte sequence to change the state to initial state.
123          * This code is assuming the iconv call for initializing the
124          * state will not fail due to lack of space in the output buffer.
125          */
126         #define INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft) \
127             { \
128                 fptr = NULL; \
129                 ileft = 0; \
130                 tptr = to; \
131                 oleft = BUFSIZ; \
132                 (void) iconv(cd, &fptr, &ileft, &tptr, &oleft); \
133                 (void) fwrite(to, 1, BUFSIZ - oleft, stdout); \
134             }
135
136         int
137         main(int argc, char **argv)
138         {
139             iconv_t cd;
140             char    from[BUFSIZ], to[BUFSIZ];
141             char    *from_code, *to_code;
142             char    *tptr;
143             const char  *fptr;
144             size_t  ileft, oleft, num, ret;
145
146
147             if (argc != 3) {
148                 (void) fprintf(stderr,
149                     "Usage: %s from_codeset to_codeset\\n", argv[0]);
150                 return (1);
151             }
152
153             from_code = argv[1];
154             to_code = argv[2];
155
156             cd = iconv_open((const char *)to_code, (const char *)from_code);
157             if (cd == (iconv_t)-1) {
158                 /*
159                  * iconv_open failed
160                  */
161                 (void) fprintf(stderr,
162                     "iconv_open(%s, %s) failed\\n", to_code, from_code);
163                 return (1);
164             }
165
166             ileft = 0;
167             while ((ileft +=
168                 (num = fread(from + ileft, 1, BUFSIZ - ileft, stdin))) > 0) {
169                 if (num == 0) {
170                     /*
171                      * Input buffer still contains incomplete character
172                      * or sequence.  However, no more input character.
173                      */
174
175                     /*
176                      * Initializes the conversion descriptor and outputs
177                      * the sequence to change the state to initial state.
178                      */
179                     INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
180                     (void) iconv_close(cd);
181
182                     (void) fprintf(stderr, "Conversion error\\n");
183                     return (1);
184                 }
185
186                 fptr = from;
187                 for (;;) {
188                     tptr = to;
189                     oleft = BUFSIZ;
190
191                     ret = iconv(cd, &fptr, &ileft, &tptr, &oleft);
192                     if (ret != (size_t)-1) {
193                         /*
194                          * iconv succeeded
195                          */
196
197                         /*
198                          * Outputs converted characters
199                          */
200                         (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
201                         break;
202                     }
203
204                     /*
205                      * iconv failed
206                      */
207                     if (errno == EINVAL) {
208                         /*
209                        * Incomplete character or shift sequence
210                          */
211
212                         /*
213                          * Outputs converted characters
214                          */
215                         (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
216                         /*
217                          * Copies remaining characters in input buffer
218                          * to the top of the input buffer.
219                          */
220                         (void) memmove(from, fptr, ileft);
221                         /*
222                          * Tries to fill input buffer from stdin
223                          */
224                         break;
225                     } else if (errno == E2BIG) {
226                         /*
227                          * Lack of space in output buffer
228                          */
229
230                         /*
231                          * Outputs converted characters
232                          */
233                         (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
234                         /*
235                          * Tries to convert remaining characters in
236                          * input buffer with emptied output buffer
237                          */
238                         continue;
239                     } else if (errno == EILSEQ) {
240                         /*
241                          * Illegal character or shift sequence
242                          */
243
244                         /*
245                          * Outputs converted characters
246                          */
247                         (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
248                         /*
249                          * Initializes the conversion descriptor and
250                          * outputs the sequence to change the state to
251                          * initial state.
252                          */
253                         INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
254                         (void) iconv_close(cd);
255
256                         (void) fprintf(stderr,
257                          "Illegal character or sequence\\n");
258                         return (1);
259                     } else if (errno == EBADF) {
260                         /*
261                          * Invalid conversion descriptor.
262                          * Actually, this shouldn't happen here.
263                          */
264                         (void) fprintf(stderr, "Conversion error\\n");
265                         return (1);
266                     } else {
267                         /*
268                          * This errno is not defined
269                          */
270                         (void) fprintf(stderr, "iconv error\\n");
271                         return (1);
272                     }
273                 }
274             }
275
276             /*
277              * Initializes the conversion descriptor and outputs
278              * the sequence to change the state to initial state.
279              */
280             INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
281
282             (void) iconv_close(cd);
283             return (0);
284         }
285
286

FILES

288       /usr/lib/iconv/*.so
289
290           conversion modules for 32-bit
291
292
293       /usr/lib/iconv/sparcv9/*.so
294
295           conversion modules for 64-bit sparc
296
297
298       /usr/lib/iconv/amd64/*.so
299
300           conversion modules for 64-bit amd64
301
302
303       /usr/lib/iconv/geniconvtbl/binarytables/*.bt
304
305           conversion binary tables
306
307

ATTRIBUTES

309       See attributes(5) for descriptions of the following attributes:
310
311
312
313
314       ┌─────────────────────────────┬─────────────────────────────┐
315       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
316       ├─────────────────────────────┼─────────────────────────────┤
317       │Interface Stability          │Standard                     │
318       ├─────────────────────────────┼─────────────────────────────┤
319       │MT-Level                     │MT-Safe                      │
320       └─────────────────────────────┴─────────────────────────────┘
321

SEE ALSO

323       geniconvtbl(1),  iconv(1),  iconv_close(3C),  iconv_open(3C),  genicon‐
324       vtbl(4), attributes(5), iconv(5), iconv_unicode(5), standards(5)
325
326
327
328SunOS 5.11                        6 Oct 2004                         iconv(3C)
Impressum