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 ' \"'. > 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 ' \"'. > however, > because functions that modify the this data structure are all marked with Should delete 'this '. > .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 ','. > \" or AS-Unsafe, Should use '.\"' > 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'. -- Best Regards, Peng > and > .I /one_per_line > indicate the preceding marker only applies when argument > .I ps > is NULL, or global variable > .I one_per_line > is nonzero. > > When all marks that render a function unsafe are > adorned with such conditions, > and none of the named conditions hold, > then the function can be regarded as safe. > .SH SEE ALSO > .BR pthreads (7) > -- 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
