1explain_iconv_open(3) Library Functions Manual explain_iconv_open(3)
2
6 explain_iconv_open - explain iconv_open(3) errors
7
9 #include <libexplain/iconv_open.h>
10 const char *explain_iconv_open(const char *tocode, const char *from‐
11 code);
12 const char *explain_errno_iconv_open(int errnum, const char *tocode,
13 const char *fromcode);
14 void explain_message_iconv_open(char *message, int message_size, const
15 char *tocode, const char *fromcode);
16 void explain_message_errno_iconv_open(char *message, int message_size,
17 int errnum, const char *tocode, const char *fromcode);
18
20 These functions may be used to obtain explanations for errors returned
21 by the iconv_open(3) system call.
22 explain_iconv_open
24 const char *explain_iconv_open(const char *tocode, const char *from‐
25 code);
26 The explain_iconv_open function is used to obtain an explanation of an
28 error returned by the iconv_open(3) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 tocode The original tocode, exactly as passed to the iconv_open(3)
36 system call.
37 fromcode
39 The original fromcode, exactly as passed to the iconv_open(3)
40 system call.
41 Returns:
43 The message explaining the error. This message buffer is shared
44 by all libexplain functions which do not supply a buffer in
45 their argument list. This will be overwritten by the next call
46 to any libexplain function which shares this buffer, including
47 other threads.
48 Note: This function is not thread safe, because it shares a return buf‐
50 fer across all threads, and many other functions in this library.
51 Example: This function is intended to be used in a fashion similar to
53 the following example:
54 iconv_t result = iconv_open(tocode, fromcode);
55 if (result < 0)
56 {
57 fprintf(stderr, "%s\n", explain_iconv_open(tocode, from‐
58 code));
59 exit(EXIT_FAILURE);
60 }
61 The above code example is available pre-packaged as the
63 explain_iconv_open_or_die(3) function.
64 explain_errno_iconv_open
66 const char *explain_errno_iconv_open(int errnum, const char *tocode,
67 const char *fromcode);
68 The explain_errno_iconv_open function is used to obtain an explanation
70 of an error returned by the iconv_open(3) system call. The least the
71 message will contain is the value of strerror(errno), but usually it
72 will do much better, and indicate the underlying cause in more detail.
73 errnum The error value to be decoded, usually obtained from the errno
75 global variable just before this function is called. This is
76 necessary if you need to call any code between the system call
77 to be explained and this function, because many libc functions
78 will alter the value of errno.
79 tocode The original tocode, exactly as passed to the iconv_open(3)
81 system call.
82 fromcode
84 The original fromcode, exactly as passed to the iconv_open(3)
85 system call.
86 Returns:
88 The message explaining the error. This message buffer is shared
89 by all libexplain functions which do not supply a buffer in
90 their argument list. This will be overwritten by the next call
91 to any libexplain function which shares this buffer, including
92 other threads.
93 Note: This function is not thread safe, because it shares a return buf‐
95 fer across all threads, and many other functions in this library.
96 Example: This function is intended to be used in a fashion similar to
98 the following example:
99 iconv_t result = iconv_open(tocode, fromcode);
100 if (result < 0)
101 {
102 int err = errno;
103 fprintf(stderr, "%s\n", explain_errno_iconv_open(err,
104 tocode, fromcode));
105 exit(EXIT_FAILURE);
106 }
107 The above code example is available pre-packaged as the
109 explain_iconv_open_or_die(3) function.
110 explain_message_iconv_open
112 void explain_message_iconv_open(char *message, int message_size, const
113 char *tocode, const char *fromcode);
114 The explain_message_iconv_open function is used to obtain an explana‐
116 tion of an error returned by the iconv_open(3) system call. The least
117 the message will contain is the value of strerror(errno), but usually
118 it will do much better, and indicate the underlying cause in more
119 detail.
120 The errno global variable will be used to obtain the error value to be
122 decoded.
123 message The location in which to store the returned message. If a suit‐
125 able message return buffer is supplied, this function is thread
126 safe.
127 message_size
129 The size in bytes of the location in which to store the
130 returned message.
131 tocode The original tocode, exactly as passed to the iconv_open(3)
133 system call.
134 fromcode
136 The original fromcode, exactly as passed to the iconv_open(3)
137 system call.
138 Example: This function is intended to be used in a fashion similar to
140 the following example:
141 iconv_t result = iconv_open(tocode, fromcode);
142 if (result < 0)
143 {
144 char message[3000];
145 explain_message_iconv_open(message, sizeof(message), tocode,
146 fromcode);
147 fprintf(stderr, "%s\n", message);
148 exit(EXIT_FAILURE);
149 }
150 The above code example is available pre-packaged as the
152 explain_iconv_open_or_die(3) function.
153 explain_message_errno_iconv_open
155 void explain_message_errno_iconv_open(char *message, int message_size,
156 int errnum, const char *tocode, const char *fromcode);
157 The explain_message_errno_iconv_open function is used to obtain an
159 explanation of an error returned by the iconv_open(3) system call. The
160 least the message will contain is the value of strerror(errno), but
161 usually it will do much better, and indicate the underlying cause in
162 more detail.
163 message The location in which to store the returned message. If a suit‐
165 able message return buffer is supplied, this function is thread
166 safe.
167 message_size
169 The size in bytes of the location in which to store the
170 returned message.
171 errnum The error value to be decoded, usually obtained from the errno
173 global variable just before this function is called. This is
174 necessary if you need to call any code between the system call
175 to be explained and this function, because many libc functions
176 will alter the value of errno.
177 tocode The original tocode, exactly as passed to the iconv_open(3)
179 system call.
180 fromcode
182 The original fromcode, exactly as passed to the iconv_open(3)
183 system call.
184 Example: This function is intended to be used in a fashion similar to
186 the following example:
187 iconv_t result = iconv_open(tocode, fromcode);
188 if (result < 0)
189 {
190 int err = errno;
191 char message[3000];
192 explain_message_errno_iconv_open(message, sizeof(message),
193 err, tocode, fromcode);
194 fprintf(stderr, "%s\n", message);
195 exit(EXIT_FAILURE);
196 }
197 The above code example is available pre-packaged as the
199 explain_iconv_open_or_die(3) function.
200
202 iconv_open(3)
203 allocate descriptor for character set conversion
204 explain_iconv_open_or_die(3)
206 allocate descriptor for character set conversion and report
207 errors
208
210 libexplain version 1.4
211 Copyright (C) 2013 Peter Miller
212 explain_iconv_open(3)