Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
tags 328269 fixed-upstream thanks Andries, Von: Andries Brouwer [EMAIL PROTECTED] On Mon, Sep 19, 2005 at 07:35:30PM +0200, Hrvoje Niksic wrote: Andries Brouwer [EMAIL PROTECTED] writes: This can be replaced by FreeBSD adds a function void sranddev(void); that initializes the seed for rand() with a value obtained from the /dev/random device. But why waste space on functions on other operating systems that Linux doesn't have? All Unix-like operating systems are rather similar. It is better to describe the Linux situation and mention the differences with other very similar systems than to just give the Linux description. While in general I agree with this sentiment (but I think you were always more inclined to include wide coverage of other implementations than I am), in this particular case there seems little value in the existing text, and I'm unconvinced that modifying it as you suggest elsewhere results in text that really is valuable to the reader. My fix, for man-pages-2.08, is to simply remove the offending text. Cheers, Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/ and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Hrvoje, Better yet, the limited space available in a man page should be spent documenting the API Linux does support. For example, it could mention that RAND_MAX is not 32767, unlike many other systems. It could mention that RAND_MAX+1 causes an overflow on Linux, breaking poorly written code. It could mention that rand(3) should *never* be used for cryptographic purposes. It could mention that standard library functions do not influence the sequence of numbers returned by rand. It could document the period of the random number generator, or that ISO C requires the period to be at least 2**32, if the period is considered an implementation detail and not part of the API. Patches to the man page covering these points would indeed be very welcome. Thanks, Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/ and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
On Tue, Sep 20, 2005 at 02:34:37AM +0200, Hrvoje Niksic wrote: I have provided arguments for my position, to which you failed to respond. You didn't give any reasons why you consider FreeBSD to be very similar to Linux No response is needed. If you do not understand that the specific implementation is irrelevant for the man page author, and that tne APIs in FreeBSD and Linux are very similar then discussion with you is not interesting. Better yet, the limited space available in a man page should be spent documenting the API Linux does support. For example, it could mention that RAND_MAX is not 32767, unlike many other systems. It could mention that RAND_MAX+1 causes an overflow on Linux, breaking poorly written code. It could mention that rand(3) should *never* be used for cryptographic purposes. It could mention that standard library functions do not influence the sequence of numbers returned by rand. It could document the period of the random number generator, or that ISO C requires the period to be at least 2**32, if the period is considered an implementation detail and not part of the API. Some of these remarks could indeed be added to the manual page. Submit a patch. Be careful to distinguish Linux-specific remarks (dependency on Linux kernel) from libc-specific remarks (dependency on libc or glibc or klibc or uClibc etc.) and remarks about standard requirements, and general remarks (like remarks about what is needed for crypto). Be concise and precise. Yes, the period is an implementation detail - the current glibc implementation has a much larger period than the classical Unix version. Classically rand() is bad and random() is much better but for glibc the two are the same. RAND_MAX is 2^31-1 in current glibc, and already had that value in libc4. Andries -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Andries Brouwer [EMAIL PROTECTED] writes: On Tue, Sep 20, 2005 at 02:34:37AM +0200, Hrvoje Niksic wrote: I have provided arguments for my position, to which you failed to respond. You didn't give any reasons why you consider FreeBSD to be very similar to Linux No response is needed. [...] then discussion with you is not interesting. That is dodging the question, and patronizing to boot. You still didn't mention the criteria by which the APIs in FreeBSD and Linux are very similar, and those in e.g. Solaris and AIX are not. All of those aim to follow the same Unix standards, after all, and all have their own additions to those standards. If you do not understand that the specific implementation is irrelevant for the man page author, I understand that very well -- you are misrepresenting my words. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
[Andries Brower CCed since he may have written the original text] Package: manpages-dev Version: 2.02-2 Severity: minor Man page for rand(3) claims the following: FreeBSD adds a function void sranddev(void); that initializes the seed for their bad random generator rand() with a value obtained from their good random generator random(). Strange. This implies that FreeBSD's sranddev() uses the output of random() to seed rand's PRNG. If that were the case, it would indeed be strange, since random(3) is merely an entry point to another generator, which also needs to be seeded, which would make sranddev useless. But that is, of course, not the case. From the FreeBSD manual: The sranddev() function initializes a seed using the random(4) random number device which returns good random numbers, suitable for crypto- graphic use. That makes a lot more sense: sranddev seeds rand's PRNG from the random number *device* which gets entropy from the system's physical interfaces. random(4) referred to here is the random *device* which has nothing to do with the random() *function* (which would be referred to as random(3)). Hrvoje, I see two possible ways of dealing with this: 1. s/random()/random(4)/ in the Linux page. 2. Simply remove this text from the page. What do you think? Cheers, Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/ and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
On Mon, Sep 19, 2005 at 02:58:24PM +0200, Michael Kerrisk wrote: [Andries Brower CCed since he may have written the original text] Package: manpages-dev Version: 2.02-2 Severity: minor Man page for rand(3) claims the following: FreeBSD adds a function void sranddev(void); that initializes the seed for their bad random generator rand() with a value obtained from their good random generator random(). Strange. This can be replaced by FreeBSD adds a function void sranddev(void); that initializes the seed for rand() with a value obtained from the /dev/random device. Andries -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Michael Kerrisk [EMAIL PROTECTED] writes: I see two possible ways of dealing with this: 1. s/random()/random(4)/ in the Linux page. 2. Simply remove this text from the page. What do you think? The first possibility doesn't make sense without also removing the deridive adjective strange, because with changed meaning the function is not really all that strange, is it? Also, I don't see why the man page should enumerate random functions from other operating systems which *don't* exist on Linux? Shouldn't there be enough space used up for functions that we *do* have? When such a function is introduced in glibc, by all means document it. In other words, I think #2 would be appropriate. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Andries Brouwer [EMAIL PROTECTED] writes: This can be replaced by FreeBSD adds a function void sranddev(void); that initializes the seed for rand() with a value obtained from the /dev/random device. But why waste space on functions on other operating systems that Linux doesn't have? -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
On Mon, Sep 19, 2005 at 07:35:30PM +0200, Hrvoje Niksic wrote: Andries Brouwer [EMAIL PROTECTED] writes: This can be replaced by FreeBSD adds a function void sranddev(void); that initializes the seed for rand() with a value obtained from the /dev/random device. But why waste space on functions on other operating systems that Linux doesn't have? All Unix-like operating systems are rather similar. It is better to describe the Linux situation and mention the differences with other very similar systems than to just give the Linux description. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Andries Brouwer [EMAIL PROTECTED] writes: But why waste space on functions on other operating systems that Linux doesn't have? All Unix-like operating systems are rather similar. Except this function has no root in Unix tradition, it is a FreeBSD invention not shared by other Unix-like systems. As far as I can tell, it's not even present on other *BSD flavors. It is better to describe the Linux situation and mention the differences with other very similar systems than to just give the Linux description. How is FreeBSD very similar to Linux? It uses an independently-developed C library and an independently-developed kernel. While I agree that it makes sense to describe historical behavior or the differences between Linux and other *widely accepted* solutions, the sranddev function is neither widely accepted by implementations nor widely used by applications. Therefore it has nothing to do in a manpage of a system that doesn't implement it. Documenting functions found on similar systems, but unsupported by and unimplemented on Linux, will cause clutter due to their sheer number. It's a waste of valuable space better spent on function Linux (glibc) *does* implement. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
On Tue, Sep 20, 2005 at 12:39:55AM +0200, Hrvoje Niksic wrote: [muttering that he does not want to hear about differences between the FreeBSD and the Linux API for the rand() family of functions; don't know why - I always consider info about differences important] But now that I see my text again, let me add one letter and change it into FreeBSD adds a function void sranddev(void); that initializes the seed for rand() with a value obtained from the /dev/urandom device. making it more correct for FreeBSD, DragonflyBSD, MacOS X. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Andries Brouwer [EMAIL PROTECTED] writes: On Tue, Sep 20, 2005 at 12:39:55AM +0200, Hrvoje Niksic wrote: [muttering that he does not want to hear about differences between the FreeBSD and the Linux API for the rand() family of functions; don't know why - I always consider info about differences important] I have provided arguments for my position, to which you failed to respond. You didn't give any reasons why you consider FreeBSD to be very similar to Linux and use that as justification for describing functions not supported on Linux. If you include descriptions of completely non-standard functions found on another OS and not present on Linux, then why not also document various of Solaris, AIX or Windows XP specific functions as well? After all, they contribute to info about differences too. The original wording of that paragraph should be an embarrassment to the author (which I don't claim to be you, I really have no idea who wrote that paragraph), who obviously didn't bother to understand the API he was deriding. It would be best if man pages not written by someone who cared to do the necessary research refrained from documenting the differences between Linux and other systems. Better yet, the limited space available in a man page should be spent documenting the API Linux does support. For example, it could mention that RAND_MAX is not 32767, unlike many other systems. It could mention that RAND_MAX+1 causes an overflow on Linux, breaking poorly written code. It could mention that rand(3) should *never* be used for cryptographic purposes. It could mention that standard library functions do not influence the sequence of numbers returned by rand. It could document the period of the random number generator, or that ISO C requires the period to be at least 2**32, if the period is considered an implementation detail and not part of the API. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#328269: manpages-dev: rand() manpage misrepresents FreeBSD's sranddev()
Package: manpages-dev Version: 2.02-2 Severity: minor Man page for rand(3) claims the following: FreeBSD adds a function void sranddev(void); that initializes the seed for their bad random generator rand() with a value obtained from their good random generator random(). Strange. This implies that FreeBSD's sranddev() uses the output of random() to seed rand's PRNG. If that were the case, it would indeed be strange, since random(3) is merely an entry point to another generator, which also needs to be seeded, which would make sranddev useless. But that is, of course, not the case. From the FreeBSD manual: The sranddev() function initializes a seed using the random(4) random number device which returns good random numbers, suitable for crypto- graphic use. That makes a lot more sense: sranddev seeds rand's PRNG from the random number *device* which gets entropy from the system's physical interfaces. random(4) referred to here is the random *device* which has nothing to do with the random() *function* (which would be referred to as random(3)). -- System Information: Debian Release: testing/unstable APT prefers testing APT policy: (500, 'testing') Architecture: i386 (i686) Shell: /bin/sh linked to /bin/bash Kernel: Linux 2.6.11-1-686 Locale: LANG=en_US, LC_CTYPE=en_US (charmap=ISO-8859-1) Versions of packages manpages-dev depends on: ii manpages 2.02-2 Manual pages about using a GNU/Lin manpages-dev recommends no packages. -- no debconf information -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
