[PATCH] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[PATCH] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

The functions strtod(), strtof() and strtold() are thread safe
with exceptions.

Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
---
 man3/strtod.3 | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/man3/strtod.3 b/man3/strtod.3
index 8498a06..43efb50 100644
--- a/man3/strtod.3
+++ b/man3/strtod.3
@@ -42,7 +42,7 @@
 .\"   (michael-dcCOIfDdh9paP0f+8Gpiu5H8eBQqjErGxu+e+x4sQ7A@public.gmane.org)
 .\" Added strof, strtold, aeb, 2001-06-07
 .\"
-.TH STRTOD 3 2010-09-20 "Linux" "Linux Programmer's Manual"
+.TH STRTOD 3 2014-01-20 "Linux" "Linux Programmer's Manual"
 .SH NAME
 strtod, strtof, strtold \- convert ASCII string to floating-point number
 .SH SYNOPSIS
@@ -157,6 +157,18 @@ is stored in
 .TP
 .B ERANGE
 Overflow or underflow occurred.
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR strtod (),
+.BR strtof (),
+and
+.BR strtold ()
+functions are thread-safe with exceptions.
+These functions can be safely used in multithreaded applications,
+as long as
+.BR setlocale (3)
+is not called to change the locale.
 .SH CONFORMING TO
 C89 describes
 .BR strtod (),
-- 
1.8.4.2

--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Michael Kerrisk (man-pages)]

Thanks, Haitao. Applied.

Cheers,

Michael


On 01/20/2014 09:15 AM, Peng Haitao wrote:
> The functions strtod(), strtof() and strtold() are thread safe
> with exceptions.
> 
> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
> ---
>  man3/strtod.3 | 14 +++++++++++++-
>  1 file changed, 13 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/strtod.3 b/man3/strtod.3
> index 8498a06..43efb50 100644
> --- a/man3/strtod.3
> +++ b/man3/strtod.3
> @@ -42,7 +42,7 @@
>  .\"   (michael-dcCOIfDdh9paP0f+8Gpiu5H8eBQqjErGxu+e+x4sQ7A@public.gmane.org)
>  .\" Added strof, strtold, aeb, 2001-06-07
>  .\"
> -.TH STRTOD 3 2010-09-20 "Linux" "Linux Programmer's Manual"
> +.TH STRTOD 3 2014-01-20 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  strtod, strtof, strtold \- convert ASCII string to floating-point number
>  .SH SYNOPSIS
> @@ -157,6 +157,18 @@ is stored in
>  .TP
>  .B ERANGE
>  Overflow or underflow occurred.
> +.SH ATTRIBUTES
> +.SS Multithreading (see pthreads(7))
> +The
> +.BR strtod (),
> +.BR strtof (),
> +and
> +.BR strtold ()
> +functions are thread-safe with exceptions.
> +These functions can be safely used in multithreaded applications,
> +as long as
> +.BR setlocale (3)
> +is not called to change the locale.
>  .SH CONFORMING TO
>  C89 describes
>  .BR strtod (),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Andre Majorel]

On 2014-01-20 16:15 +0800, Peng Haitao wrote:

> The functions strtod(), strtof() and strtold() are thread safe
> with exceptions.

> +The
> +.BR strtod (),
> +.BR strtof (),
> +and
> +.BR strtold ()
> +functions are thread-safe with exceptions.
> +These functions can be safely used in multithreaded applications,
> +as long as
> +.BR setlocale (3)
> +is not called to change the locale.

Is the requirement that all threads be in the same locale ? Or
that the thread that calls strtod() not use setlocale() at all ?
Or maybe that setlocale() not be called by anyone after threads
are created ? Or even that setlocale() not be used AT ALL by the
process ?

It's not obvious to me which it is !

I think that a more specific wording would be useful.

-- 
André Majorel http://www.teaser.fr/~amajorel/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

On 01/20/2014 08:28 PM, Andre Majorel wrote:
>> +.BR strtold ()
>> +functions are thread-safe with exceptions.
>> +These functions can be safely used in multithreaded applications,
>> +as long as
>> +.BR setlocale (3)
>> +is not called to change the locale.
> 

The sentence is from the Oracle Solaris's manpages.

> Is the requirement that all threads be in the same locale ? Or
> that the thread that calls strtod() not use setlocale() at all ?
> Or maybe that setlocale() not be called by anyone after threads
> are created ? Or even that setlocale() not be used AT ALL by the
> process ?
> 
> It's not obvious to me which it is !
> 
> I think that a more specific wording would be useful.
> 

In a locale other than the standard "C" or "POSIX" locales, these function may
recognize additional locale-dependent syntax.
When these functions and setlocale() are simultaneously called in multithreaded applications,
these functions will not be thread safe.


