rid/rid.3

.TH Rid 3 "September 2017" "Version 1.0" "librid API"
.SH NAME
rid \- Rid (Random Id) library.
.SH SYNOPSIS
.B #include <rid.h>
.sp
Link with \fI\-lrid\fP and \fI\-lbsd\fP or `pkg-config --libs rid`
.SH DESCRIPTION
Rids are 16 random bytes generated in a cryptographically secure way and are also good for identification.
.sp
They can serve as a simple alternative to version 4 UUIDs, with the difference being that Rids use all 128 bits for randomly generated identification with no bits being used for version information. Rids, unlike UUIDs, are guaranteed to be cryptographically secure.
.sp
Some use cases for Rids are as ids for decentralized and distributed systems, databases (especially when there is so much information it is unreasonable to use a single file), and serialization (it is independent of endianness and can easily be written to and read from a binary file, plus string conversion is easy and provided by other libraries). If you wish to have general purpose ids for a system, Rids might not be a bad choice.
.sp
.SS Types
.B Rid
represents an identity with random data. It is defined as:
.sp
.nf
typedef unsigned char Rid[16];
.fi
.SS Functions
.BI "void rid_set(Rid " to ", const Rid " from ");"
.br
.BI "int rid_cmp(const Rid " id1 ", const Rid " id2 ");"
.sp
.B rid_set ()
.RI "sets " to " to the value of " from " unless " from " is NULL, in which case " to " is set to random data."
.sp
.B rid_cmp ()
.RI "calls memcmp on " id1 " and " id2 ". " id1 " is the first argument to memcmp and " id2 " is the second."
.SH "Return Value"
The function
.B rid_cmp ()
returns the result of calling
.B memcmp ()
.RI "with " id1 " as the first argument and " id2 " as the second."
.SH EXAMPLES
.SS Comparing Rids
There is nothing special about comparing Rids as they are just 16 bytes of random data. Using the functions provided by this library, this is a beyond simple task. See this example program:
.sp
.nf
#include <stdio.h>
#include <rid.h>

int
main(int argc, char *argv[])
{
	Rid id1;
	Rid id2;

	/* set both Rids to random values */
	rid_set(id1, NULL);
	rid_set(id2, NULL);

	/* rid_cmp () return 0 if both Rids are equal, here they should not
	 * be equal.
	 */
	if (!rid_cmp(id1, id2))
		printf("this should not be printed!\n");

	/* copy id1 into id2 */
	rid_set(id2, id1);

	if (!rid_cmp(id1, id2))
		printf("this WILL be printed!\n");

	return 0;
}
.fi
.SH AUTHOR
Uladox (not just any random identity!)
.SH "AVAILABILITY AND SOURCE"
.B rid
can be found in its repository at https://www.notabug.org/Uladox/rid
.SH "SEE ALSO"
.BR rid_fn85 (3)
.BR rid_hex (3)
.BR libbsd (7)
.BR arc4random_buf (3bsd)
.BR uuid (3)
.BR memcmp (3)