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: Alexandre Oliva <aoliva at redhat dot com>
- To: "Carlos O'Donell" <carlos at redhat dot com>
- Cc: codonell at redhat dot com, libc-alpha at sourceware dot org
- Date: Sat, 01 Feb 2014 03:13:14 -0200
- 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>
On Feb 1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
> On 01/31/2014 09:57 PM, Alexandre Oliva wrote:
>> The cases of brk(filedes) and tcattr(filedes) name actual properties
>> that may conflict with other functions that set properties of a
>> terminal, as mentioned under âtermâ.
> Why not just use term then?
The definition of term implies a temporary setting of attributes of the
controlling terminal, later restored. This doesn't quite fit tcflow,
although it would fit tcsendbreak if it weren't for the fact that
tcsendbreak operates on a given file descriptor, which may or may not be
the controlling terminal.
> The problem I have is that this violates what it says in "race"
> specifically:
> ~~~
> We will annotate, with @code{race} followed by a colon and the
> argument name, functions that take such objects but that do not take
> care of synchronizing access to them by default.
> ~~~
This is one case of race that involves races on user-supplied arguments,
which users must guard against. This note is applied only when the
argument has an opaque type. int fd surely doesn't look opaque, but if
it's a key into a kernel-internal data structure whose members point to
terminal settings, is it opaque?
> In tcflow for example we have "race:tcattr(filedes)/bsd".
> The string after the colon is not an argument name.
The other case of race is that of internal data structures, which
terminal attributes are IMHO, accepts more general identifiers.
> I'd expect "race:filedes/bsd term/bsd" perhaps.
After some IRC conversation, we converged on dropping brk(filedes) in
favor of tcattr(filedes), with an update to the definition of term to
make this conflict clearer.
Here's the resulting intro.texi patch. I'll post the updated
terminal.texi patch in its own subthread.
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 | 43 ++++++++++++++++++++++++++++++++++++++++---
1 file changed, 40 insertions(+), 3 deletions(-)
diff --git a/manual/intro.texi b/manual/intro.texi
index fb501a6..fcbdacf 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 mutexes 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,42 @@ 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}.
+
+
+@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
--
Alexandre Oliva, freedom fighter http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/ FSF Latin America board member
Free Software Evangelist Red Hat Brazil Toolchain Engineer