getpass documentation

[Simon Josefsson]

I noticed that a significant difference between other getpass
implementations and glibc/gnulib's is that the latter allocate the
output buffer.

This makes the gnulib 'getpass' module (not the 'getpass-gnu' module)
rather difficult to use: how do you know whether to de-allocate the
returned string or not?  It depends on whether the system function or
the gnulib replacement was used.  Another way of looking at this is that
there is a memory leak in the gnulib 'getpass' module.

As a minimum, the following seemed appropriate.  Ok to apply, Jim?

/Simon

diff --git a/doc/glibc-functions/getpass.texi b/doc/glibc-functions/getpass.texi
index b805cf5..561b89c 100644
--- a/doc/glibc-functions/getpass.texi
+++ b/doc/glibc-functions/getpass.texi
@@ -6,6 +6,13 @@ Gnulib module: ---
 
 Portability problems fixed by Gnulib:
 @itemize
address@hidden
+This implementation returns password of arbitrary length, other
+implementations truncate it to PASS_MAX or 8 characters.
address@hidden
+This implementation allocate the password using malloc, other
+implementations may return a pointer to a static buffer which must not
+be de-allocated.
 @end itemize
 
 Portability problems not fixed by Gnulib:
diff --git a/modules/getpass-gnu b/modules/getpass-gnu
index af493f9..5093338 100644
--- a/modules/getpass-gnu
+++ b/modules/getpass-gnu
@@ -1,5 +1,6 @@
 Description:
-getpass() function: read a password of arbitrary length from /dev/tty.
+getpass() function: read a password of arbitrary length from /dev/tty
+and allocate output.
 
 Files:
 lib/getpass.h