Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / base.h / base_fmt.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
% limb manual
% base_fmt(3)
% limb 0.1.0
% 2023-07-24

# NAME

base_fmt, base_scan - base-16/32/64/128 encode/decode a byte array

# SYNOPSIS

    #include <limb/base.h>

```pre hl
ssize_t base_fmt(char *<em>dst</em>, int <em>base</em>, const char *<em>data</em>, size_t <em>dlen</em>, const char *<em>alpha</em>, int <em>strict</em>)
ssize_t base_scan(char *<em>dst</em>, int <em>base</em>, const char *<em>data</em>, size_t <em>dlen</em>, const char *<em>alpha</em>, int <em>strict</em>)
```

# DESCRIPTION

The `base_fmt`() function will encode the byte array pointed to by `data` of
length `dlen` bytes into the byte array pointed to by `dst` using the base
algorithm specified with `base` and the alphabet pointed to be `alpha`.

Valid values for `base` are 2, 4, 8, 16, 32, 64 and 128 for the corresponding
base. Accordingly the specified alphabet `alpha` must be of length 3, 5, 9, 17,
33, 65 and 129 bytes, with the last character to be used for padding.

The output placed into `dst` will have necessary padding unless `strict` is
non-zero, in which case only one padding character is put when padding is
needed.
Note that it will /not/ be NUL-terminated. If `dst` is *NULL*, the function
simply returns the size required for `dst`.

The `base_scan`() function will decode the byte array pointed to by `data` of
length `dlen` into the byte array pointed to be `dst` using the base algorithm
specified with `base` and the alphabet pointed to by `alpha`.

Both arguments `base` and `alpha` are similar than their counterparts for
`base_fmt`(). Argument `strict` is similar as well, in that if non-zero it will
require all necessary padding, but with zero it will accept a single padding
character indicating padding.

Additionally, when `strict` is non-zero any base-encoded data were at least one
unused bit was set will result in an error.

The encoded `data` doesn't have to end with proper padding, that is a single
padding character marking the end of data is enough (as done with `base_fmt`()
when `strict` is zero).  Note that, as with `base_fmt`(), the result in `dst`
will /not/ be NUL-terminated; And that `dst` can also be *NULL*, in which case
only data validation is performed and the length required in `dst` is returned.

! INFO:
! Both functions implement algorithms that can be used to perform encoding
! and decoding as described in [RFC 4648][rfc4648], assuming corresponding
! alphabet is used (and `strict` is non-zero).

[rfc4648]: https://datatracker.ietf.org/doc/html/rfc4648

# RETURN VALUE

Both functions return the length written into `dst` - or that would have been
had it not been *NULL* - on success. Otherwise, they return -1 and set `errno`
to indicate the error.

# ERRORS

The `base_fmt`() and `base_scan`() functions may fail if :

: *ERANGE*
:: The `base` argument isn't valid.

The `base_scan`() function may also fail if :

: *EINVAL*
:: The input `data` is invalid, e.g. contains a character not from `alpha`.

# SEE ALSO

[base32_fmt](3), [base64_fmt](3)