| 1 | .\" Copyright (c) 2005 Tom Rhodes |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" |
| 13 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 14 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 15 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 16 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 17 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 18 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 19 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 20 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 21 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 22 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 23 | .\" SUCH DAMAGE. |
| 24 | .\" |
| 25 | .\" Portions of this text are reprinted and reproduced in electronic form |
| 26 | .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- |
| 27 | .\" Portable Operating System Interface (POSIX), The Open Group Base |
| 28 | .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of |
| 29 | .\" Electrical and Electronics Engineers, Inc and The Open Group. In the |
| 30 | .\" event of any discrepancy between this version and the original IEEE and |
| 31 | .\" The Open Group Standard, the original IEEE and The Open Group Standard is |
| 32 | .\" the referee document. The original Standard can be obtained online at |
| 33 | .\" http://www.opengroup.org/unix/online.html. |
| 34 | .\" |
| 35 | .\" $FreeBSD: src/lib/libc/stdlib/a64l.3,v 1.3 2006/09/30 10:29:43 ru Exp $ |
| 36 | .\" |
| 37 | .Dd November 20, 2005 |
| 38 | .Dt A64L 3 |
| 39 | .Os |
| 40 | .Sh NAME |
| 41 | .Nm a64l , |
| 42 | .Nm l64a , |
| 43 | .Nm l64a_r |
| 44 | .Nd "convert between a long integer and a base-64 ASCII string" |
| 45 | .Sh LIBRARY |
| 46 | .Lb libc |
| 47 | .Sh SYNOPSIS |
| 48 | .In stdlib.h |
| 49 | .Ft long |
| 50 | .Fn a64l "const char *s" |
| 51 | .Ft char * |
| 52 | .Fn l64a "long int l" |
| 53 | .Ft int |
| 54 | .Fn l64a_r "long int l" "char *buffer" "int buflen" |
| 55 | .Sh DESCRIPTION |
| 56 | These functions are used to maintain numbers stored in radix-64 |
| 57 | .Tn ASCII |
| 58 | characters. |
| 59 | This is a notation by which 32-bit integers can be represented by |
| 60 | up to six characters; each character represents a digit in |
| 61 | radix-64 notation. |
| 62 | If the type long contains more than 32 bits, only the low-order |
| 63 | 32 bits are used for these operations. |
| 64 | .Pp |
| 65 | The characters used to represent |
| 66 | .Dq digits |
| 67 | are |
| 68 | .Ql .\& |
| 69 | for 0, |
| 70 | .Ql / |
| 71 | for 1, |
| 72 | .Ql 0 |
| 73 | - |
| 74 | .Ql 9 |
| 75 | for 2 - 11, |
| 76 | .Ql A |
| 77 | - |
| 78 | .Ql Z |
| 79 | for 12 - 37, and |
| 80 | .Ql a |
| 81 | - |
| 82 | .Ql z |
| 83 | for 38 - 63. |
| 84 | .Pp |
| 85 | The |
| 86 | .Fn a64l |
| 87 | function takes a pointer to a radix-64 representation, in which the first |
| 88 | digit is the least significant, and returns a corresponding |
| 89 | .Vt long |
| 90 | value. |
| 91 | If the string pointed to by |
| 92 | .Fa s |
| 93 | contains more than six characters, |
| 94 | .Fn a64l |
| 95 | uses the first six. |
| 96 | If the first six characters of the string contain a null terminator, |
| 97 | .Fn a64l |
| 98 | uses only characters preceding the null terminator. |
| 99 | The |
| 100 | .Fn a64l |
| 101 | function scans the character string from left to right with the least |
| 102 | significant digit on the left, decoding each character as a 6-bit |
| 103 | radix-64 number. |
| 104 | If the type long contains more than 32 bits, the resulting value is |
| 105 | sign-extended. |
| 106 | The behavior of |
| 107 | .Fn a64l |
| 108 | is unspecified if |
| 109 | .Fa s |
| 110 | is a null pointer or the string pointed to by |
| 111 | .Fa s |
| 112 | was not generated by a previous call to |
| 113 | .Fn l64a . |
| 114 | .Pp |
| 115 | The |
| 116 | .Fn l64a |
| 117 | function takes a |
| 118 | .Vt long |
| 119 | argument and returns a pointer to the corresponding |
| 120 | radix-64 representation. |
| 121 | The behavior of |
| 122 | .Fn l64a |
| 123 | is unspecified if value is negative. |
| 124 | .Pp |
| 125 | The value returned by |
| 126 | .Fn l64a |
| 127 | is a pointer into a static buffer. |
| 128 | Subsequent calls to |
| 129 | .Fn l64a |
| 130 | may overwrite the buffer. |
| 131 | .Pp |
| 132 | The |
| 133 | .Fn l64a_r |
| 134 | function performs a conversion identical to that of |
| 135 | .Fn l64a |
| 136 | and stores the resulting representation in the memory area pointed to by |
| 137 | .Fa buffer , |
| 138 | consuming at most |
| 139 | .Fa buflen |
| 140 | characters including the terminating |
| 141 | .Dv NUL |
| 142 | character. |
| 143 | .Sh RETURN VALUES |
| 144 | On successful completion, |
| 145 | .Fn a64l |
| 146 | returns the |
| 147 | .Vt long |
| 148 | value resulting from conversion of the input string. |
| 149 | If a string pointed to by |
| 150 | .Fa s |
| 151 | is an empty string, |
| 152 | .Fn a64l |
| 153 | returns 0. |
| 154 | .Pp |
| 155 | The |
| 156 | .Fn l64a |
| 157 | function returns a pointer to the radix-64 representation. |
| 158 | If value is 0, |
| 159 | .Fn l64a |
| 160 | returns a pointer to an empty string. |
| 161 | .Sh SEE ALSO |
| 162 | .Xr strtoul 3 |
| 163 | .Sh HISTORY |
| 164 | The |
| 165 | .Fn a64l , |
| 166 | .Fn l64a , |
| 167 | and |
| 168 | .Fn l64a_r |
| 169 | functions are derived from |
| 170 | .Nx |
| 171 | with modifications. |
| 172 | They appeared in |
| 173 | .Fx 6.1 . |
| 174 | .Sh AUTHORS |
| 175 | The |
| 176 | .Fn a64l , |
| 177 | .Fn l64a , |
| 178 | and |
| 179 | .Fn l64a_r |
| 180 | functions |
| 181 | were added to |
| 182 | .Fx |
| 183 | by |
| 184 | .An Tom Rhodes Aq Mt trhodes@FreeBSD.org . |
| 185 | Almost all of this manual page came from the |
| 186 | .Tn POSIX |
| 187 | standard. |