]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> | |
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 | .\" 3. The name of the author may not be used to endorse or promote products | |
13 | .\" derived from this software without specific prior written permission. | |
14 | .\" | |
15 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, | |
16 | .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY | |
17 | .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL | |
18 | .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | |
19 | .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | |
20 | .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; | |
21 | .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, | |
22 | .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR | |
23 | .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF | |
24 | .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
25 | .\" | |
26 | .\" $OpenBSD: a64l.3,v 1.5 2000/04/20 13:50:01 aaron Exp $ | |
27 | .\" | |
28 | .Dd August 17, 1997 | |
29 | .Dt A64L 3 | |
30 | .Os | |
31 | .Sh NAME | |
32 | .Nm a64l , | |
33 | .Nm l64a | |
34 | .Nd convert between 32-bit integer and radix-64 ASCII string | |
35 | .Sh SYNOPSIS | |
36 | .Fd #include <stdlib.h> | |
37 | .Ft long | |
38 | .Fn a64l "const char *s" | |
39 | .Ft char * | |
40 | .Fn l64a "long value" | |
41 | .Sh DESCRIPTION | |
42 | The | |
43 | .Fn a64l | |
44 | and | |
45 | .Fn l64a | |
46 | functions are used to maintain numbers stored in radix-64 | |
47 | .Tn ASCII | |
48 | characters. | |
49 | This is a notation by which 32-bit integers | |
50 | can be represented by up to six characters; each character represents a | |
51 | .Dq digit | |
52 | in a radix-64 notation. | |
53 | .Pp | |
54 | The characters used to represent digits are | |
55 | .Ql \&. | |
56 | for 0, | |
57 | .Ql / | |
58 | for 1, | |
59 | .Ql 0 | |
60 | through | |
61 | .Ql 9 | |
62 | for 2-11, | |
63 | .Ql A | |
64 | through | |
65 | .Ql Z | |
66 | for 12-37, and | |
67 | .Ql a | |
68 | through | |
69 | .Ql z | |
70 | for 38-63. | |
71 | .Pp | |
72 | The | |
73 | .Fn a64l | |
74 | function takes a pointer to a null-terminated radix-64 representation | |
75 | and returns a corresponding 32-bit value. | |
76 | If the string pointed to by | |
77 | .Fa s | |
78 | contains more than six characters, | |
79 | .Fn a64l | |
80 | will use the first six. | |
81 | .Fn a64l | |
82 | scans the character string from left to right, decoding | |
83 | each character as a 6-bit radix-64 number. | |
84 | If a long integer is | |
85 | larger than 32 bits, the return value will be sign-extended. | |
86 | .Pp | |
87 | .Fn l64a | |
88 | takes a long integer argument | |
89 | .Fa value | |
90 | and returns a pointer to the corresponding radix-64 representation. | |
91 | .Sh RETURN VALUES | |
92 | On success, | |
93 | .Fn a64l | |
94 | returns a 32-bit representation of | |
95 | .Fa s . | |
96 | If | |
97 | .Fa s | |
98 | is a null pointer or if it contains digits other than those described above. | |
99 | .Fn a64l | |
100 | returns \-1 and sets the global variable | |
101 | .Va errno | |
102 | to | |
103 | .Er EINVAL . | |
104 | .Pp | |
105 | On success, | |
106 | .Fn l64a | |
107 | returns a pointer to a string containing the radix-64 representation of | |
108 | .Fa value . | |
109 | If | |
110 | .Fa value | |
111 | is 0, | |
112 | .Fn l64a | |
113 | returns a pointer to the empty string. | |
114 | If | |
115 | .Fa value | |
116 | is negative, | |
117 | .Fn l64a | |
118 | returns a null pointer and sets the global variable | |
119 | .Va errno | |
120 | to | |
121 | .Er EINVAL . | |
122 | .Sh WARNINGS | |
123 | The value returned by | |
124 | .Fn l64a | |
125 | is a pointer into a static buffer, the contents of which | |
126 | will be overwritten by subsequent calls. | |
127 | .Pp | |
128 | The value returned by | |
129 | .Fn a64l | |
130 | may be incorrect if the value is too large; for that reason, only strings | |
131 | that resulted from a call to | |
132 | .Fn l64a | |
133 | should be used to call | |
134 | .Fn a64l . | |
135 | .Pp | |
136 | If a long integer is larger than 32 bits, only the low-order | |
137 | 32 bits are used. | |
138 | .Sh STANDARDS | |
139 | The | |
140 | .Fn a64l | |
141 | and | |
142 | .Fn l64a | |
143 | functions conform to | |
144 | .St -xpg4.2 . |