man: add libbase64.3 manual page

Wed, 02 Jun 2021 16:37:59 +0200

author
David Demelier <markand@malikania.fr>
date
Wed, 02 Jun 2021 16:37:59 +0200
changeset 33
01c29bee0c54
parent 32
c96f2b26678a
child 34
e4a6c3f3d0f2

man: add libbase64.3 manual page

Makefile file | annotate | diff | comparison | revisions
README.md file | annotate | diff | comparison | revisions
base64.c file | annotate | diff | comparison | revisions
base64.h file | annotate | diff | comparison | revisions
libbase64.3 file | annotate | diff | comparison | revisions
test/base64.c file | annotate | diff | comparison | revisions
--- a/Makefile	Wed Jun 02 15:59:46 2021 +0200
+++ b/Makefile	Wed Jun 02 16:37:59 2021 +0200
@@ -1,7 +1,7 @@
 #
 # Makefile -- basic Makefile for libbase64
 #
-# Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
+# Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
 #
 # Permission to use, copy, modify, and/or distribute this software for any
 # purpose with or without fee is hereby granted, provided that the above
@@ -19,7 +19,7 @@
 .POSIX:
 
 CC=             cc
-CFLAGS=         -O3 -DNDEBUG -Wall -Wextra
+CFLAGS=         -O3 -DNDEBUG
 
 .SUFFIXES:
 .SUFFIXES: .c .o
--- a/README.md	Wed Jun 02 15:59:46 2021 +0200
+++ b/README.md	Wed Jun 02 16:37:59 2021 +0200
@@ -4,7 +4,7 @@
 Introduction
 ------------
 
-Base64 encoding and decoding easily in C99.
+Base64 encoding and decoding easily in C.
 
 Features
 --------
@@ -12,6 +12,8 @@
 - base64 encoding,
 - base64 decoding (with base64url support),
 - no dynamic allocation required,
+- only C89 required.
+- less than 200 lines of code.
 
 Quick overview
 --------------
@@ -33,3 +35,10 @@
 
 Note: even with binary data the function `b64_decode` still append a NUL
 terminator. Use the return code from the function to get the size binary data.
+
+Documentation
+-------------
+
+See the libbase64(3) manual page.
+
+	man ./libbase64.3
--- a/base64.c	Wed Jun 02 15:59:46 2021 +0200
+++ b/base64.c	Wed Jun 02 16:37:59 2021 +0200
@@ -62,19 +62,7 @@
 }
 
 size_t
