summaryrefslogtreecommitdiff
path: root/doc/ref/api-data.texi
diff options
context:
space:
mode:
authorMark H Weaver <mhw@netris.org>2012-01-18 02:36:17 -0500
committerMark H Weaver <mhw@netris.org>2012-01-21 03:22:57 -0500
commitd47db067b63089880e2e202d5a33fd7fe5e41dbe (patch)
tree4942484bcfdc3a877cca2ea9e294d399ed6fc2fc /doc/ref/api-data.texi
parent925172cf529a89f0c5fd81720718971f9059fcfd (diff)
downloadguile-d47db067b63089880e2e202d5a33fd7fe5e41dbe.tar.gz
Add `random-state-from-platform' and `scm_i_random_bytes_from_platform'
* libguile/random.c (scm_random_state_from_platform): New procedure. (scm_i_random_bytes_from_platform): New internal function. * libguile/random.h (scm_random_state_from_platform, scm_i_random_bytes_from_platform): Add prototypes. * doc/ref/api-data.texi (Random): Add documentation.
Diffstat (limited to 'doc/ref/api-data.texi')
-rw-r--r--doc/ref/api-data.texi32
1 files changed, 13 insertions, 19 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 60a214872..bcfbae365 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1865,6 +1865,16 @@ Return a datum representation of @var{state} that may be written out and
read back with the Scheme reader.
@end deffn
+@deffn {Scheme Procedure} random-state-from-platform
+@deffnx {C Function} scm_random_state_from_platform ()
+Construct a new random state seeded from a platform-specific source of
+entropy, appropriate for use in non-security-critical applications.
+Currently @file{/dev/urandom} is tried first, or else the seed is based
+on the time, date, process ID, an address from a freshly allocated heap
+cell, an address from the local stack frame, and a high-resolution timer
+if available.
+@end deffn
+
@defvar *random-state*
The global random state used by the above functions when the
@var{state} parameter is not given.
@@ -1887,29 +1897,13 @@ Guile started up, will always give:
(0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
@end lisp
-To use the time of day as the random seed, you can use code like this:
-
-@lisp
-(let ((time (gettimeofday)))
- (set! *random-state*
- (seed->random-state (+ (car time)
- (cdr time)))))
-@end lisp
-
-@noindent
-And then (depending on the time of day, of course):
+To seed the random state in a sensible way for non-security-critical
+applications, do this during initialization of your program:
@lisp
-(map random (cdr (iota 19)))
-@result{}
-(0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)
+(set! *random-state* (random-state-from-platform))
@end lisp
-For security applications, such as password generation, you should use
-more bits of seed. Otherwise an open source password generator could
-be attacked by guessing the seed@dots{} but that's a subject for
-another manual.
-
@node Characters
@subsection Characters