Re: getpass documentation

[Simon Josefsson]

Bruno Haible <address@hidden> writes:

> Simon Josefsson wrote:
>> 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.
>
> Good point.

Alas, a false one.

>> Another way of looking at this is that
>> there is a memory leak in the gnulib 'getpass' module.
>
> It's hard to argue this way: getpass() is not specified by a standard.

It is a memory leak regardless of whether it is standardized.

>> 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
>>  
>
> The way you wrote it here, it is not clear which module provides "this
> implementation". The "Gnulib module" field is "---"...
>
> Can you change the "Gnulib module" field to "getpass or getpass-gnu" and
> then set up a 3-way structure like in doc/posix-functions/snprintf.texi?
> The goal is to make clear to the reader which module he needs if he wants
> a particular portability problem fixed.
>
> Another, minor point is: "This implementation returns password of arbitrary
> length" is incorrect English syntax for me. "a password"? "passwords"?

Thanks, below is an updated patch.

Btw, to document the memory leak, should we add something like:

Problems introduced by Gnulib:
@itemize
@item
There is a memory leak of the last password read using this function.
@end itemize

/Simon

diff --git a/doc/glibc-functions/getpass.texi b/doc/glibc-functions/getpass.texi
index b805cf5..0f2992d 100644
--- a/doc/glibc-functions/getpass.texi
+++ b/doc/glibc-functions/getpass.texi
@@ -2,15 +2,23 @@
 @subsection @code{getpass}
 @findex getpass
 
-Gnulib module: ---
+Gnulib module: getpass or getpass-gnu
 
-Portability problems fixed by Gnulib:
+Portability problems fixed by either Gnulib module @code{getpass} or 
@code{getpass-gnu}:
 @itemize
address@hidden
+This function is missing on some platforms:
+mingw, BeOS.
 @end itemize
 
-Portability problems not fixed by Gnulib:
+Portability problems fixed by Gnulib module @code{getpass-gnu}:
 @itemize
 @item
-This function is missing on some platforms:
-mingw, BeOS.
+The gnulib implementation return a password of arbitrary length read
+from /dev/tty (or stdin), other implementations may truncate the
+password to PASS_MAX or 8 characters.
address@hidden itemize
+
+Portability problems not fixed by Gnulib:
address@hidden
 @end itemize