[patch] random.3: Update initstate() return value description to match glibc

[patch] random.3: Update initstate() return value description to match glibc

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 2295 bytes --]

The glibc manual section on initstate
  http://www.gnu.org/software/libc/manual/html_node/BSD-Random.html#index-initstate-2292
makes no mention of NULL on error (which it does mention for setstate).

As proof, the test code

  #include <stdlib.h>
  #include <stdio.h>
  #include <errno.h>
  
  int main(int argc, char **argv)
  {
    void *state = NULL;
    int arg_state = 0;
  
    printf("errno before %d\n", errno);
    state = (void *) initstate(1, (void *) &arg_state, 7);
    printf("errno after %d (EINVAL is %d)\n", errno, EINVAL);
    printf("state returned from bad initstate call: %p\n", state);
  
    return 0;
  }

returns

  errno before 0
  errno after 22 (EINVAL is 22)
  state returned from bad initstate call: 0xb781f040

not

  errno before 0
  errno after 22 (EINVAL is 22)
  state returned from bad initstate call: (nil)

This makes sense because glibc's stdlib/random.c defines __initstate()
to always return ostate (blank lines removed):

  char *
  __initstate (seed, arg_state, n)
       unsigned int seed;
       char *arg_state;
       size_t n;
  {
    int32_t *ostate;
    __libc_lock_lock (lock);
    ostate = &unsafe_state.state[-1];
    __initstate_r (seed, arg_state, n, &unsafe_state);
    __libc_lock_unlock (lock);
    return (char *) ostate;
  }

Personally, I think the behavior specified by the old man page makes
more sense, but I don't imagine the glibc folks want to change their
version.

This patch it against the current Git version of man-pages, and was
generated with 'git format-patch -1' before I altered it to include
the extra information the man-pages project suggested:
  http://www.kernel.org/doc/man-pages/patches.html

W. Trevor King

---
 man3/random.3 |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/man3/random.3 b/man3/random.3
index 7568dc1..6845b98 100644
--- a/man3/random.3
+++ b/man3/random.3
@@ -120,9 +120,10 @@ The
 function returns no value.
 The
 .BR initstate ()
-and
+function returns a pointer to the previous state.
+The
 .BR setstate ()
-functions return a pointer to the previous state
+function returns a pointer to the previous state
 array, or NULL on error.
 .SH ERRORS
 .TP
-- 
1.7.2.2.173.g515cc

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [patch] random.3: Update initstate() return value description to match glibc

[Michael Kerrisk]

Hello Trevor,

On Thu, Sep 16, 2010 at 6:44 PM, W. Trevor King <wking-lbwBIqCsw6A3uPMLIKxrzw@public.gmane.org> wrote:
> The glibc manual section on initstate
>  http://www.gnu.org/software/libc/manual/html_node/BSD-Random.html#index-initstate-2292
> makes no mention of NULL on error (which it does mention for setstate).
>
> As proof, the test code
>
>  #include <stdlib.h>
>  #include <stdio.h>
>  #include <errno.h>
>
>  int main(int argc, char **argv)
>  {
>    void *state = NULL;
>    int arg_state = 0;
>
>    printf("errno before %d\n", errno);
>    state = (void *) initstate(1, (void *) &arg_state, 7);
>    printf("errno after %d (EINVAL is %d)\n", errno, EINVAL);
>    printf("state returned from bad initstate call: %p\n", state);
>
>    return 0;
>  }
>
> returns
>
>  errno before 0
>  errno after 22 (EINVAL is 22)
>  state returned from bad initstate call: 0xb781f040
>
> not
>
>  errno before 0
>  errno after 22 (EINVAL is 22)
>  state returned from bad initstate call: (nil)
>
> This makes sense because glibc's stdlib/random.c defines __initstate()
> to always return ostate (blank lines removed):
>
>  char *
>  __initstate (seed, arg_state, n)
>       unsigned int seed;
>       char *arg_state;
>       size_t n;
>  {
>    int32_t *ostate;
>    __libc_lock_lock (lock);
>    ostate = &unsafe_state.state[-1];
>    __initstate_r (seed, arg_state, n, &unsafe_state);
>    __libc_lock_unlock (lock);
>    return (char *) ostate;
>  }
>
> Personally, I think the behavior specified by the old man page makes
> more sense, but I don't imagine the glibc folks want to change their
> version.
>
> This patch it against the current Git version of man-pages, and was
> generated with 'git format-patch -1' before I altered it to include
> the extra information the man-pages project suggested:
>  http://www.kernel.org/doc/man-pages/patches.html
>
> W. Trevor King

Thanks for the detailed report. I applied the patch for man-pages-3.27.

Thanks,

Michael


> ---
>  man3/random.3 |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/man3/random.3 b/man3/random.3
> index 7568dc1..6845b98 100644
> --- a/man3/random.3
> +++ b/man3/random.3
> @@ -120,9 +120,10 @@ The
>  function returns no value.
>  The
>  .BR initstate ()
> -and
> +function returns a pointer to the previous state.
> +The
>  .BR setstate ()
> -functions return a pointer to the previous state
> +function returns a pointer to the previous state
>  array, or NULL on error.
>  .SH ERRORS
>  .TP
> --
> 1.7.2.2.173.g515cc
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html