Added
Link Here
|
1 |
.\" $NetBSD: a64l.3,v 1.8 2003/04/16 13:34:45 wiz Exp $ |
2 |
.\" |
3 |
.\" Copyright (c) 1998, 1999 The NetBSD Foundation, Inc. |
4 |
.\" All rights reserved. |
5 |
.\" |
6 |
.\" This code is derived from software contributed to The NetBSD Foundation |
7 |
.\" by Klaus Klein. |
8 |
.\" |
9 |
.\" Redistribution and use in source and binary forms, with or without |
10 |
.\" modification, are permitted provided that the following conditions |
11 |
.\" are met: |
12 |
.\" 1. Redistributions of source code must retain the above copyright |
13 |
.\" notice, this list of conditions and the following disclaimer. |
14 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
15 |
.\" notice, this list of conditions and the following disclaimer in the |
16 |
.\" documentation and/or other materials provided with the distribution. |
17 |
.\" 3. All advertising materials mentioning features or use of this software |
18 |
.\" must display the following acknowledgement: |
19 |
.\" This product includes software developed by the NetBSD |
20 |
.\" Foundation, Inc. and its contributors. |
21 |
.\" 4. Neither the name of The NetBSD Foundation nor the names of its |
22 |
.\" contributors may be used to endorse or promote products derived |
23 |
.\" from this software without specific prior written permission. |
24 |
.\" |
25 |
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS |
26 |
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED |
27 |
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
28 |
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS |
29 |
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
30 |
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
31 |
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
32 |
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
33 |
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
34 |
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
35 |
.\" POSSIBILITY OF SUCH DAMAGE. |
36 |
.\" |
37 |
.\" $FreeBSD$ |
38 |
.\" |
39 |
.Dd April 21, 2003 |
40 |
.Dt A64L 3 |
41 |
.Os |
42 |
.Sh NAME |
43 |
.Nm a64l , |
44 |
.Nm l64a , |
45 |
.Nm l64a_r |
46 |
.Nd "convert between a long integer and a base-64 ASCII string" |
47 |
.Sh LIBRARY |
48 |
.Lb libc |
49 |
.Sh SYNOPSIS |
50 |
.In stdlib.h |
51 |
.Ft long |
52 |
.Fn a64l "const char *s" |
53 |
.Ft char * |
54 |
.Fn l64a "long int l" |
55 |
.Ft int |
56 |
.Fn l64a_r "long int l" "char *buffer" "int buflen" |
57 |
.Sh DESCRIPTION |
58 |
The |
59 |
.Fn a64l |
60 |
and |
61 |
.Fn l64a |
62 |
functions convert between a long integer and its base-64 ASCII string |
63 |
representation. |
64 |
.Pp |
65 |
The characters used to represent ``digits'' are |
66 |
`.' for 0, |
67 |
`/' for 1, |
68 |
`0' - `9' for 2 - 11, |
69 |
`A' - `Z' for 12 - 37, and |
70 |
`a' - `z' for 38 - 63. |
71 |
.Pp |
72 |
.Fn a64l |
73 |
takes a pointer to a NUL-terminated base-64 ASCII string |
74 |
representation, |
75 |
.Fa s , |
76 |
and returns the corresponding long integer value. |
77 |
.Pp |
78 |
.Fn l64a |
79 |
takes a long integer value, |
80 |
.Fa l , |
81 |
and returns a pointer to the corresponding NUL-terminated base-64 |
82 |
ASCII string representation. |
83 |
.Pp |
84 |
.Fn l64a_r |
85 |
performs a conversion identical to that of |
86 |
.Fn l64a |
87 |
and stores the resulting representation in the memory area pointed to by |
88 |
.Fa buffer , |
89 |
consuming at most |
90 |
.Fa buflen |
91 |
characters including the terminating NUL character. |
92 |
.Sh RETURN VALUES |
93 |
On successful completion, |
94 |
.Fn a64l |
95 |
returns the long integer value corresponding to the input string. |
96 |
If the string pointed to by |
97 |
.Fa s |
98 |
is an empty string, |
99 |
.Fn a64l |
100 |
returns a value of 0L. |
101 |
.Pp |
102 |
.Fn l64a |
103 |
returns a pointer to the base-64 ASCII string representation corresponding to |
104 |
the input value. |
105 |
If |
106 |
.Fa l |
107 |
is 0L, |
108 |
.Fn l64a |
109 |
returns a pointer to an empty string. |
110 |
.Pp |
111 |
On successful completion, |
112 |
.Fn l64a_r |
113 |
returns 0; if |
114 |
.Fa buffer |
115 |
is of insufficient length, -1 is returned. |
116 |
.Sh SEE ALSO |
117 |
.Xr strtol 3 |
118 |
.Sh STANDARDS |
119 |
The |
120 |
.Fn a64l |
121 |
and |
122 |
.Fn l64a |
123 |
functions conform to |
124 |
.St -xpg4.2 . |
125 |
The |
126 |
.Fn l64a_r |
127 |
function conforms to |
128 |
.St -svid4 , |
129 |
Multithreading Extension. |
130 |
.Sh BUGS |
131 |
The |
132 |
.Fn l64a |
133 |
function is not reentrant. |
134 |
The value returned by it points into a static buffer area; |
135 |
subsequent calls to |
136 |
.Fn la64a |
137 |
may overwrite this buffer. |
138 |
In multi-threaded applications, |
139 |
.Fn l64a_r |
140 |
should be used instead. |