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