[PATCH] strerror: improve strerror_r description

[PATCH] strerror: improve strerror_r description

[Eric Blake]

Signed-off-by: Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---

POSIX requires that perror() not modify the static storage
returned by strerror().  POSIX 2008 and C99 both require that
strerror() never return NULL (a strerror() that always
returns "" for all inputs is valid for C99, but not for POSIX).

http://sourceware.org/bugzilla/show_bug.cgi?id=12204
documents glibc's change to come into compliance with POSIX
regarding strerror_r return value.  The GNU strerror_r use
of buf was confusing - I ended up writing a test program that
proves that buf is unused for valid errnum, but contains
truncated "unknown message" for out-of-range errnum.

See also http://austingroupbugs.net/view.php?id=382

 man3/strerror.3 |   18 +++++++++++-------
 1 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/man3/strerror.3 b/man3/strerror.3
index 37fc95d..8928a1e 100644
--- a/man3/strerror.3
+++ b/man3/strerror.3
@@ -71,10 +71,10 @@ code passed in the argument \fIerrnum\fP, possibly using the
 part of the current locale to select the appropriate language.
 This string must not be modified by the application, but may be
 modified by a subsequent call to
-.BR perror (3)
-or
 .BR strerror ().
-No library function will modify this string.
+No other library function, including
+.BR perror (3),
+will modify this string.

 The
 .BR strerror_r ()
@@ -84,7 +84,7 @@ but is
 thread safe.
 This function is available in two versions:
 an XSI-compliant version specified in POSIX.1-2001
-(available since glibc 2.3.4),
+(available since glibc 2.3.4, but not compliant until glibc 2.13),
 and a GNU-specific version (available since glibc 2.0).
 The XSI-compliant version is provided with the feature test macros
 settings shown in the SYNOPSIS;
@@ -120,7 +120,9 @@ then at most
 .I buflen
 bytes are stored (the string may be truncated if
 .I buflen
-is too small) and the string always includes a terminating null byte.
+is too small and
+.I errnum
+is unknown).  The string always includes a terminating null byte.
 .SH "RETURN VALUE"
 The
 .BR strerror ()
@@ -133,9 +135,10 @@ or an "Unknown error nnn" message if the error number is unknown.
 The XSI-compliant
 .BR strerror_r ()
 function returns 0 on success;
-on error, \-1 is returned and
+on error, glibc 2.13 returns a positive error number, while
+older versions returned \-1 and set
 .I errno
-is set to indicate the error.
+indicate the error instead.
 .SH ERRORS
 .TP
 .B EINVAL
@@ -165,6 +168,7 @@ On some systems,
 .\" e.g., Solaris 8, HP-UX 11
 .BR strerror ()
 returns NULL if the error number is unknown.
+POSIX.1-2008 requires the result to be non-NULL for all inputs.
 On other systems,
 .\" e.g., FreeBSD 5.4, Tru64 5.1B
 .BR strerror ()
-- 
1.7.4

--
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

Re: [PATCH] strerror: improve strerror_r description

[Stefan Puiu]

Hi,

On Fri, Mar 18, 2011 at 12:26 AM, Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> Signed-off-by: Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
[...]
>
> http://sourceware.org/bugzilla/show_bug.cgi?id=12204
> documents glibc's change to come into compliance with POSIX
> regarding strerror_r return value.  The GNU strerror_r use
> of buf was confusing - I ended up writing a test program that
> proves that buf is unused for valid errnum, but contains
> truncated "unknown message" for out-of-range errnum.

Yeah, the only use of the buffer is to format "unknown error: %d" when
the errno is out of range - in all other cases it returns a constant
string (e.g. "Resource temporary unavailable"). strerror() behaves in
a similar way, and IIRC only when errno is out of bounds, strerror()
is not thread-safe on Linux - at least it was the last time I checked.

I did point this out in a glibc bug, but the reception was not that
warm :). I guess it's too late to change things at this point. OTOH,
this also makes using strerror/strerror_r portably more interesting.

>
> See also http://austingroupbugs.net/view.php?id=382
>
>  man3/strerror.3 |   18 +++++++++++-------
>  1 files changed, 11 insertions(+), 7 deletions(-)
>
> diff --git a/man3/strerror.3 b/man3/strerror.3
> index 37fc95d..8928a1e 100644
> --- a/man3/strerror.3
> +++ b/man3/strerror.3
> @@ -71,10 +71,10 @@ code passed in the argument \fIerrnum\fP, possibly using the
>  part of the current locale to select the appropriate language.
>  This string must not be modified by the application, but may be
>  modified by a subsequent call to
> -.BR perror (3)
> -or
>  .BR strerror ().
> -No library function will modify this string.
> +No other library function, including
> +.BR perror (3),
> +will modify this string.
>
>  The
>  .BR strerror_r ()
> @@ -84,7 +84,7 @@ but is
>  thread safe.
>  This function is available in two versions:
>  an XSI-compliant version specified in POSIX.1-2001
> -(available since glibc 2.3.4),
> +(available since glibc 2.3.4, but not compliant until glibc 2.13),
>  and a GNU-specific version (available since glibc 2.0).
>  The XSI-compliant version is provided with the feature test macros
>  settings shown in the SYNOPSIS;
> @@ -120,7 +120,9 @@ then at most
>  .I buflen
>  bytes are stored (the string may be truncated if
>  .I buflen
> -is too small) and the string always includes a terminating null byte.
> +is too small and
> +.I errnum
> +is unknown).  The string always includes a terminating null byte.
>  .SH "RETURN VALUE"
>  The
>  .BR strerror ()
> @@ -133,9 +135,10 @@ or an "Unknown error nnn" message if the error number is unknown.
>  The XSI-compliant
>  .BR strerror_r ()
>  function returns 0 on success;
> -on error, \-1 is returned and
> +on error, glibc 2.13 returns a positive error number, while
> +older versions returned \-1 and set
>  .I errno
> -is set to indicate the error.
> +indicate the error instead.

