[PATCH 04/28] Thread safety documentation.

[Florian Weimer]

On 08/16/2013 10:32 AM, Alexandre Oliva wrote:
> +@item @code{xguargs}
> +@cindex xguargs
> +
> +Functions marked with @code{xguargs} may use or modify objects passed as
> +arguments without any guards that could guarantee consistency.  To
> +ensure MT- and AS-Safe behavior, callers must ensure that the objects
> +passed in are not modified concurrently by other threads or signal
> +handlers.

I'm not sure if this category makes sense.  Other documents deal with 
this implicitly.  It seems to me that gettimeofday would need this 
annotation:

  @deftypefun int gettimeofday (struct timeval *@var{tp}, struct 
timezone *@var{tzp})
+@safety{@mtsafe{}@assafe{}@acsafe{}}

Or readdir_r:

  @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent 
*@var{entry}, struct dirent **@var{result})
+@safety{@mtsafe{}@asunsafe{selfdeadlock}@acunsafe{lockleak}}

Basically, anything that takes a non-const pointer argument falls into 
that category.  That's why I'm not sure if explicit documentation is needed.

And one nit: Since C offers pass-by-value only, objects passed as 
arguments cannot be modified.  Some indirection has to occur, either a 
pointer dereference or a handle lookup.

-- 
Florian Weimer / Red Hat Product Security Team