This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH 09/??] MT-, AS- and AC-Safety docs: manual/errno.texi
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>
- Cc: codonell at redhat dot com, libc-alpha at sourceware dot org
- Date: Mon, 03 Feb 2014 09:15:55 -0500
- Subject: Re: [MTASCsft PATCH 09/??] MT-, AS- and AC-Safety docs: manual/errno.texi
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home> <or4n4uoncj dot fsf at livre dot home> <oreh3xfnq3 dot fsf_-_ at livre dot home> <52EA0931 dot 4000802 at redhat dot com> <or4n4l6ee0 dot fsf at livre dot home> <52EB67C5 dot 6020608 at redhat dot com> <ord2j7myge dot fsf at livre dot home> <52EC4FB8 dot 6010807 at redhat dot com> <orvbwzleuv dot fsf at livre dot home> <52EC7002 dot 2060609 at redhat dot com> <or38k3l8k5 dot fsf at livre dot home> <52EC858D dot 4050402 at redhat dot com> <ortxcjjs5p dot fsf at livre dot home>
On 02/01/2014 12:52 AM, Alexandre Oliva wrote:
> On Feb 1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
>
>> OK to checkin with typos fixed and some note about why identifiers
>> are important is added.
>
> Thanks, fixed and added. Here's the patch I checked in along with the 3
> patches that depended on this one:
Looks great. Thanks!
> MT-, AS- and AC-safety docs: identifiers and conditionals
>
> From: Alexandre Oliva <aoliva@redhat.com>
>
> for ChangeLog
>
> * manual/intro.texi: Document safety identifiers and
> conditionals.
> ---
> manual/intro.texi | 48 +++++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 45 insertions(+), 3 deletions(-)
>
> diff --git a/manual/intro.texi b/manual/intro.texi
> index fb501a6..0f57859 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
>
>
>
>