to indicate the error instead?

>  .SH ERRORS
>  .TP
>  .B EINVAL
> @@ -165,6 +168,7 @@ On some systems,
>  .\" e.g., Solaris 8, HP-UX 11
>  .BR strerror ()
>  returns NULL if the error number is unknown.
> +POSIX.1-2008 requires the result to be non-NULL for all inputs.

Maybe you could mention C99 as well, since you were saying it also
mandates this behavior?

Otherwise, the patch looks ok to me.

>  On other systems,
>  .\" e.g., FreeBSD 5.4, Tru64 5.1B
>  .BR strerror ()
> --
> 1.7.4
>
> --
> 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
>
--
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

Re: [PATCH] strerror: improve strerror_r description

[Eric Blake]

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

On 03/18/2011 03:35 AM, Stefan Puiu wrote:
>> Signed-off-by: Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> [...]
>>
>> http://sourceware.org/bugzilla/show_bug.cgi?id=12204
>> documents glibc's change to come into compliance with POSIX
>> regarding strerror_r return value.  The GNU strerror_r use
>> of buf was confusing - I ended up writing a test program that
>> proves that buf is unused for valid errnum, but contains
>> truncated "unknown message" for out-of-range errnum.
> 

>> +on error, glibc 2.13 returns a positive error number, while
>> +older versions returned \-1 and set
>>  .I errno
>> -is set to indicate the error.
>> +indicate the error instead.
> 
> to indicate the error instead?

Yes.

> 
>>  .SH ERRORS
>>  .TP
>>  .B EINVAL
>> @@ -165,6 +168,7 @@ On some systems,
>>  .\" e.g., Solaris 8, HP-UX 11
>>  .BR strerror ()
>>  returns NULL if the error number is unknown.
>> +POSIX.1-2008 requires the result to be non-NULL for all inputs.
> 
> Maybe you could mention C99 as well, since you were saying it also
> mandates this behavior?

Would make sense.  Do you need me to resubmit with those corrections, or
can you squash it in yourself when applying?

> Otherwise, the patch looks ok to me.

-- 
Eric Blake   eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org    +1-801-349-2682
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [PATCH] strerror: improve strerror_r description

[Stefan Puiu]

On Thu, Mar 24, 2011 at 10:51 PM, Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On 03/18/2011 03:35 AM, Stefan Puiu wrote:
>>> Signed-off-by: Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> [...]
> Would make sense.  Do you need me to resubmit with those corrections, or
> can you squash it in yourself when applying?

I don't have write access to man-pages, so I guess it's better if you resubmit.

Thanks,
Stefan.
--
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

Re: [PATCH] strerror: improve strerror_r description

[Michael Kerrisk (man-pages)]

Eric,

On Fri, Mar 25, 2011 at 9:51 AM, Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On 03/18/2011 03:35 AM, Stefan Puiu wrote:
>>> Signed-off-by: Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> [...]
>>>
>>> http://sourceware.org/bugzilla/show_bug.cgi?id=12204
>>> documents glibc's change to come into compliance with POSIX
>>> regarding strerror_r return value.  The GNU strerror_r use
>>> of buf was confusing - I ended up writing a test program that
>>> proves that buf is unused for valid errnum, but contains
>>> truncated "unknown message" for out-of-range errnum.
>>
>
>>> +on error, glibc 2.13 returns a positive error number, while
>>> +older versions returned \-1 and set
>>>  .I errno
>>> -is set to indicate the error.
>>> +indicate the error instead.
>>
>> to indicate the error instead?
>
> Yes.
>
>>
>>>  .SH ERRORS
>>>  .TP
>>>  .B EINVAL
>>> @@ -165,6 +168,7 @@ On some systems,
>>>  .\" e.g., Solaris 8, HP-UX 11
>>>  .BR strerror ()
>>>  returns NULL if the error number is unknown.
>>> +POSIX.1-2008 requires the result to be non-NULL for all inputs.
>>
>> Maybe you could mention C99 as well, since you were saying it also
>> mandates this behavior?
>
> Would make sense.  Do you need me to resubmit with those corrections, or
> can you squash it in yourself when applying?
>
>> Otherwise, the patch looks ok to me.

