sys/man/2/encode

   1 .TH ENCODE 2
   2 .SH NAME
   3 dec64, enc64, dec32, enc32, dec16, enc16, \
   4 dec64x, enc64x, dec32x, enc32x, \
   5 dec64chr, enc64chr, dec32chr, enc32chr, dec16chr, enc16chr, \
   6 encodefmt \- encoding byte arrays as strings
   7 .SH SYNOPSIS
   8 .B #include <u.h>
   9 .br
  10 .B #include <libc.h>
  11 .PP
  12 .B
  13 int     dec64(uchar *out, int lim, char *in, int n)
  14 .PP
  15 .B
  16 int     dec64x(uchar *out, int lim, char *in, int n, int (*map)(int))
  17 .PP
  18 .B
  19 int     enc64(char *out, int lim, uchar *in, int n)
  20 .PP
  21 .B
  22 int     enc64x(char *out, int lim, uchar *in, int n, int (*map)(int))
  23 .PP
  24 .B
  25 int     dec32(uchar *out, int lim, char *in, int n)
  26 .PP
  27 .B
  28 int     dec32x(uchar *out, int lim, char *in, int n, int (*map)(int))
  29 .PP
  30 .B
  31 int     enc32(char *out, int lim, uchar *in, int n)
  32 .PP
  33 .B
  34 int     enc32x(char *out, int lim, uchar *in, int n, int (*map)(int))
  35 .PP
  36 .B
  37 int     dec16(uchar *out, int lim, char *in, int n)
  38 .PP
  39 .B
  40 int     enc16(char *out, int lim, uchar *in, int n)
  41 .PP
  42 .B
  43 int     dec64chr(int c)
  44 .PP
  45 .B
  46 int     enc64chr(int o)
  47 .PP
  48 .B
  49 int     dec32chr(int c)
  50 .PP
  51 .B
  52 int     enc32chr(int o)
  53 .PP
  54 .B
  55 int     dec16chr(int c)
  56 .PP
  57 .B
  58 int     enc16chr(int o)
  59 .PP
  60 .B
  61 int     encodefmt(Fmt*)
  62 .SH DESCRIPTION
  63 The functions described here handle encoding and decoding of
  64 bytes to printable ASCII strings as specified by RFC4648.
  65 .PP
  66 .IR Enc16 ,
  67 .I enc32
  68 and
  69 .I enc64
  70 create null terminated strings.  They return the size of the
  71 encoded string (without the null) or -1 if the encoding fails.
  72 The encoding fails if
  73 .IR lim ,
  74 the length of the output buffer (including null), is too small.
  75 .PP
  76 .IR Dec16 ,
  77 .I dec32
  78 and
  79 .I dec64
  80 return the number of bytes decoded or -1 if the decoding fails.
  81 The decoding fails if the output buffer is not large enough or,
  82 for base 32, if the input buffer length is not a multiple
  83 of 8.
  84 .PP
  85 .IR Dec16chr ,
  86 .I dec32chr
  87 and
  88 .I dec64chr
  89 return the value for a symbol of the alphabet or -1 when the
  90 symbol is not in the alphabet.
  91 .PP
  92 .IR Enc16chr ,
  93 .I enc32chr
  94 and
  95 .I enc64chr
  96 encode a symbol of the alphabet given a value.
  97 if the value is out of range then zero is returned.
  98 .PP
  99 The
 100 .I enc64x
 101 and
 102 .I enc32x
 103 variants are identical to the above, except that they take a
 104 function mapping from an arbitrary index in the alphabet to
 105 the encoded character.
 106 For example, in the following 32-character alphabet,
 107 .EX
 108 .I ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
 109 .EE
 110 the chr function would map the value
 111 .I 3
 112 to the character
 113 .IR D .
 114
 115 The
 116 .I dec64x
 117 and
 118 .I dec32x
 119 variants are similar to the above, however the function passed
 120 maps from a character within the alphabet to the index within
 121 the alphabet.
 122
 123 .PP
 124 .I Encodefmt
 125 can be used with
 126 .IR fmtinstall (2)
 127 and
 128 .IR print (2)
 129 to print encoded representations of byte arrays.
 130 The verbs are
 131 .TP
 132 .B H
 133 base 16 (i.e. hexadecimal). The default encoding is
 134 in upper case.  The
 135 .B l
 136 flag forces lower case.
 137 .TP
 138 .B <
 139 base 32. The default is upper case, same as
 140 .BR H .
 141 .TP
 142 .B [
 143 base 64 (same as MIME)
 144 .PD
 145 .PP
 146 The length of the array is specified as
 147 .IR f2 .
 148 For example, to display a 15 byte array as hex:
 149 .EX
 150
 151     char x[15];
 152
 153     fmtinstall('H', encodefmt);
 154     print("%.*H\\n", sizeof x, x);
 155
 156 .EE
 157 .SH SOURCE
 158 .B /sys/src/libc/port/u16.c
 159 .br
 160 .B /sys/src/libc/port/u32.c
 161 .br
 162 .B /sys/src/libc/port/u64.c
 163 .br
 164 .B /sys/src/libc/port/encodefmt.c
 165 .SH HISTORY
 166 In Jan 2018, base 32 encoding was changed from non-standard
 167 to standard RFC4648 alphabet.
 168 .TP
 169 old:
 170 .B "23456789abcdefghijkmnpqrstuvwxyz"
 171 .TP
 172 new:
 173 .B "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"