1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>gmime-iconv</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="index.html" title="GMime 2.6 Reference Manual">
8 <link rel="up" href="core.html" title="Part III. GMime Core Reference">
9 <link rel="prev" href="gmime-gmime-charset.html" title="gmime-charset">
10 <link rel="next" href="gmime-gmime-iconv-utils.html" title="gmime-iconv-utils">
11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17 <td><a accesskey="p" href="gmime-gmime-charset.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">GMime 2.6 Reference Manual</th>
21 <td><a accesskey="n" href="gmime-gmime-iconv-utils.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#gmime-gmime-iconv.synopsis" class="shortcut">Top</a>
26 <a href="#gmime-gmime-iconv.description" class="shortcut">Description</a>
29 <div class="refentry">
30 <a name="gmime-gmime-iconv"></a><div class="titlepage"></div>
31 <div class="refnamediv"><table width="100%"><tr>
33 <h2><span class="refentrytitle"><a name="gmime-gmime-iconv.top_of_page"></a>gmime-iconv</span></h2>
34 <p>gmime-iconv — Low-level routines for converting text from one charset to another</p>
36 <td valign="top" align="right"></td>
38 <div class="refsynopsisdiv">
39 <a name="gmime-gmime-iconv.synopsis"></a><h2>Synopsis</h2>
40 <pre class="synopsis"><span class="returnvalue">void</span> <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-init" title="g_mime_iconv_init ()">g_mime_iconv_init</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
41 <span class="returnvalue">void</span> <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-shutdown" title="g_mime_iconv_shutdown ()">g_mime_iconv_shutdown</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
42 <span class="returnvalue">iconv_t</span> <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-open" title="g_mime_iconv_open ()">g_mime_iconv_open</a> (<em class="parameter"><code>const <span class="type">char</span> *to</code></em>,
43 <em class="parameter"><code>const <span class="type">char</span> *from</code></em>);
44 #define <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()">g_mime_iconv</a> (cd,
49 <span class="returnvalue">int</span> <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-close" title="g_mime_iconv_close ()">g_mime_iconv_close</a> (<em class="parameter"><code><span class="type">iconv_t</span> cd</code></em>);
52 <div class="refsect1">
53 <a name="gmime-gmime-iconv.description"></a><h2>Description</h2>
55 These functions are wrappers around the system iconv(3)
56 routines. The purpose of these wrappers are two-fold:
59 1. Cache iconv_t descriptors for you in order to optimize
60 opening/closing many descriptors frequently
66 2. To use the appropriate system charset alias for the MIME charset
67 names given as arguments.
70 <div class="refsect1">
71 <a name="gmime-gmime-iconv.details"></a><h2>Details</h2>
72 <div class="refsect2">
73 <a name="g-mime-iconv-init"></a><h3>g_mime_iconv_init ()</h3>
74 <pre class="programlisting"><span class="returnvalue">void</span> g_mime_iconv_init (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
76 Initialize GMime's iconv cache. This *MUST* be called before any
77 gmime-iconv interfaces will work correctly.
80 Note: this function is called for you by <a class="link" href="gmime-gmime.html#g-mime-init" title="g_mime_init ()"><code class="function">g_mime_init()</code></a>.
84 <div class="refsect2">
85 <a name="g-mime-iconv-shutdown"></a><h3>g_mime_iconv_shutdown ()</h3>
86 <pre class="programlisting"><span class="returnvalue">void</span> g_mime_iconv_shutdown (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
88 Frees internal iconv caches created in <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-init" title="g_mime_iconv_init ()"><code class="function">g_mime_iconv_init()</code></a>.
91 Note: this function is called for you by <a class="link" href="gmime-gmime.html#g-mime-shutdown" title="g_mime_shutdown ()"><code class="function">g_mime_shutdown()</code></a>.
95 <div class="refsect2">
96 <a name="g-mime-iconv-open"></a><h3>g_mime_iconv_open ()</h3>
97 <pre class="programlisting"><span class="returnvalue">iconv_t</span> g_mime_iconv_open (<em class="parameter"><code>const <span class="type">char</span> *to</code></em>,
98 <em class="parameter"><code>const <span class="type">char</span> *from</code></em>);</pre>
100 Allocates a coversion descriptor suitable for converting byte
101 sequences from charset <em class="parameter"><code>from</code></em> to charset <em class="parameter"><code>to</code></em>. The resulting
102 descriptor can be used with <code class="function">iconv()</code> (or the <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><code class="function">g_mime_iconv()</code></a> wrapper) any
103 number of times until closed using <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-close" title="g_mime_iconv_close ()"><code class="function">g_mime_iconv_close()</code></a>.
106 See the manual page for iconv_open(3) for further details.
108 <div class="variablelist"><table border="0">
109 <col align="left" valign="top">
112 <td><p><span class="term"><em class="parameter"><code>to</code></em> :</span></p></td>
113 <td>charset to convert to</td>
116 <td><p><span class="term"><em class="parameter"><code>from</code></em> :</span></p></td>
117 <td>charset to convert from</td>
120 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
121 <td>a new conversion descriptor for use with <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><code class="function">g_mime_iconv()</code></a> on
122 success or (iconv_t) <code class="literal">-1</code> on fail as well as setting an appropriate
129 <div class="refsect2">
130 <a name="g-mime-iconv"></a><h3>g_mime_iconv()</h3>
131 <pre class="programlisting">#define g_mime_iconv(cd,inbuf,inleft,outbuf,outleft)</pre>
133 The argument <em class="parameter"><code>cd</code></em> must be a conversion descriptor created using the
134 function <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-open" title="g_mime_iconv_open ()"><span class="type">g_mime_iconv_open</span></a>.
137 The main case is when <em class="parameter"><code>inbuf</code></em> is not <code class="literal">NULL</code> and *inbuf is not
138 <code class="literal">NULL</code>. In this case, the <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function converts the
139 multibyte sequence starting at *inbuf to a multibyte sequence
140 starting at *outbuf. At most *inleft bytes, starting at *inbuf,
141 will be read. At most *outleft bytes, starting at *outbuf, will
145 The <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function converts one multibyte character at a
146 time, and for each character conversion it increments *inbuf and
147 decrements *inleft by the number of converted input bytes, it
148 increments *outbuf and decrements *outleft by the number of
149 converted output bytes, and it updates the conversion state
150 contained in <em class="parameter"><code>cd</code></em>. The conversion can stop for four reasons:
153 1. An invalid multibyte sequence is encountered in the input. In
154 this case it sets errno to <code class="literal">EILSEQ</code> and returns (size_t)(-1).
155 *inbuf is left pointing to the beginning of the invalid multibyte
159 2. The input byte sequence has been entirely converted, i.e.
160 *inleft has gone down to <code class="literal">0</code>. In this case <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> returns
161 the number of non-reversible conversions performed during this
165 3. An incomplete multibyte sequence is encountered in the input,
166 and the input byte sequence terminates after it. In this case it
167 sets errno to <code class="literal">EINVAL</code> and returns (size_t)(-1). *inbuf is left
168 pointing to the beginning of the incomplete multibyte sequence.
171 4. The output buffer has no more room for the next converted
172 character. In this case it sets errno to <code class="literal">E2BIG</code> and returns
176 A different case is when <em class="parameter"><code>inbuf</code></em> is <code class="literal">NULL</code> or *inbuf is <code class="literal">NULL</code>, but
177 <em class="parameter"><code>outbuf</code></em> is not <code class="literal">NULL</code> and *outbuf is not <code class="literal">NULL</code>. In this case, the
178 <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function attempts to set <em class="parameter"><code>cd</code></em>'s conversion state to
179 the initial state and store a corresponding shift sequence at
180 *outbuf. At most *outleft bytes, starting at *outbuf, will be
181 written. If the output buffer has no more room for this reset
182 sequence, it sets errno to <code class="literal">E2BIG</code> and returns (size_t)(-1).
183 Otherwise it increments *outbuf and decrements *outleft by the
184 number of bytes written.
187 A third case is when <em class="parameter"><code>inbuf</code></em> is <code class="literal">NULL</code> or *inbuf is <code class="literal">NULL</code>, and
188 <em class="parameter"><code>outbuf</code></em> is <code class="literal">NULL</code> or *outbuf is <code class="literal">NULL</code>. In this case, the
189 <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function sets <em class="parameter"><code>cd</code></em>'s conversion state to the initial
192 <div class="variablelist"><table border="0">
193 <col align="left" valign="top">
196 <td><p><span class="term"><em class="parameter"><code>cd</code></em> :</span></p></td>
197 <td>iconv_t conversion descriptor</td>
200 <td><p><span class="term"><em class="parameter"><code>inbuf</code></em> :</span></p></td>
201 <td>input buffer</td>
204 <td><p><span class="term"><em class="parameter"><code>inleft</code></em> :</span></p></td>
205 <td>number of bytes left in <em class="parameter"><code>inbuf</code></em>
209 <td><p><span class="term"><em class="parameter"><code>outbuf</code></em> :</span></p></td>
210 <td>output buffer</td>
213 <td><p><span class="term"><em class="parameter"><code>outleft</code></em> :</span></p></td>
214 <td>number of bytes left in <em class="parameter"><code>outbuf</code></em>
218 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
219 <td>the number of characters converted in a nonreversible way
220 during this call; reversible conversions are not counted. In case
221 of error, it sets errno and returns (size_t)(-1).</td>
227 <div class="refsect2">
228 <a name="g-mime-iconv-close"></a><h3>g_mime_iconv_close ()</h3>
229 <pre class="programlisting"><span class="returnvalue">int</span> g_mime_iconv_close (<em class="parameter"><code><span class="type">iconv_t</span> cd</code></em>);</pre>
231 Closes the iconv descriptor <em class="parameter"><code>cd</code></em>.
234 See the manual page for iconv_close(3) for further details.
236 <div class="variablelist"><table border="0">
237 <col align="left" valign="top">
240 <td><p><span class="term"><em class="parameter"><code>cd</code></em> :</span></p></td>
241 <td>iconv conversion descriptor</td>
244 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
246 <code class="literal">0</code> on success or <code class="literal">-1</code> on fail as well as setting an
247 appropriate errno value.</td>
256 Generated by GTK-Doc V1.18</div>