-- 
Best Regards,
Peng
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Michael Kerrisk (man-pages)]

On 01/21/2014 04:08 AM, Peng Haitao wrote:
> 
> On 01/20/2014 08:28 PM, Andre Majorel wrote:
>>> +.BR strtold ()
>>> +functions are thread-safe with exceptions.
>>> +These functions can be safely used in multithreaded applications,
>>> +as long as
>>> +.BR setlocale (3)
>>> +is not called to change the locale.
>>
> 
> The sentence is from the Oracle Solaris's manpages.
> 
>> Is the requirement that all threads be in the same locale ? Or
>> that the thread that calls strtod() not use setlocale() at all ?
>> Or maybe that setlocale() not be called by anyone after threads
>> are created ? Or even that setlocale() not be used AT ALL by the
>> process ?
>>
>> It's not obvious to me which it is !
>>
>> I think that a more specific wording would be useful.
>>
> 
> In a locale other than the standard "C" or "POSIX" locales, these function may
> recognize additional locale-dependent syntax.
> When these functions and setlocale() are simultaneously called in multithreaded applications,
> these functions will not be thread safe.

Hello Haitao,

So, do you think maybe a more precise wording would be better in 
the man page?

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

On 01/21/2014 02:19 PM, Michael Kerrisk (man-pages) wrote:
>>> Is the requirement that all threads be in the same locale ? Or
>>> that the thread that calls strtod() not use setlocale() at all ?
>>> Or maybe that setlocale() not be called by anyone after threads
>>> are created ? Or even that setlocale() not be used AT ALL by the
>>> process ?
>>>
>>> It's not obvious to me which it is !
>>>
>>> I think that a more specific wording would be useful.
>>>
>>
>> In a locale other than the standard "C" or "POSIX" locales, these function may
>> recognize additional locale-dependent syntax.
>> When these functions and setlocale() are simultaneously called in multithreaded applications,
>> these functions will not be thread safe.
> 
> Hello Haitao,
> 
> So, do you think maybe a more precise wording would be better in 
> the man page?
> 

Maybe added simultaneously is better?

These functions can be safely used in multithreaded applications,
as long as setlocale(3) is not called to change the locale.

->

These functions can be safely used in multithreaded applications,
as long as setlocale(3) is not simultaneously called to change the locale.


-- 
Best Regards,
Peng

> Thanks,
> 
> Michael
> 
> 
> 

--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Andre Majorel]

On 2014-01-21 14:38 +0800, Peng Haitao wrote:

> Maybe added simultaneously is better?
> 
> These functions can be safely used in multithreaded
> applications, as long as setlocale(3) is not called to change
> the locale.
> 
> ->
> 
> These functions can be safely used in multithreaded
> applications, as long as setlocale(3) is not simultaneously
> called to change the locale.

I find the word "simultaneous" ambiguous when it comes to events
whose duration is non-zero.

Is the problem as simple as this ?
1) A thread is interrupted while it's running strto*().
2) The other thread calls setlocale().
3) strto*() resumes with locale data which is now inconsistent
   or invalid.

If that is the case, how about :

  These functions can be safely used in multithreaded
  applications, as long as the locale is not changed during
  their execution.

or

  These functions can be safely used in multithreaded
  applications, as long as setlocale() is not called during
  their execution.

(depending on whether calling setlocale() would invalidate the
data returned by a previous call to setlocale() with the same
argument).

-- 
André Majorel http://www.teaser.fr/~amajorel/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

On 01/21/2014 09:52 PM, Andre Majorel wrote:
>> These functions can be safely used in multithreaded
>> applications, as long as setlocale(3) is not simultaneously
>> called to change the locale.
> 
> I find the word "simultaneous" ambiguous when it comes to events
> whose duration is non-zero.
> 
> Is the problem as simple as this ?
> 1) A thread is interrupted while it's running strto*().
> 2) The other thread calls setlocale().
> 3) strto*() resumes with locale data which is now inconsistent
>    or invalid.
> 
> If that is the case, how about :
> 
>   These functions can be safely used in multithreaded
>   applications, as long as the locale is not changed during
>   their execution.
> 

The above sentence is OK, but I think added setlocale(3) is better, thanks.

These functions can be safely used in multithreaded
applications, as long as setlocale(3) is not called
to change the locale during their execution.


-- 
Best Regards,
Peng

> or
> 
>   These functions can be safely used in multithreaded
>   applications, as long as setlocale() is not called during
>   their execution.
> 
> (depending on whether calling setlocale() would invalidate the
> data returned by a previous call to setlocale() with the same
> argument).
> 
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Andre Majorel]

