diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | manual/intro.texi | 48 |
2 files changed, 50 insertions, 3 deletions
diff --git a/ChangeLog b/ChangeLog index f02ccc78ab..1f8abd4f63 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2014-02-01 Alexandre Oliva <aoliva@redhat.com> + * manual/intro.texi: Document safety identifiers and + conditionals. + +2014-02-01 Alexandre Oliva <aoliva@redhat.com> + * manual/string.texi (wcstok): Fix prototype. (wcstok, strtok, strtok_r): Adjust reentrancy remarks. diff --git a/manual/intro.texi b/manual/intro.texi index fb501a67f9..0f5785990b 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -669,7 +669,10 @@ concurrent and reentrant interactions with it, by not using it in signal handlers or blocking signals that might use it, and holding a lock while calling these functions and interacting with the terminal. This lock should also be used for mutual exclusion with functions marked with -@code{@mtasurace{:tcattr}}. +@code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for +the controlling terminal. The caller may use a single mutex for +simplicity, or use one mutex per terminal, even if referenced by +different file descriptors. Functions marked with @code{term} as an AC-Safety issue are supposed to restore terminal settings to their original state, after temporarily @@ -698,7 +701,6 @@ taken into account in certain classes of programs: @itemize @bullet -@c revisit: uses are mt-safe, distinguish from const:locale @item @code{locale} @cindex locale @@ -729,7 +731,6 @@ constant in these contexts, which makes the former safe. @c because of the unexpected locale changes. -@c revisit: this was incorrectly used as an mt-unsafe marker. @item @code{env} @cindex env @@ -855,6 +856,47 @@ properties we documented are identical to those mandated by POSIX for the corresponding functions. +@item @code{:identifier} +@cindex :identifier + +Annotations may sometimes be followed by identifiers, intended to group +several functions that e.g. access the data structures in an unsafe way, +as in @code{race} and @code{const}, or to provide more specific +information, such as naming a signal in a function marked with +@code{sig}. It is envisioned that it may be applied to @code{lock} and +@code{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 +e.g. @code{:buf(arg)} to denote a buffer associated with the argument +@var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a +file descriptor @var{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. + + +@item @code{/condition} +@cindex /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 +@code{/hurd} or @code{/!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. @code{/!ps} and +@code{/one_per_line} indicate the preceding marker only applies when +argument @var{ps} is NULL, or global variable @var{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. + + @end itemize |