srand - seed the pseudo-random number generator

SYNOPSIS

<srand $seed>

DESCRIPTION
The srand function "seeds" the pseudo-random number generator with $seed, which helps determine what sequence of pseudo-random numbers will be returned in future calls to rand and randpick.

When openssl is set as the randprovider (default; see <vxcp randprovider>, here), all values of $seed (as strings) are added to the existing entropy for the random number generator, and Ok is returned on success, or zero values on error (e.g. OpenSSL library cannot be loaded). Note that unlike with the system provider, with openssl the current entropy (seed) cannot be obtained nor cleared; nor can a previous sequence be reproduced by setting a fixed seed.

When system is the randprovider, $seed (as an unsigned integer) is set as the (sole) generator seed, if a non-empty value is given. This can be used either to help ensure the sequence is different each run (with a random seed), or to generate the same sequence on a subsequent run (with the same seed) i.e. for "reproducibly random" results. The previous seed (as an integer) is always returned, or zero values if no seed has been set (nor auto-generated) yet. (Thus the existing seed can be obtained with <srand "">, without disturbing or creating one.)

The pseudo-random number generator does not normally need seeding, as both providers will automatically seed upon first use of rand or a related function.

The openssl provider (see <vxcp randprovider>, here) was added in version 8.01.1773857975 20260318. Previous versions also returned empty string (instead of zero values) when no previous seed was present.

DIAGNOSTICS
For the openssl provider (default), srand returns Ok on success or zero values on failure. For the system provider, srand returns the previous seed as a long, or zero values if no seed has been set nor generated.

EXAMPLE

<vxcp "randprovider" "system">
  <srand 12345>
  <while $loop lt 10>
    <rand 0 10> $ret
  </while>

The output will always produce the same sequence of "random" numbers on a given platform.

CAVEATS
The srand function was added Mar. 16 2000.

The reproducibility of numbers requires the system randprovider be set, which is likely a less-random provider.

The openssl provider (see <vxcp randprovider>, here) was added in version 8.01.1773857975 20260318. Previous versions also returned empty string (instead of zero values) when no previous seed was present.

Note the differing success return types, depending on randprovider (error always returns zero values, or empty string in older versions).

With the openssl provider (default), adding varbyte entropy will stop before the first nul byte in each value, as this is a user function.

SEE ALSO
rand, randpick