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: Fri, 31 Jan 2014 23:08:33 -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>
On Jan 31, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
> We should not add things that we have not described in the introduction.
How about this?
(I've also dropped comments about the need to revisit some markers that
I've already revisied; they shouldn't have made it in the first place)
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 | 38 ++++++++++++++++++++++++++++++++++++--
1 file changed, 36 insertions(+), 2 deletions(-)
diff --git a/manual/intro.texi b/manual/intro.texi
index fb501a6..3387dc1 100644
--- a/manual/intro.texi
+++ b/manual/intro.texi
@@ -698,7 +698,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 +728,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 +853,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{:brk(fd)} to denote the @code{brk} terminal property
+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