Re: For review: attributes(7) man page

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hello Haitao,

On 10/27/2014 07:09 AM, Peng Haitao wrote:
> 
> On 10/20/2014 01:47 PM, Michael Kerrisk (man-pages) wrote:
>> .TP
>> .I env
>> Functions marked with
>> .I env
>> as an MT-Safety issue access the
>> environment with
>> .BR getenv (3)
>> or similar, without any guards to ensure
>> safety in the presence of concurrent modifications.
>>
>> We do not mark these functions as MT-Unsafe \" or AS-Unsafe,
> 
> Should add ',' before ' \"'.

Fixed.

>> however,
>> because functions that modify the environment are all marked with
>> .I const:env
>> and regarded as unsafe.
>> Being unsafe, the latter are not to be called when multiple threads
>> are running or asynchronous signals are enabled,
>> and so the environment can be considered
>> effectively constant in these contexts,
>> which makes the former safe.
>> .TP
>> .I hostid
>> The function marked with
>> .I hostid
>> as an MT-Safety issue reads from the system-wide data structures that
>> hold the "host ID" of the machine.
>> These data structures cannot generally be modified atomically.
>> Since it is expected that the "host ID" will not normally change,
>> the function that reads from it
>> .RB ( gethostid (3))
>> is regarded as safe,
>> whereas the function that modifies it
>> .RB ( sethostid (3))
>> is marked with
>> .IR const:hostid ,
>> indicating it may require special care if it is to be called.
>> In this specific case,
>> the special care amounts to system-wide
>> (not merely intra-process) coordination.
>> .TP
>> .I sigintr
>> Functions marked with
>> .I sigintr
>> as an MT-Safety issue access the
>> GNU C Library
>> .I _sigintr
>> internal data structure without any guards to ensure
>> safety in the presence of concurrent modifications.
>>
>> We do not mark these functions as MT-Unsafe \" or AS-Unsafe,
> 
> Should add ',' before ' \"'.

Fixed.

>> however,
>> because functions that modify the this data structure are all marked with
> 
> Should delete 'this '.


Thanks. Better to delete "the" though.

>> .I const:sigintr
>> and regarded as unsafe.
>> Being unsafe,
>> the latter are not to be called when multiple threads are
>> running or asynchronous signals are enabled,
>> and so the data structure can be considered
>> effectively constant in these contexts,
>> which makes the former safe.
>> .\" .TP
>> .\" .I fd
>> .\" Functions annotated with
>> .\" .I fd
>> .\" as an AC-Safety issue may leak file
>> .\" descriptors if asynchronous thread cancellation interrupts their
>> .\" execution.
>> .\" 
>> .\" Functions that allocate or deallocate file descriptors will generally be
>> .\" marked as such.
>> .\" Even if they attempted to protect the file descriptor
>> .\" allocation and deallocation with cleanup regions,
>> .\" allocating a new descriptor and storing its number where the cleanup region
>> .\" could release it cannot be performed as a single atomic operation.
>> .\" Similarly,
>> .\" releasing the descriptor and taking it out of the data structure
>> .\" normally responsible for releasing it cannot be performed atomically.
>> .\" There will always be a window in which the descriptor cannot be released
>> .\" because it was not stored in the cleanup handler argument yet,
>> .\" or it was already taken out before releasing it.
>> .\" .\" It cannot be taken out after release:
>> .\" an open descriptor could mean either that the descriptor still
>> .\" has to be closed,
>> .\" or that it already did so but the descriptor was
>> .\" reallocated by another thread or signal handler.
>> .\" 
>> .\" Such leaks could be internally avoided, with some performance penalty,
>> .\" by temporarily disabling asynchronous thread cancellation.
>> .\" However,
>> .\" since callers of allocation or deallocation functions would have to do
>> .\" this themselves, to avoid the same sort of leak in their own layer,
>> .\" it makes more sense for the library to assume they are taking care of it
>> .\" than to impose a performance penalty that is redundant when the problem
>> .\" is solved in upper layers, and insufficient when it is not.
>> .\" 
>> .\" This remark by itself does not cause a function to be regarded as
>> .\" AC-Unsafe.
>> .\" However, cumulative effects of such leaks may pose a
>> .\" problem for some programs.
>> .\" If this is the case,
>> .\" suspending asynchronous cancellation for the duration of calls
>> .\" to such functions is recommended.
>> .\" .TP
>> .\" .I mem
>> .\" Functions annotated with
>> .\" .I mem
>> .\" as an AC-Safety issue may leak
>> .\" memory if asynchronous thread cancellation interrupts their execution.
>> .\" 
>> .\" The problem is similar to that of file descriptors: there is no atomic
>> .\" interface to allocate memory and store its address in the argument to a
>> .\" cleanup handler,
>> .\" or to release it and remove its address from that argument,
>> .\" without at least temporarily disabling asynchronous cancellation,
>> .\" which these functions do not do.
>> .\" 
>> .\" This remark does not by itself cause a function to be regarded as
>> .\" generally AC-Unsafe.
>> .\" However, cumulative effects of such leaks may be
>> .\" severe enough for some programs that disabling asynchronous cancellation
>> .\" for the duration of calls to such functions may be required.
>> .TP
>> .I cwd
>> Functions marked with
>> .I cwd
>> as an MT-Safety issue may temporarily
>> change the current working directory during their execution,
>> which may cause relative pathnames to be resolved in unexpected ways in
>> other threads or within asynchronous signal or cancellation handlers.
>>
>> This is not enough of a reason to mark so-marked functions as MT-Unsafe
> 
> Should add ','.

