magi%uwocsd.uwo.ca@cornellc.cit.cornell.edu (David Wiseman) (02/03/89)
Machine Type: All machines, SunOS 4.0
Organization: The University of Western Ontario
Department of Computer Science
London Ontario Canada N6A 5B7
Description:
The drand48(3) man page is badly confused. As witness: read the
following paragraph extracted from the man page.
Functions drand48, seed48, and lcong48() are initialization
entry points, one of which should be invoked before either
drand48, drand48, or drand48() is called. (Although it is
not recommended practice, constant default initializer
values will be supplied automatically if drand48, drand48,
or drand48() is called without a prior call to an initiali-
zation entry point.) Functions drand48, drand48, and
drand48() do not require an initialization entry point to be
called first.
You will note that drand48 appears rather often. In the DESCRIPTION
section of this man page, each reference to one of [delnmjs]rand48()
has been rendered drand48. Since the routines are NOT identical, this
can make it difficult for users to decide what is true about the
routines.
It should also be noted that this bug appears in both the online
documentation and in the hardcopy manuals.
Repeat-By:
man 3 drand48
Fix:
Merge it with the 3.5 man page. A quick scan of the 3.5 man page
doesn't show any glaring changes. The 4.0 man page appears to have been
"fixed" up so that it is more easily read. Unfortunately, they managed
to "fix" it too well.
--
David Wiseman, Network Manager magi@uwocsd.uwo.ca
Department of Computer Science magi@uwovax.BITNET
The University of Western Ontario watmath!julian!uwocsd!magi
London Ontario Canada N6A 5B7guy@uunet.uu.net (Guy Harris) (02/10/89)
> The 4.0 man page appears to have been "fixed" up so that it is more > easily read. Unfortunately, they managed to "fix" it too well. Change "they" to "it", and the problem is explained; the "()" was added to function references in the man page by a mondo shell/"sed" script. Unfortunately, computers are really rather stupid; hand them a script and they do what they're told to do, not what you wanted them to do. Here's a "diff -c" script that fixes the problem (and also adds some "()"s that the script in question missed). If you have "patch", just use it to apply this script to to "drand48.3"; if you don't have "patch", find somebody who does (it's in the "comp.sources.unix" archive, and probably in other places on "uunet"/"uu.uu.net") and grab it, because it's an *extremely* useful program. [[ Patch is also available in the Rice archives under "public" in four files: "patch.kit1" through "patch.kit4". They can be retrieved via anonymous FTP from the host "titan.rice.edu" or via the archive server. For more information about the archive server, send a mail message containing the word "help" to the address "archive-server@rice.edu". --wnl ]] __________ *** /usr/man/man3/drand48.3 Fri Apr 8 22:21:54 1988 --- ./drand48.3 Fri Feb 3 16:31:31 1989 *************** *** 66,79 **** Functions .B drand48(\|) and ! .B drand48(\|) return non-negative double-precision floating-point values uniformly distributed over the interval $[0.0,~1.0).$ .LP Functions ! .B drand48(\|) and ! .B drand48(\|) return non-negative long integers uniformly distributed over the interval .if n .ig --- 66,79 ---- Functions .B drand48(\|) and ! .B erand48(\|) return non-negative double-precision floating-point values uniformly distributed over the interval $[0.0,~1.0).$ .LP Functions ! .B lrand48(\|) and ! .B nrand48(\|) return non-negative long integers uniformly distributed over the interval .if n .ig *************** *** 84,92 **** .. .LP Functions ! .B drand48(\|) and ! .B drand48(\|) return signed long integers uniformly distributed over the interval .if n .ig $[-2 sup 31 ,~2 sup 31 ).$ --- 84,92 ---- .. .LP Functions ! .B mrand48(\|) and ! .B jrand48(\|) return signed long integers uniformly distributed over the interval .if n .ig $[-2 sup 31 ,~2 sup 31 ).$ *************** *** 96,124 **** .. .LP Functions ! .BR drand48 , ! .BR seed48 , and .B lcong48(\|) are initialization entry points, one of which should be invoked before either ! .BR drand48 , ! .BR drand48 , or ! .B drand48(\|) is called. (Although it is not recommended practice, constant default initializer values will be supplied automatically if ! .BR drand48 , ! .BR drand48 , or ! .B drand48(\|) is called without a prior call to an initialization entry point.) Functions ! .BR drand48 , ! .BR drand48 , and ! .B drand48(\|) do not require an initialization entry point to be called first. .LP All the routines work by generating a sequence of 48-bit integer values, --- 96,124 ---- .. .LP Functions ! .BR srand48(\|) , ! .BR seed48(\|) , and .B lcong48(\|) are initialization entry points, one of which should be invoked before either ! .BR drand48(\|) , ! .BR lrand48(\|) , or ! .B mrand48(\|) is called. (Although it is not recommended practice, constant default initializer values will be supplied automatically if ! .BR drand48(\|) , ! .BR lrand48(\|) , or ! .B mrand48(\|) is called without a prior call to an initialization entry point.) Functions ! .BR erand48(\|) , ! .BR nrand48(\|) , and ! .B jrand48(\|) do not require an initialization entry point to be called first. .LP All the routines work by generating a sequence of 48-bit integer values, *************** *** 152,164 **** .RE .LP The value returned by any of the functions ! .BR drand48 , ! .BR drand48 , ! .BR drand48 , ! .BR drand48 , ! .BR drand48 , or ! .B drand48(\|) is computed by first generating the next 48-bit $X sub i$ in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of $X sub i$ --- 152,164 ---- .RE .LP The value returned by any of the functions ! .BR drand48(\|) , ! .BR erand48(\|) , ! .BR lrand48(\|) , ! .BR nrand48(\|) , ! .BR mrand48(\|) , or ! .B jrand48(\|) is computed by first generating the next 48-bit $X sub i$ in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of $X sub i$ *************** *** 165,181 **** and transformed into the returned value. .LP The functions ! .BR drand48 , ! .BR drand48 , and ! .B drand48(\|) store the last 48-bit $X sub i$ generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions ! .BR drand48 , ! .BR drand48 , and ! .B drand48(\|) require the calling program to provide storage for the successive $X sub i$ values in the array specified as an argument when the functions are invoked. --- 165,181 ---- and transformed into the returned value. .LP The functions ! .BR drand48(\|) , ! .BR lrand48(\|) , and ! .B mrand48(\|) store the last 48-bit $X sub i$ generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions ! .BR erand48(\|) , ! .BR nrand48(\|) , and ! .B jrand48(\|) require the calling program to provide storage for the successive $X sub i$ values in the array specified as an argument when the functions are invoked. *************** *** 184,193 **** array and pass it as an argument. By using different arguments, functions ! .BR drand48 , ! .BR drand48 , and ! .B drand48(\|) allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers, that is, --- 184,193 ---- array and pass it as an argument. By using different arguments, functions ! .BR erand48(\|) , ! .BR nrand48(\|) , and ! .B jrand48(\|) allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers, that is, *************** *** 197,203 **** numbers for the other streams. .LP The initializer function ! .B drand48(\|) sets the high-order 32 bits of $X sub i$ to the 32 bits contained in its argument. The low-order 16 bits of $X sub i$ are set to the arbitrary value --- 197,203 ---- numbers for the other streams. .LP The initializer function ! .B srand48(\|) sets the high-order 32 bits of $X sub i$ to the 32 bits contained in its argument. The low-order 16 bits of $X sub i$ are set to the arbitrary value *************** *** 209,217 **** argument array. In addition, the previous value of $X sub i$ is copied into a 48-bit internal buffer, used only by ! .BR seed48 , and a pointer to this buffer is the value returned by ! .BR seed48 . This returned pointer, which can just be ignored if not needed, is useful if a program is to be restarted from a given point at some future time \(em use the pointer to get at and store the last $X sub i$ value, and --- 209,217 ---- argument array. In addition, the previous value of $X sub i$ is copied into a 48-bit internal buffer, used only by ! .BR seed48(\|) , and a pointer to this buffer is the value returned by ! .BR seed48(\|) . This returned pointer, which can just be ignored if not needed, is useful if a program is to be restarted from a given point at some future time \(em use the pointer to get at and store the last $X sub i$ value, and *************** *** 232,238 **** specifies the 16-bit addend $c.$ After .B lcong48(\|) has been called, a subsequent call to either ! .B drand48(\|) or .B seed48(\|) will restore the \(lqstandard\(rq multiplier and addend values, $a$ and $c,$ --- 232,238 ---- specifies the 16-bit addend $c.$ After .B lcong48(\|) has been called, a subsequent call to either ! .B srand48(\|) or .B seed48(\|) will restore the \(lqstandard\(rq multiplier and addend values, $a$ and $c,$