1explain_iconv(3) Library Functions Manual explain_iconv(3)
2
6 explain_iconv - explain iconv(3) errors
7
9 #include <libexplain/iconv.h>
10 const char *explain_iconv(iconv_t cd, char **inbuf, size_t
11 *inbytesleft, char **outbuf, size_t *outbytesleft);
12 const char *explain_errno_iconv(int errnum, iconv_t cd, char **inbuf,
13 size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
14 void explain_message_iconv(char *message, int message_size, iconv_t cd,
15 char **inbuf, size_t *inbytesleft, char **outbuf, size_t *out‐
16 bytesleft);
17 void explain_message_errno_iconv(char *message, int message_size, int
18 errnum, iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf,
19 size_t *outbytesleft);
20
22 These functions may be used to obtain explanations for errors returned
23 by the iconv(3) system call.
24 explain_iconv
26 const char *explain_iconv(iconv_t cd, char **inbuf, size_t
27 *inbytesleft, char **outbuf, size_t *outbytesleft);
28 The explain_iconv function is used to obtain an explanation of an error
30 returned by the iconv(3) system call. The least the message will con‐
31 tain is the value of strerror(errno), but usually it will do much bet‐
32 ter, and indicate the underlying cause in more detail.
33 The errno global variable will be used to obtain the error value to be
35 decoded.
36 cd The original cd, exactly as passed to the iconv(3) system call.
38 inbuf The original inbuf, exactly as passed to the iconv(3) system
40 call.
41 inbytesleft
43 The original inbytesleft, exactly as passed to the iconv(3)
44 system call.
45 outbuf The original outbuf, exactly as passed to the iconv(3) system
47 call.
48 outbytesleft
50 The original outbytesleft, exactly as passed to the iconv(3)
51 system call.
52 Returns:
54 The message explaining the error. This message buffer is shared
55 by all libexplain functions which do not supply a buffer in
56 their argument list. This will be overwritten by the next call
57 to any libexplain function which shares this buffer, including
58 other threads.
59 Note: This function is not thread safe, because it shares a return buf‐
61 fer across all threads, and many other functions in this library.
62 Example: This function is intended to be used in a fashion similar to
64 the following example:
65 errno = 0;
66 size_t result = iconv(cd, inbuf, inbytesleft, outbuf, out‐
67 bytesleft);
68 if (result < 0 && errno != 0)
69 {
70 fprintf(stderr, "%s\n", explain_iconv(cd, inbuf,
71 inbytesleft, outbuf, outbytesleft));
72 exit(EXIT_FAILURE);
73 }
74 The above code example is available pre-packaged as the
76 explain_iconv_or_die(3) function.
77 explain_errno_iconv
79 const char *explain_errno_iconv(int errnum, iconv_t cd, char **inbuf,
80 size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
81 The explain_errno_iconv function is used to obtain an explanation of an
83 error returned by the iconv(3) system call. The least the message will
84 contain is the value of strerror(errno), but usually it will do much
85 better, and indicate the underlying cause in more detail.
86 errnum The error value to be decoded, usually obtained from the errno
88 global variable just before this function is called. This is
89 necessary if you need to call any code between the system call
90 to be explained and this function, because many libc functions
91 will alter the value of errno.
92 cd The original cd, exactly as passed to the iconv(3) system call.
94 inbuf The original inbuf, exactly as passed to the iconv(3) system
96 call.
97 inbytesleft
99 The original inbytesleft, exactly as passed to the iconv(3)
100 system call.
101 outbuf The original outbuf, exactly as passed to the iconv(3) system
103 call.
104 outbytesleft
106 The original outbytesleft, exactly as passed to the iconv(3)
107 system call.
108 Returns:
110 The message explaining the error. This message buffer is shared
111 by all libexplain functions which do not supply a buffer in
112 their argument list. This will be overwritten by the next call
113 to any libexplain function which shares this buffer, including
114 other threads.
115 Note: This function is not thread safe, because it shares a return buf‐
117 fer across all threads, and many other functions in this library.
118 Example: This function is intended to be used in a fashion similar to
120 the following example:
121 errno = 0;
122 size_t result = iconv(cd, inbuf, inbytesleft, outbuf, out‐
123 bytesleft);
124 if (result < 0 && errno != 0)
125 {
126 int err = errno;
127 fprintf(stderr, "%s\n", explain_errno_iconv(err, cd, inbuf,
128 inbytesleft, outbuf, outbytesleft));
129 exit(EXIT_FAILURE);
130 }
131 The above code example is available pre-packaged as the
133 explain_iconv_or_die(3) function.
134 explain_message_iconv
136 void explain_message_iconv(char *message, int message_size, iconv_t cd,
137 char **inbuf, size_t *inbytesleft, char **outbuf, size_t *out‐
138 bytesleft);
139 The explain_message_iconv function is used to obtain an explanation of
141 an error returned by the iconv(3) system call. The least the message
142 will contain is the value of strerror(errno), but usually it will do
143 much better, and indicate the underlying cause in more detail.
144 The errno global variable will be used to obtain the error value to be
146 decoded.
147 message The location in which to store the returned message. If a suit‐
149 able message return buffer is supplied, this function is thread
150 safe.
151 message_size
153 The size in bytes of the location in which to store the
154 returned message.
155 cd The original cd, exactly as passed to the iconv(3) system call.
157 inbuf The original inbuf, exactly as passed to the iconv(3) system
159 call.
160 inbytesleft
162 The original inbytesleft, exactly as passed to the iconv(3)
163 system call.
164 outbuf The original outbuf, exactly as passed to the iconv(3) system
166 call.
167 outbytesleft
169 The original outbytesleft, exactly as passed to the iconv(3)
170 system call.
171 Example: This function is intended to be used in a fashion similar to
173 the following example:
174 errno = 0;
175 size_t result = iconv(cd, inbuf, inbytesleft, outbuf, out‐
176 bytesleft);
177 if (result < 0 && errno != 0)
178 {
179 char message[3000];
180 explain_message_iconv(message, sizeof(message), cd, inbuf,
181 inbytesleft, outbuf, outbytesleft);
182 fprintf(stderr, "%s\n", message);
183 exit(EXIT_FAILURE);
184 }
185 The above code example is available pre-packaged as the
187 explain_iconv_or_die(3) function.
188 explain_message_errno_iconv
190 void explain_message_errno_iconv(char *message, int message_size, int
191 errnum, iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf,
192 size_t *outbytesleft);
193 The explain_message_errno_iconv function is used to obtain an explana‐
195 tion of an error returned by the iconv(3) system call. The least the
196 message will contain is the value of strerror(errno), but usually it
197 will do much better, and indicate the underlying cause in more detail.
198 message The location in which to store the returned message. If a suit‐
200 able message return buffer is supplied, this function is thread
201 safe.
202 message_size
204 The size in bytes of the location in which to store the
205 returned message.
206 errnum The error value to be decoded, usually obtained from the errno
208 global variable just before this function is called. This is
209 necessary if you need to call any code between the system call
210 to be explained and this function, because many libc functions
211 will alter the value of errno.
212 cd The original cd, exactly as passed to the iconv(3) system call.
214 inbuf The original inbuf, exactly as passed to the iconv(3) system
216 call.
217 inbytesleft
219 The original inbytesleft, exactly as passed to the iconv(3)
220 system call.
221 outbuf The original outbuf, exactly as passed to the iconv(3) system
223 call.
224 outbytesleft
226 The original outbytesleft, exactly as passed to the iconv(3)
227 system call.
228 Example: This function is intended to be used in a fashion similar to
230 the following example:
231 errno = 0;
232 size_t result = iconv(cd, inbuf, inbytesleft, outbuf, out‐
233 bytesleft);
234 if (result < 0 && errno != 0)
235 {
236 int err = errno;
237 char message[3000];
238 explain_message_errno_iconv(message, sizeof(message), err,
239 cd, inbuf, inbytesleft, outbuf, outbytesleft);
240 fprintf(stderr, "%s\n", message);
241 exit(EXIT_FAILURE);
242 }
243 The above code example is available pre-packaged as the
245 explain_iconv_or_die(3) function.
246
248 iconv(3)
249 perform character set conversion
250 explain_iconv_or_die(3)
252 perform character set conversion and report errors
253
255 libexplain version 1.4
256 Copyright (C) 2013 Peter Miller
257 explain_iconv(3)