Bug 13595 - missing details about how to use BSD random number function APIs
Summary: missing details about how to use BSD random number function APIs
Status: NEW
Alias: None
Product: glibc
Classification: Unclassified
Component: manual (show other bugs)
Version: 2.14
: P2 normal
Target Milestone: ---
Assignee: Roland McGrath
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2012-01-14 17:18 UTC by Bruno Haible
Modified: 2014-06-27 11:11 UTC (History)
0 users

See Also:
Host:
Target:
Build:
Last reconfirmed:
fweimer: security-


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Bruno Haible 2012-01-14 17:18:43 UTC
3 problems with the documentation, node "BSD Random",
title "BSD Random Number Functions":

1) The doc says that the prototype of the 'initstate' function is
void * initstate (unsigned int SEED, void *STATE, size_t SIZE)
But in reality, in <stdlib.h>, it is
char * initstate (unsigned int SEED, char *STATE, size_t SIZE)

2) It is unclear whether the function initstate() has to be called once
before the first call to random(). The doc should say whether it needs to
be called first or not.

3) It is unclear whether the function initstate_r() has to be called once,
to initialize a 'struct random_data', before the first call to random_r() on
this random-number generator. Also, it is unclear whether the memory area
of the 'struct random_data' has to be cleared first, using memset(), before
the first use of initstate_r() on it. Currently GNU recutils 1.5 uses the
initialization sequence

  char random_state[128];
  struct random_data random_data;

  memset (&random_data, 0, sizeof (random_data));
  initstate_r (time(NULL), (char *) &random_state, 128, &random_data);

The doc should say whether memset() is needed first, and whether initstate_r()
is needed then.