Thanks for this patch. I happened to apply another fix from Bernhard
Walle just beforehand, so modified your patch slightly (and included
Stefan's input), to the following:

=====
--- a/man3/strerror.3
+++ b/man3/strerror.3
@@ -71,10 +71,10 @@ code passed in the argument \fIerrnum\fP, possibly using the
 part of the current locale to select the appropriate language.
 This string must not be modified by the application, but may be
 modified by a subsequent call to
-.BR perror (3)
-or
 .BR strerror ().
-No library function will modify this string.
+No library function, including
+.BR perror (3),
+will modify this string.

 The
 .BR strerror_r ()
@@ -84,7 +84,7 @@ but is
 thread safe.
 This function is available in two versions:
 an XSI-compliant version specified in POSIX.1-2001
-(available since glibc 2.3.4),
+(available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13),
 and a GNU-specific version (available since glibc 2.0).
 The XSI-compliant version is provided with the feature test macros
 settings shown in the SYNOPSIS;
@@ -120,7 +120,10 @@ then at most
 .I buflen
 bytes are stored (the string may be truncated if
 .I buflen
-is too small) and the string always includes a terminating null byte.
+is too small and
+.I errnum
+is unknown).
+The string always includes a terminating null byte.
 .SH "RETURN VALUE"
 The
 .BR strerror ()
@@ -132,8 +135,12 @@ or an "Unknown error nnn" message if the error
number is unknown.

 The XSI-compliant
 .BR strerror_r ()
-function returns 0 on success;
-on error, a (positive) error number is returned.
+function returns 0 on success.
+On error,
+a (positive) error number is returned (since glibc 2.13),
+or \-1 is returned and
+.I errno
+is set to indicate the error (glibc versions before 2.13).
 .SH ERRORS
 .TP
 .B EINVAL
@@ -171,6 +178,7 @@ returns a string something like "Error nnn
occurred" and sets
 to
 .B EINVAL
 if the error number is unknown.
+C99 and POSIX.1-2008 require the return value to be non-NULL.
 .SH "SEE ALSO"
 .BR err (3),
 .BR errno (3),
=====

In addition to the above, I added the following, and I'd be happy if
you could ack it.

=====
--- a/man3/strerror.3
+++ b/man3/strerror.3
@@ -133,6 +133,19 @@ functions return
 the appropriate error description string,
 or an "Unknown error nnn" message if the error number is unknown.

+POSIX.1-2001 and POSIX.1-2008 require that a successful call to
+.BR strerror (3)
+shall leave
+.I errno
+unchanged, and note that,
+since no function return value is reserved to indicate an error,
+an application that wishes to check for errors should initialize
+.I errno
+to zero before the call,
+and then check
+.I errno
+after the call.
+
 The XSI-compliant
 .BR strerror_r ()
 function returns 0 on success.
=====

These changes will be in man-pages-3.40.

Cheers,

Michael


-- 
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

Re: [PATCH] strerror: improve strerror_r description

[Eric Blake]

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

On 04/21/2012 06:19 PM, Michael Kerrisk (man-pages) wrote:
> Eric,
> 

> In addition to the above, I added the following, and I'd be happy if
> you could ack it.
> 
> =====
> --- a/man3/strerror.3
> +++ b/man3/strerror.3
> @@ -133,6 +133,19 @@ functions return
>  the appropriate error description string,
>  or an "Unknown error nnn" message if the error number is unknown.
> 
> +POSIX.1-2001 and POSIX.1-2008 require that a successful call to
> +.BR strerror (3)
> +shall leave
> +.I errno
> +unchanged, and note that,
> +since no function return value is reserved to indicate an error,
> +an application that wishes to check for errors should initialize
> +.I errno
> +to zero before the call,
> +and then check
> +.I errno
> +after the call.
> +
>  The XSI-compliant
>  .BR strerror_r ()
>  function returns 0 on success.
> =====

Correct.

-- 
Eric Blake   eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

Re: [PATCH] strerror: improve strerror_r description

[Michael Kerrisk (man-pages)]

On Sun, Apr 22, 2012 at 2:18 PM, Eric Blake <eblake-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> On 04/21/2012 06:19 PM, Michael Kerrisk (man-pages) wrote:
>> Eric,
>>
>
>> In addition to the above, I added the following, and I'd be happy if
>> you could ack it.
>>
>> =====
>> --- a/man3/strerror.3
>> +++ b/man3/strerror.3
>> @@ -133,6 +133,19 @@ functions return
>>  the appropriate error description string,
>>  or an "Unknown error nnn" message if the error number is unknown.
>>
>> +POSIX.1-2001 and POSIX.1-2008 require that a successful call to
>> +.BR strerror (3)
>> +shall leave
>> +.I errno
>> +unchanged, and note that,
>> +since no function return value is reserved to indicate an error,
>> +an application that wishes to check for errors should initialize
>> +.I errno
>> +to zero before the call,
>> +and then check
>> +.I errno
>> +after the call.
>> +
>>  The XSI-compliant
>>  .BR strerror_r ()
>>  function returns 0 on success.
>> =====

Thanks Eric!

-- 
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