On 02/11/2015 04:28 PM, Michael Kerrisk (man-pages) wrote:
> Hi Ma Shmiao,
>
> On 11 February 2015 at 09:20, Ma Shimiao <mashimiao.fnst@xxxxxxxxxxxxxx> wrote:
>> Hi Michael,
>> On 02/11/2015 03:55 PM, Michael Kerrisk (man-pages) wrote:
>>> On 02/11/2015 08:35 AM, Ma Shimiao wrote:
>>>> The marking matches glibc marking.
>>>>
>>>> Signed-off-by: Ma Shimiao <mashimiao.fnst@xxxxxxxxxxxxxx>
>>>> ---
>>>> man3/fgetgrent.3 | 12 ++++++++++++
>>>> 1 file changed, 12 insertions(+)
>>>>
>>>> diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3
>>>> index 57665dd..e599483 100644
>>>> --- a/man3/fgetgrent.3
>>>> +++ b/man3/fgetgrent.3
>>>> @@ -90,6 +90,18 @@ is set to indicate the cause.
>>>> Insufficient memory to allocate
>>>> .I group
>>>> structure.
>>>> +.SH ATTRIBUTES
>>>> +For an explanation of the terms used in this section, see
>>>> +.BR attributes (7).
>>>> +.TS
>>>> +allbox;
>>>> +lb lb lb
>>>> +l l l.
>>>> +Interface Attribute Value
>>>> +T{
>>>> +.BR fgetgrent ()
>>>> +T} Thread safety MT-Unsafe race:fgrent
>>>
>>> Why the change here in the V2? What does "fgrent" refer to?
>>
>> race:fgrent is right mark, I made a mistake.
>> race:fgrent is similar to race:grent.
>> race:grent is used to indicate data race exists in getgrent(), setgrent() and endgrent().
>> race:fgrent is used to indicate data race exists when using fgetgrent() in multi-thread.
>
> My question then is: how does the reader know that "grent" refers to
> "getgrent(), setgrent() and endgrent()"?
>From definition of race in glibc manual, we get:
If data race exists and objects cause data race are not from user,
then the function should be annotated as MT-Unsafe and marked with race.
And we need a colon and an identifier follows race to tell user what causes data race.
getgrent(), setgrent() and endgrent() are usually used together.
Because they need to share an iterator, then data race occurs between them.
We want users to know when using them together in multi-thread, data race makes them
unsafe in multi-thread. But, we can't definitely write which internal object causes data race.
So, we extract the common string 'grent' from functions' name as a identifier which groups
getgrent(), setgrent() and endgrent() to tell users that the group of *grent() functions
can't be used together in multi-thread.
If a reader understand the definition of race, I think he can know that "grent" refers to
getgrent(), setgrent() and endgrent().
Thanks,
>
> Thanks,
>
> Michael
>
--
Ma Shimiao
Development Dept.I
Nanjing Fujitsu Nanda Software Tech. Co., Ltd.(FNST)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
