sys/man/2/encode

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