Re: documentation for portable use of 'volatile'

[Paul Eggert]

Ralf Wildenhues <address@hidden> writes:

> If you keep going like this, and we don't destabilize CVS Autoconf much
> in the near future, it would be beneficial to release another version in
> a couple of months, simply for the improved documentation  :-)
> (and some added bug fixes, of course).  Even more so with Bruno's
> function portability section...

Yes, the function portability documentation would be nice to have.  I
haven't had time to look into that yet.

> Some language nits inline

Thanks.  I installed the following, which should address your points
and tone down the negative /* comment */ a bit (one should never be
too confident about 'volatile' :-).

--- autoconf.texi       5 Jul 2006 09:40:56 -0000       1.1056
+++ autoconf.texi       5 Jul 2006 22:05:53 -0000       1.1057
@@ -14827,9 +14827,9 @@ than the buffer.
 
 The keyword @code{volatile} is often misunderstood in portable code.
 Its use inhibits some memory-access optimizations, but programmers often
-wish that it had a different meaning that it actually does.
+wish that it had a different meaning than it actually does.
 
-One area of confusion is the distinction between a volatile objects and
+One area of confusion is the distinction between volatile objects and
 volatile lvalues.  From the C standard's point of view, a volatile
 object has externally visible behavior.  You can think of such objects
 as having little oscilloscope probes attached to them, so that the user
@@ -14841,28 +14841,29 @@ access to ordinary objects.  For example
 
 @example
 /* Declare and access a volatile object.
-   The keyword 'volatile' has an effect here.  */
+   'volatile' has a well-defined effect here.  */
 static int volatile x;
 x = 1;
 
 /* Access two ordinary objects via a volatile lvalue.
-   The keyword 'volatile' has no effect here.  */
+   It's not clear what 'volatile' means here.  */
 int y;
+int *z = malloc (sizeof (int));
 int volatile *p;
 p = &y;
 *p = 1;
-p = malloc (sizeof (int));
+p = z;
 *p = 1;
 @end example
 
 Programmers often wish that @code{volatile} meant ``Perform the memory
 access here and now, without merging several memory accesses, without
-changing the memory word size width, and without reordering.''  But the
+changing the memory word size, and without reordering.''  But the
 C standard does not require this.  For volatile @emph{objects}, accesses
 must be done before the next sequence point; but otherwise merging,
-reordering, and word-size change is allowed.  Worse, in general volatile
address@hidden provide no more guarantees than nonvolatile lvalues, when
-the underlying objects are nonvolatile.
+reordering, and word-size change is allowed.  Worse, volatile
address@hidden provide no more guarantees in general than nonvolatile
+lvalues, when the underlying objects are nonvolatile.
 
 Even when accessing volatile objects, the C standard allows only
 extremely limited signal handlers: the behavior is undefined if a signal