On 2014-01-22 10:15 +0800, Peng Haitao wrote:
> On 01/21/2014 09:52 PM, Andre Majorel wrote:
> >> These functions can be safely used in multithreaded
> >> applications, as long as setlocale(3) is not simultaneously
> >> called to change the locale.
> > 
> > I find the word "simultaneous" ambiguous when it comes to events
> > whose duration is non-zero.
> > 
> > Is the problem as simple as this ?
> > 1) A thread is interrupted while it's running strto*().
> > 2) The other thread calls setlocale().
> > 3) strto*() resumes with locale data which is now inconsistent
> >    or invalid.
> > 
> > If that is the case, how about :
> > 
> >   These functions can be safely used in multithreaded
> >   applications, as long as the locale is not changed during
> >   their execution.
> 
> The above sentence is OK, but I think added setlocale(3) is
> better, thanks.
> 
> These functions can be safely used in multithreaded
> applications, as long as setlocale(3) is not called
> to change the locale during their execution.

This wording can be interpreted to mean that calling setlocale()
*is* permitted as long as the locale doesn't change. If that is
really what you mean, then no further objections from me.
Otherwise, my recommendation would be

  These functions can be safely used in multithreaded
  applications, as long as setlocale() is not called during
  their execution.

-- 
André Majorel http://www.teaser.fr/~amajorel/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

On 01/22/2014 04:29 PM, Andre Majorel wrote:
>>> If that is the case, how about :
>>>
>>>   These functions can be safely used in multithreaded
>>>   applications, as long as the locale is not changed during
>>>   their execution.
>>
>> The above sentence is OK, but I think added setlocale(3) is
>> better, thanks.
>>
>> These functions can be safely used in multithreaded
>> applications, as long as setlocale(3) is not called
>> to change the locale during their execution.
> 
> This wording can be interpreted to mean that calling setlocale()
> *is* permitted as long as the locale doesn't change. If that is
> really what you mean, then no further objections from me.

That is what I mean.
Thanks.


-- 
Best Regards,
Peng

> Otherwise, my recommendation would be
> 
>   These functions can be safely used in multithreaded
>   applications, as long as setlocale() is not called during
>   their execution.
> 

--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Michael Kerrisk (man-pages)]

Hello Haitao,

On Wed, Jan 22, 2014 at 9:57 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
>
> On 01/22/2014 04:29 PM, Andre Majorel wrote:
>>>> If that is the case, how about :
>>>>
>>>>   These functions can be safely used in multithreaded
>>>>   applications, as long as the locale is not changed during
>>>>   their execution.
>>>
>>> The above sentence is OK, but I think added setlocale(3) is
>>> better, thanks.
>>>
>>> These functions can be safely used in multithreaded
>>> applications, as long as setlocale(3) is not called
>>> to change the locale during their execution.
>>
>> This wording can be interpreted to mean that calling setlocale()
>> *is* permitted as long as the locale doesn't change. If that is
>> really what you mean, then no further objections from me.
>
> That is what I mean.

Can I just confirm what I understand from this conversation:

* A call to strtod() is thread-safe so long as no other thread uses
setlocale() to change the locale *during* the execution of strtod().
* If a call to setlocale() changes the locale *before* a call to
strtod(), then the call to strtod() is still thread safe.

Correct?

Thanks,

Michael


> --
> Best Regards,
> Peng
>
>> Otherwise, my recommendation would be
>>
>>   These functions can be safely used in multithreaded
>>   applications, as long as setlocale() is not called during
>>   their execution.
>>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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] strtod.3: ATTRIBUTES: Note functions that are thread safe with exceptions

[Peng Haitao]

On 01/22/2014 06:41 PM, Michael Kerrisk (man-pages) wrote:
>>> This wording can be interpreted to mean that calling setlocale()
>>> *is* permitted as long as the locale doesn't change. If that is
>>> really what you mean, then no further objections from me.
>>
>> That is what I mean.
> 
> Can I just confirm what I understand from this conversation:
> 
> * A call to strtod() is thread-safe so long as no other thread uses
> setlocale() to change the locale *during* the execution of strtod().
> * If a call to setlocale() changes the locale *before* a call to
> strtod(), then the call to strtod() is still thread safe.
> 
> Correct?
> 

Yes, it is correct.


-- 
Best Regards,
Peng

> Thanks,
> 
> Michael
> 
> 
>> --
>> Best Regards,
>> Peng
>>
>>> Otherwise, my recommendation would be
>>>
>>>   These functions can be safely used in multithreaded
>>>   applications, as long as setlocale() is not called during
>>>   their execution.
>>>
>>
> 
> 
> 

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