fn85/fn85.3

.TH Fn85 3 "September 2017" "Version 1.0" "libfn85 API"
.SH NAME
fn85 \- file name in base 85 (from arbitrary bytes) library.
.SH SYNOPSIS
.br
.B #include <fn85.h>
.sp
Link with \fI\-lfn85\fP or `pkg-config --libs fn85`
.SH DESCRIPTION
fn85 encodes 4 bytes of arbitrary data as 5 printable ascii characters suitable for use in a file name. This is done by treating each byte as a digit in a 256 radix number and converting said number to an 85 radix number.  The digits used to represent this 85 radix number are the following in order from 0 to 85:
.sp
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!$%&*+,-:;<=>?@[]^_`{|}
.sp
.SS Types
.B Fn85_err
.RB "represents a decoding error. Possible values are " FN85_OKAY " for no error, " FN85_INVALID " for trying to decode something that is not a valid digit, and " FN85_TOO_HIGH " for decoding a number that is greater than the possible value that can be represented by 4 bytes. It is defined as such:"
.sp
typedef enum { FN85_OKAY, FN85_INVALID, FN85_TOO_HIGH } Fn85_err;
.SS Functions
.BI "void fn85_encode(char *" des ", const void *" src ", size_t " units ");"
.br
.BI "Fn85_err fn85_decode(void *" des ", const char *" src ", size_t " units ", size_t *" pos ", const char **" error ");"
.sp
.B fn85_encode ()
.RI "encodes 4 * " units " bytes from " src " to 5 * " units " digits in " des "."
.sp
.B fn85_decode ()
.RI "decodes 5 * " units " digits from " src " to 4 * " units " bytes in " des ". The value of " pos " should be initialized before calling the function and is increased by the number of valid digits before an error occurs. If no error occurs, this number is increased by 5 * " units ". If " error " is not NULL, it will be set to an appropriate error string upon an error occurring."
.SH "Return Value"
The function
.B fn85_decode ()
returns a value of type
.B Fn85_err
which denotes if an error occured in decoding, and if so, what said error was. The value FN85_OKAY denotes that no error has occurred, this also means an error string will not be set.
.SH EXAMPLES
.SS Encoding and decoding simple data
.nf
#include <stdio.h>
#include <fn85.h>

int
main(int argc, char *argv[])
{
	char dat[16] = "hello, world!!!";
	char dat2[21];
	char dat3[sizeof(dat)];
	size_t pos = 0;
	const char *error;

	/* encode and print encoding */
	fn85_encode(dat2, dat, 4);
	dat2[20] = '\e0';
	printf("%s\n", dat2);

	/* decode and check for errors */
	if (fn85_decode(dat3, dat2, 4, &pos, &error) == FN85_OKAY) {
		printf("%s\n", dat3);
	} else {
		printf("%s at %zu\n", error, pos);
	}

	return 0;
}
.fi
.SH AUTHOR
Uladox (more than based!)
.SH "AVAILABILITY AND SOURCE"
.B fn85
can be found in its repository at https://www.notabug.org/Uladox/fn85
.SH "SEE ALSO"
.BR ascii (7)
.BR utf-8 (7)
.BR filesystems (5)
.BR rid (3)
.BR uuid (3)
.BR endian (3)
.BR base32 (1)
.BR base64 (1)