RANDOMID(3)

RANDOMID(3) | Library Functions Manual | RANDOMID(3)

# NAME

`randomid`, `randomid_new`, `randomid_delete` —
provide pseudo-random data stream without repetitions

# SYNOPSIS

`#include <sys/types.h>`
`#include <randomid.h>`

uint32_t
`randomid`(randomid_t ctx);

randomid_t
`randomid_new`(int bits, long timeo);

void
`randomid_delete`(randomid_t ctx);

# DESCRIPTION

The `randomid`() function provides pseudo-random data stream, which is guaranteed not to generate the same number twice during a certain duration. ctx is the context which holds internal state for the random number generator.

To initialize a context, randomid_new is used. bits specifies the bitwidth of the value generated by `randomid`(). Currently 32, 20, and 16 are supported. timeo specifies the reinitialization interval in seconds. timeo has to be bigger than `RANDOMID_TIMEO_MIN`. randomid_new returns a dynamically-allocated memory region allocated by malloc(3).

`randomid_delete`() will free(3) the internal state ctx.

The same number may appear after two reinitialization events of the internal state, ctx. Reinitialization happens when the random number generator cycle is exhausted, or timeo seconds have passed since the last reinitialization. For instance, ctx configured to generate 16 bit data stream will reinitialize its internal state every 30000 calls to `randomid`() (or after timeo seconds), therefore the same data will not appear until after 30000 calls to `randomid`() (or after timeo seconds).

The internal state, ctx, determines the data stream generated by `randomid`(). ctx must be allocated per data stream (such as a specific data field). It must not be shared among multiple data streams with different usage.

# EXAMPLES

    #include <stdio.h>
    #include <sys/types.h>
    #include <randomid.h>

    uint32_t
    genid(void)
    {
    	static randomid_t ctx = NULL;

    	if (!ctx)
    		ctx = randomid_new(16, (long)3600);
    	return randomid(ctx);
    }

# ERRORS

`randomid_new`() returns `NULL` on error and sets the external variable errno.

# SEE ALSO

arc4random(3)

# HISTORY

The pseudo-random data stream generator was designed by Niels Provos for OpenBSD IPv4 fragment ID generation. `randomid`() is a generalized version of the generator, reworked by Jun-ichiro itojun Hagino, and was introduced in NetBSD 2.0.

January 5, 2006 | NetBSD 9.5