-b64_decode_length(size_t srcsz)
-{
-	return 3 * srcsz / 4;
-}
-
-size_t
-b64_encode_length(size_t srcsz)
-{
-	return 4 * (srcsz / 3 + 1);
-}
-
-size_t
-b64_encode(const char src[], size_t srcsz, char dst[], size_t dstsz)
+b64_encode(const char *src, size_t srcsz, char *dst, size_t dstsz)
 {
 	assert(src);
 	assert(dst);
@@ -85,7 +73,7 @@
 		srcsz = strlen(src);
 
 	while (srcsz && dstsz) {
-		char inputbuf[3] = { 0 };
+		char inputbuf[3] = {0};
 		int count = 0;
 
 		while (srcsz && count < 3) {
@@ -99,14 +87,12 @@
 		}
 
 		*dst++ = b64_lookup(inputbuf[0] >> 2 & 0x3f);
-		*dst++ = b64_lookup((inputbuf[0] << 4 & 0x3f) |
-		                    (inputbuf[1] >> 4 & 0x0f));
+		*dst++ = b64_lookup((inputbuf[0] << 4 & 0x3f) | (inputbuf[1] >> 4 & 0x0f));
 
 		if (count < 2)
 			*dst++ = '=';
 		else
-			*dst++ = b64_lookup((inputbuf[1] << 2 & 0x3c) |
-			                    (inputbuf[2] >> 6 & 0x03));
+			*dst++ = b64_lookup((inputbuf[1] << 2 & 0x3c) | (inputbuf[2] >> 6 & 0x03));
 
 		if (count < 3)
 			*dst++ = '=';
@@ -129,7 +115,7 @@
 }
 
 size_t
-b64_decode(const char src[], size_t srcsz, char dst[], size_t dstsz)
+b64_decode(const char *src, size_t srcsz, char *dst, size_t dstsz)
 {
 	assert(src);
 	assert(dst);
--- a/base64.h	Wed Jun 02 15:59:46 2021 +0200
+++ b/base64.h	Wed Jun 02 16:37:59 2021 +0200
@@ -19,124 +19,35 @@
 #ifndef BASE64_H
 #define BASE64_H
 
-/**
- * \file base64.h
- * \brief Base64 encoding and decoding.
- * \author David Demelier <markand@malikania.fr>
- * \version 2.0.0-dev
- */
-
 #include <stddef.h>
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
-/**
- * Check if the character is a %base64 character, A-Za-z0-9 and +/.
- *
- * \param ch the character to test
- * \return non-zero if valid
- */
+#define B64_ENCODE_LENGTH(x) (4 * ((x) / 3 + 1))
+#define B64_DECODE_LENGTH(x) (3 * ((x) / 4))
+
 int
 b64_isbase64(unsigned char ch);
 
-/**
- * Check if the given character is a valid character in %base64 string,
- * including '='.
- *
- * \param ch the character
- * \return non-zero if the character is valid
- */
 int
 b64_isvalid(unsigned char ch);
 
-/**
- * Get the %base64 character from the 6-bits value.
- *
- * \pre value must be valid (< 64)
- * \param value the value
- * \return the %base64 character for value
- */
 unsigned char
 b64_lookup(unsigned char value);
 
-/**
- * Get the integer value from the %base64 character.
- *
- * \pre b64_isvalid(ch)
- * \param ch the %base64 character
- * \return the integer value for the %base64 character ch
- */
 unsigned char
 b64_rlookup(unsigned char ch);
 
-/**
- * Compute the original data size according to srcsz.
- *
- * \param srcsz the base64 input length
- * \return The pessimist original data size.
- */
 size_t
-b64_decode_length(size_t srcsz);
-
-/**
- * Compute the required size to encode this data.
- *
- * For performance reasons, this function may returns four unused bytes to
- * avoid calculating padding.
- * 
- * \param srcsz the input size
- * \return The number of bytes required to encode the data.
- */
-size_t
-b64_encode_length(size_t srcsz);
+b64_encode(const char *src, size_t srcsz, char *dst, size_t dstsz);
 
-/**
- * Encode the given src into the destination buffer.
- *
- * This function will write at most dstsz bytes into the buffer, including the
- * NUL terminator.
- *
- * If srcsz is -1 then strlen(src) is called to determine the number of bytes
- * in src. Note that binary data may contain embedded 0 and therefore
- * specifying the source size would be required in that case.
- *
- * \pre src != NULL
- * \pre dst != NULL
- * \param src the source to encode
- * \param srcsz the source size or -1 to read until NUL terminator
- * \param dst the destination buffer
- * \param dstsz the destination size
- * \return The number of bytes written or -1 on error and sets errno.
- * \see \ref b64_encode_length
- */
 size_t
-b64_encode(const char src[], size_t srcsz, char dst[], size_t dstsz);
-
-/**
- * Decode the given src into the destination buffer.
- *
- * This function will write at most dstsz bytes into the buffer, including the
- * NUL terminator.
- *
- * If srcsz is -1 then strlen(src) is called to determine the number of bytes
- * in src.
- *
- * \pre src != NULL
- * \pre dst != NULL
- * \param src the source to encode
- * \param srcsz the source size or -1 to read until NUL terminator
- * \param dst the destination buffer
- * \param dstsz the destination size
- * \return The number of bytes written or -1 on error and sets errno.
- * \see \ref b64_decode_length
- */
-size_t
-b64_decode(const char src[], size_t srcsz, char dst[], size_t dstsz);
+b64_decode(const char *src, size_t srcsz, char *dst, size_t dstsz);
 
 #if defined(__cplusplus)
 }
 #endif
 
-#endif // !BASE64_H
+#endif /* !BASE64_H */
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libbase64.3	Wed Jun 02 16:37:59 2021 +0200
@@ -0,0 +1,102 @@
+.\"
+.\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
+.\"
+.\" Permission to use, copy, modify, and/or distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd June 2, 2021
+.Dt LIBBASE64 3
+.Os
+.\" NAME
+.Sh NAME
+.Nm libbase64
+.Nd encode and decode base64
+.\" SYNOPSIS
+.Sh SYNOPSIS
+.In base64.h
+.Fd #define B64_ENCODE_LENGTH(size)
+.Fd #define B64_DECODE_LENGTH(size)
+.Ft size_t
+.Fn b64_encode "const char *src, size_t srcsz, char *dst, size_t dstsz"
+.Ft size_t
+.Fn b64_decode "const char *src, size_t srcsz, char *dst, size_t dstsz"
+.\" DESCRIPTION
+.Sh DESCRIPTION
+This library exposes few functions to encode and decode any kind of input data
+using base64 format.
+.Pp
+The
+.Fn B64_ENCODE_LENGTH
+and
+.Fn B64_DECODE_LENGTH
+macros can be used to compute the required size to encode or decode
+respectively depending on the argument
+.Fa size
+expressed in bytes. They always return the number of bytes required at most
+(depending on padding bytes) but the returned value
+.Em doesn't
+include the NUL terminator.
+.Pp
+The
+.Fn b64_encode
+function reads the input string
+.Fa src
+up to
+.Fa srcsz
+bytes (which can be -1 to read until NUL character) and stores the result into
+argument
+.Fa dst .
+The function writes up to
+.Fa dstsz
+bytes at most (including the NUL terminator).
+.Pp
+The
+.Fn b64_decode
+functions read the base64 encoded (or base64url encoded) input string
+.Fa src
+up to
+.Fa srcsz (which can be -1 to read until NUL character) and stores the decoded
+result into argument
+.Fa dst .
+Ths function writes up to
+.Fa dstsz
+bytes at most (including the NUL terminator). This function always append a NUL
+terminator so make sure to use the return value to get the real binary size if
+required.
+.\" RETURN VALUES
+.Sh RETURN VALUES
+The functions
+.Fn b64_encode
+and
+.Fn b64_decode
+returns the number of bytes written into the
+.Fa dst
+argument (not including the NUL terminator) or (size_t)-1 on error. In that case
+.Va errno
+is set to indicate the error.
+.\" ERRORS
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er ERANGE
+The output
+.Fa dst
+pointer wasn't large enough to store the encoded/decoded data.
+.It Bq Er EILSEQ
+Only set from
+.Fn b64_decode .
+The input string
+.Fa src
+did not contain valid base64 characters.
+.El
+.Sh AUTHORS
+.Nm
+was written by David Demelier <markand@malikania.fr>
--- a/test/base64.c	Wed Jun 02 15:59:46 2021 +0200
+++ b/test/base64.c	Wed Jun 02 16:37:59 2021 +0200
@@ -1,7 +1,7 @@
 /*
  * base64.c -- main test file for base64 (C version)
  *
- * Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
+ * Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
  *
  * Permission to use, copy, modify, and/or distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -227,14 +227,14 @@
 GREATEST_TEST
 test_b64_encode_length_basic(void)
 {
-	GREATEST_ASSERT_EQ(b64_encode_length(1), 4U);
-	GREATEST_ASSERT_EQ(b64_encode_length(2), 4U);
-	GREATEST_ASSERT_EQ(b64_encode_length(3), 8U);
-	GREATEST_ASSERT_EQ(b64_encode_length(4), 8U);
-	GREATEST_ASSERT_EQ(b64_encode_length(5), 8U);
-	GREATEST_ASSERT_EQ(b64_encode_length(6), 12U);
-	GREATEST_ASSERT_EQ(b64_encode_length(7), 12U);
-	GREATEST_ASSERT_EQ(b64_encode_length(8), 12U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(1), 4U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(2), 4U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(3), 8U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(4), 8U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(5), 8U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(6), 12U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(7), 12U);
+	GREATEST_ASSERT_EQ(B64_ENCODE_LENGTH(8), 12U);
 	GREATEST_PASS();
 }
 
@@ -246,11 +246,11 @@
 GREATEST_TEST
 test_b64_decode_length_basic(void)
 {
-	GREATEST_ASSERT_EQ(b64_decode_length(4), 3U);
-	GREATEST_ASSERT_EQ(b64_decode_length(8), 6U);
-	GREATEST_ASSERT_EQ(b64_decode_length(12), 9U);
-	GREATEST_ASSERT_EQ(b64_decode_length(16), 12U);
-	GREATEST_ASSERT_EQ(b64_decode_length(20), 15U);
+	GREATEST_ASSERT_EQ(B64_DECODE_LENGTH(4), 3U);
+	GREATEST_ASSERT_EQ(B64_DECODE_LENGTH(8), 6U);
+	GREATEST_ASSERT_EQ(B64_DECODE_LENGTH(12), 9U);
+	GREATEST_ASSERT_EQ(B64_DECODE_LENGTH(16), 12U);
+	GREATEST_ASSERT_EQ(B64_DECODE_LENGTH(20), 15U);
 	GREATEST_PASS();
 }
 

mercurial