man3p/a64l.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "A64L" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" a64l
   4 .SH NAME
   5 a64l, l64a \- convert between a 32-bit integer and a radix-64 ASCII
   6 string
   7 .SH SYNOPSIS
   8 .LP
   9 \fB#include <stdlib.h>
  10 .br
  11 .sp
  12 long a64l(const char *\fP\fIs\fP\fB);
  13 .br
  14 char *l64a(long\fP \fIvalue\fP\fB); \fP
  15 \fB
  16 .br
  17 \fP
  18 .SH DESCRIPTION
  19 .LP
  20 These functions maintain numbers stored in radix-64 ASCII characters.
  21 This is a notation by which 32-bit integers can be
  22 represented by up to six characters; each character represents a digit
  23 in radix-64 notation. If the type \fBlong\fP contains more
  24 than 32 bits, only the low-order 32 bits shall be used for these operations.
  25 .LP
  26 The characters used to represent digits are \fB'.'\fP (dot) for 0,
  27 \fB'/'\fP for 1, \fB'0'\fP through \fB'9'\fP for
  28 [2,11], \fB'A'\fP through \fB'Z'\fP for [12,37], and \fB'a'\fP through
  29 \fB'z'\fP for [38,63].
  30 .LP
  31 The \fIa64l\fP() function shall take a pointer to a radix-64 representation,
  32 in which the first digit is the least significant,
  33 and return the corresponding \fBlong\fP value. If the string pointed
  34 to by \fIs\fP contains more than six characters,
  35 \fIa64l\fP() shall use the first six. If the first six characters
  36 of the string contain a null terminator, \fIa64l\fP() shall use
  37 only characters preceding the null terminator. The \fIa64l\fP() function
  38 shall scan the character string from left to right with
  39 the least significant digit on the left, decoding each character as
  40 a 6-bit radix-64 number. If the type \fBlong\fP contains more
  41 than 32 bits, the resulting value is sign-extended. The behavior of
  42 \fIa64l\fP() is unspecified if \fIs\fP is a null pointer or
  43 the string pointed to by \fIs\fP was not generated by a previous call
  44 to \fIl64a\fP().
  45 .LP
  46 The \fIl64a\fP() function shall take a \fBlong\fP argument and return
  47 a pointer to the corresponding radix-64 representation.
  48 The behavior of \fIl64a\fP() is unspecified if \fIvalue\fP is negative.
  49 .LP
  50 The value returned by \fIl64a\fP() may be a pointer into a static
  51 buffer. Subsequent calls to \fIl64a\fP() may overwrite the
  52 buffer.
  53 .LP
  54 The \fIl64a\fP() function need not be reentrant. A function that is
  55 not required to be reentrant is not required to be
  56 thread-safe.
  57 .SH RETURN VALUE
  58 .LP
  59 Upon successful completion, \fIa64l\fP() shall return the \fBlong\fP
  60 value resulting from conversion of the input string. If a
  61 string pointed to by \fIs\fP is an empty string, \fIa64l\fP() shall
  62 return 0L.
  63 .LP
  64 The \fIl64a\fP() function shall return a pointer to the radix-64 representation.
  65 If \fIvalue\fP is 0L, \fIl64a\fP() shall
  66 return a pointer to an empty string.
  67 .SH ERRORS
  68 .LP
  69 No errors are defined.
  70 .LP
  71 \fIThe following sections are informative.\fP
  72 .SH EXAMPLES
  73 .LP
  74 None.
  75 .SH APPLICATION USAGE
  76 .LP
  77 If the type \fBlong\fP contains more than 32 bits, the result of \fIa64l\fP(\fIl64a\fP(\fIx\fP))
  78 is \fIx\fP in the
  79 low-order 32 bits.
  80 .SH RATIONALE
  81 .LP
  82 This is not the same encoding as used by either encoding variant of
  83 the \fIuuencode\fP
  84 utility.
  85 .SH FUTURE DIRECTIONS
  86 .LP
  87 None.
  88 .SH SEE ALSO
  89 .LP
  90 \fIstrtoul\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
  91 \fI<stdlib.h>\fP, the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001,
  92 \fIuuencode\fP
  93 .SH COPYRIGHT
  94 Portions of this text are reprinted and reproduced in electronic form
  95 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  96 -- Portable Operating System Interface (POSIX), The Open Group Base
  97 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  98 Electrical and Electronics Engineers, Inc and The Open Group. In the
  99 event of any discrepancy between this version and the original IEEE and
 100 The Open Group Standard, the original IEEE and The Open Group Standard
 101 is the referee document. The original Standard can be obtained online at
 102 http://www.opengroup.org/unix/online.html .