Re: [MTASCsft PATCH 09/??] MT-, AS- and AC-Safety docs: manual/errno.texi

[Alexandre Oliva <aoliva 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