Fixed.

>> \" or AS-Unsafe,
> 
> Should use '.\"'

Fixed.

>> but when this behavior is optional (e.g.,
>> .BR nftw (3)
>> with
>> .BR FTW_CHDIR ),
>> avoiding the option may be a good alternative to
>> using full pathnames or file descriptor-relative (e.g.,
>> .BR openat (2))
>> system calls.
>> .\" .TP
>> .\" .I !posix
>> .\" This remark, as an MT-Safety, AS-Safety or AC-Safety
>> .\" note to a function,
>> .\" indicates the safety status of the function is known to differ
>> .\" from the specified status in the POSIX standard.
>> .\" For example, POSIX does not require a function to be Safe,
>> .\" but our implementation is, or vice-versa.
>> .\" 
>> .\" For the time being, the absence of this remark does not imply the safety
>> .\" properties we documented are identical to those mandated by POSIX for
>> .\" the corresponding functions.
>> .TP
>> .I :identifier
>> Annotations may sometimes be followed by identifiers,
>> intended to group several functions that, for example,
>> access the data structures in an unsafe way, as in
>> .I race
>> and
>> .IR const ,
>> or to provide more specific information,
>> such as naming a signal in a function marked with
>> .IR sig .
>> It is envisioned that it may be applied to
>> .I lock
>> and
>> .I corrupt
>> as well in the future.
>>
>> In most cases, the identifier will name a set of functions,
>> but it may name global objects or function arguments,
>> or identifiable properties or logical components associated with them,
>> with a notation such as, for example,
>> .I :buf(arg)
>> to denote a buffer associated with the argument
>> .IR arg ,
>> or
>> .I :tcattr(fd)
>> to denote the terminal attributes of a file descriptor
>> .IR fd .
>>
>> The most common use for identifiers is to provide logical groups of
>> functions and arguments that need to be protected by the same
>> synchronization primitive in order to ensure safe operation in a given
>> context.
>> .TP
>> .I /condition
>> Some safety annotations may be conditional,
>> in that they only apply if a boolean expression involving arguments,
>> global variables or even the underlying kernel evaluates evaluates to true.
>> .\" Such conditions as
>> .\" .I /hurd
>> .\" or
>> .\" .I /!linux!bsd
>> .\" indicate the preceding marker only
>> .\" applies when the underlying kernel is the HURD,
>> .\" or when it is neither Linux nor a BSD kernel, respectively.
>> For example,
>> .I !ps
> 
> Should be '/!ps'.

Good catch! Fixed.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/