A64L(3POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 A64L(3POSIX) 💖

ok so bestie, welcome to the POSIX Programmer's Manual ✨ this one's A64L(3POSIX) and it's all about turning a 32-bit integer into a radix-64 ASCII string and back again. no cap. let's get into it 🫶

🌸 PROLOG 🌸

okay so first things first, this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ — so if you're on Linux, lowkey go check the corresponding Linux manual page for the deets on Linux behavior. also possible: the interface just... isn't implemented on Linux at all. 💀 so vibe check your platform first.

✨ NAME ✨

a64l, l64a — convert between a 32-bit integer and a radix-64 ASCII string 💅

🎀 SYNOPSIS 🎀

#include <stdlib.h>

long a64l(const char *s);
char *l64a(long value);

🦋 DESCRIPTION 🦋

so these functions maintain numbers stored in radix-64 ASCII characters. it's giving... a notation where 32-bit integers get represented by up to six characters, and every character is a digit in radix-64 notation. and if your long type is carrying more than 32 bits? only the low-order 32 bits shall be used for these operations. periodt.

the characters used to represent digits are, and I need you to memorize this because it's iconic:

  • '.' (dot) for 0
  • '/' for 1
  • '0' through '9' for [2,11]
  • 'A' through 'Z' for [12,37]
  • 'a' through 'z' for [38,63]

💜 a64l() — the decoder

the a64l() function shall take a pointer to a radix-64 representation — and note that the first digit is the least significant, which is a lil quirky of it, honestly — and return the corresponding long value. ✨

the rules, bestie:

  • if the string pointed to by s contains more than six characters, a64l() shall use the first six. that's it. six. no more. 🙈
  • if the first six characters of the string contain a null terminator, a64l() shall use only the characters preceding that null terminator.
  • a64l() shall scan the character string from left to right, with the least significant digit on the left, decoding each character as a 6-bit radix-64 number.
  • if the type long contains more than 32 bits, the resulting value is sign-extended.
⚠️ the behavior of a64l() is unspecified if s is a null pointer, OR if the string pointed to by s was not generated by a previous call to l64a(). so like... don't do that. it's giving undefined, it's giving chaos, it's giving "we warned you." 😭

💜 l64a() — the encoder

the l64a() function shall take a long argument and return a pointer to the corresponding radix-64 representation. that's the whole job. slay. 💅

⚠️ the behavior of l64a() is unspecified if value is negative. so keep it non-negative or accept your fate.

also important, and this one's a real one:

  • the value returned by l64a() may be a pointer into a static buffer.
  • subsequent calls to l64a() may overwrite the buffer. so if you're holding onto that pointer thinking it's yours forever... it is not. copy it. please. 🫶
  • the l64a() function need not be thread-safe.

💖 RETURN VALUE 💖

upon successful completion, a64l() shall return the long value resulting from conversion of the input string. and if the string pointed to by s is an empty string, a64l() shall return 0L. cute. zero. nothing. empty. we love a clean zero. ✨

the l64a() function shall return a pointer to the radix-64 representation. and if value is 0L, l64a() shall return a pointer to an empty string. symmetrical. iconic. 🌸

🌈 ERRORS 🌈

No errors are defined.

the following sections are informative. (iykyk — that means the good stuff is below 👑)

⭐ EXAMPLES ⭐

None.

yes bestie, literally none. the standard said "figure it out." 💀

🧚 APPLICATION USAGE 🧚

if the type long contains more than 32 bits, the result of a64l(l64a(x)) is x in the low-order 32 bits. round trip, but make it 32-bit. 🎀

🔥 RATIONALE 🔥

okay so this is not the same encoding as used by either encoding variant of the uuencode utility. that's it. that's the whole rationale. don't mix them up, don't assume they're the same, they are not. ⭐

🌸 FUTURE DIRECTIONS 🌸

None.

the future is empty. the future is now. 🦋

💜 SEE ALSO 💜

  • strtoul()
  • the Base Definitions volume of POSIX.1‐2017, <stdlib.h>
  • the Shell and Utilities volume of POSIX.1‐2017, uuencode

okay so, legal moment, but make it cute:

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html . 🌈

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

and that's the whole page, bestie!! 🎀 this edition came to you from IEEE/The Open Group, 2017 — the A64L(3POSIX) era, and honestly? she ate. go forth and radix-64 responsibly. 💖✨🦋💅

📦 where this page comes from