| <html lang="en"> |
| <head> |
| <title>Encode Binary Data - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="String-and-Array-Utilities.html#String-and-Array-Utilities" title="String and Array Utilities"> |
| <link rel="prev" href="Trivial-Encryption.html#Trivial-Encryption" title="Trivial Encryption"> |
| <link rel="next" href="Argz-and-Envz-Vectors.html#Argz-and-Envz-Vectors" title="Argz and Envz Vectors"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Encode-Binary-Data"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Argz-and-Envz-Vectors.html#Argz-and-Envz-Vectors">Argz and Envz Vectors</a>, |
| Previous: <a rel="previous" accesskey="p" href="Trivial-Encryption.html#Trivial-Encryption">Trivial Encryption</a>, |
| Up: <a rel="up" accesskey="u" href="String-and-Array-Utilities.html#String-and-Array-Utilities">String and Array Utilities</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">5.11 Encode Binary Data</h3> |
| |
| <p>To store or transfer binary data in environments which only support text |
| one has to encode the binary data by mapping the input bytes to |
| characters in the range allowed for storing or transfering. SVID |
| systems (and nowadays XPG compliant systems) provide minimal support for |
| this task. |
| |
| <!-- stdlib.h --> |
| <!-- XPG --> |
| <div class="defun"> |
| — Function: char * <b>l64a</b> (<var>long int n</var>)<var><a name="index-l64a-584"></a></var><br> |
| <blockquote><p>This function encodes a 32-bit input value using characters from the |
| basic character set. It returns a pointer to a 7 character buffer which |
| contains an encoded version of <var>n</var>. To encode a series of bytes the |
| user must copy the returned string to a destination buffer. It returns |
| the empty string if <var>n</var> is zero, which is somewhat bizarre but |
| mandated by the standard.<br> |
| <strong>Warning:</strong> Since a static buffer is used this function should not |
| be used in multi-threaded programs. There is no thread-safe alternative |
| to this function in the C library.<br> |
| <strong>Compatibility Note:</strong> The XPG standard states that the return |
| value of <code>l64a</code> is undefined if <var>n</var> is negative. In the GNU |
| implementation, <code>l64a</code> treats its argument as unsigned, so it will |
| return a sensible encoding for any nonzero <var>n</var>; however, portable |
| programs should not rely on this. |
| |
| <p>To encode a large buffer <code>l64a</code> must be called in a loop, once for |
| each 32-bit word of the buffer. For example, one could do something |
| like this: |
| |
| <pre class="smallexample"> char * |
| encode (const void *buf, size_t len) |
| { |
| /* <span class="roman">We know in advance how long the buffer has to be.</span> */ |
| unsigned char *in = (unsigned char *) buf; |
| char *out = malloc (6 + ((len + 3) / 4) * 6 + 1); |
| char *cp = out, *p; |
| |
| /* <span class="roman">Encode the length.</span> */ |
| /* <span class="roman">Using `htonl' is necessary so that the data can be</span> |
| <span class="roman">decoded even on machines with different byte order.</span> |
| <span class="roman">`l64a' can return a string shorter than 6 bytes, so </span> |
| <span class="roman">we pad it with encoding of 0 (</span>'.'<span class="roman">) at the end by </span> |
| <span class="roman">hand.</span> */ |
| |
| p = stpcpy (cp, l64a (htonl (len))); |
| cp = mempcpy (p, "......", 6 - (p - cp)); |
| |
| while (len > 3) |
| { |
| unsigned long int n = *in++; |
| n = (n << 8) | *in++; |
| n = (n << 8) | *in++; |
| n = (n << 8) | *in++; |
| len -= 4; |
| p = stpcpy (cp, l64a (htonl (n))); |
| cp = mempcpy (p, "......", 6 - (p - cp)); |
| } |
| if (len > 0) |
| { |
| unsigned long int n = *in++; |
| if (--len > 0) |
| { |
| n = (n << 8) | *in++; |
| if (--len > 0) |
| n = (n << 8) | *in; |
| } |
| cp = stpcpy (cp, l64a (htonl (n))); |
| } |
| *cp = '\0'; |
| return out; |
| } |
| </pre> |
| <p>It is strange that the library does not provide the complete |
| functionality needed but so be it. |
| |
| </blockquote></div> |
| |
| <p>To decode data produced with <code>l64a</code> the following function should be |
| used. |
| |
| <!-- stdlib.h --> |
| <!-- XPG --> |
| <div class="defun"> |
| — Function: long int <b>a64l</b> (<var>const char *string</var>)<var><a name="index-a64l-585"></a></var><br> |
| <blockquote><p>The parameter <var>string</var> should contain a string which was produced by |
| a call to <code>l64a</code>. The function processes at least 6 characters of |
| this string, and decodes the characters it finds according to the table |
| below. It stops decoding when it finds a character not in the table, |
| rather like <code>atoi</code>; if you have a buffer which has been broken into |
| lines, you must be careful to skip over the end-of-line characters. |
| |
| <p>The decoded number is returned as a <code>long int</code> value. |
| </p></blockquote></div> |
| |
| <p>The <code>l64a</code> and <code>a64l</code> functions use a base 64 encoding, in |
| which each character of an encoded string represents six bits of an |
| input word. These symbols are used for the base 64 digits: |
| |
| <p><table summary=""><tr align="left"><td valign="top"></td><td valign="top">0 </td><td valign="top">1 </td><td valign="top">2 </td><td valign="top">3 </td><td valign="top">4 </td><td valign="top">5 </td><td valign="top">6 </td><td valign="top">7 |
| <br></td></tr><tr align="left"><td valign="top">0 </td><td valign="top"><code>.</code> </td><td valign="top"><code>/</code> </td><td valign="top"><code>0</code> </td><td valign="top"><code>1</code> |
| </td><td valign="top"><code>2</code> </td><td valign="top"><code>3</code> </td><td valign="top"><code>4</code> </td><td valign="top"><code>5</code> |
| <br></td></tr><tr align="left"><td valign="top">8 </td><td valign="top"><code>6</code> </td><td valign="top"><code>7</code> </td><td valign="top"><code>8</code> </td><td valign="top"><code>9</code> |
| </td><td valign="top"><code>A</code> </td><td valign="top"><code>B</code> </td><td valign="top"><code>C</code> </td><td valign="top"><code>D</code> |
| <br></td></tr><tr align="left"><td valign="top">16 </td><td valign="top"><code>E</code> </td><td valign="top"><code>F</code> </td><td valign="top"><code>G</code> </td><td valign="top"><code>H</code> |
| </td><td valign="top"><code>I</code> </td><td valign="top"><code>J</code> </td><td valign="top"><code>K</code> </td><td valign="top"><code>L</code> |
| <br></td></tr><tr align="left"><td valign="top">24 </td><td valign="top"><code>M</code> </td><td valign="top"><code>N</code> </td><td valign="top"><code>O</code> </td><td valign="top"><code>P</code> |
| </td><td valign="top"><code>Q</code> </td><td valign="top"><code>R</code> </td><td valign="top"><code>S</code> </td><td valign="top"><code>T</code> |
| <br></td></tr><tr align="left"><td valign="top">32 </td><td valign="top"><code>U</code> </td><td valign="top"><code>V</code> </td><td valign="top"><code>W</code> </td><td valign="top"><code>X</code> |
| </td><td valign="top"><code>Y</code> </td><td valign="top"><code>Z</code> </td><td valign="top"><code>a</code> </td><td valign="top"><code>b</code> |
| <br></td></tr><tr align="left"><td valign="top">40 </td><td valign="top"><code>c</code> </td><td valign="top"><code>d</code> </td><td valign="top"><code>e</code> </td><td valign="top"><code>f</code> |
| </td><td valign="top"><code>g</code> </td><td valign="top"><code>h</code> </td><td valign="top"><code>i</code> </td><td valign="top"><code>j</code> |
| <br></td></tr><tr align="left"><td valign="top">48 </td><td valign="top"><code>k</code> </td><td valign="top"><code>l</code> </td><td valign="top"><code>m</code> </td><td valign="top"><code>n</code> |
| </td><td valign="top"><code>o</code> </td><td valign="top"><code>p</code> </td><td valign="top"><code>q</code> </td><td valign="top"><code>r</code> |
| <br></td></tr><tr align="left"><td valign="top">56 </td><td valign="top"><code>s</code> </td><td valign="top"><code>t</code> </td><td valign="top"><code>u</code> </td><td valign="top"><code>v</code> |
| </td><td valign="top"><code>w</code> </td><td valign="top"><code>x</code> </td><td valign="top"><code>y</code> </td><td valign="top"><code>z</code> |
| <br></td></tr></table> |
| |
| <p>This encoding scheme is not standard. There are some other encoding |
| methods which are much more widely used (UU encoding, MIME encoding). |
| Generally, it is better to use one of these encodings. |
| |
| </body></html> |
| |
