>>>>> On Fri, 27 Oct 2006 13:54:30 -0400,
      christos@zoulas.com (Christos Zoulas) said:

> | I think one of acceptable ways is to add the following comment to the
> | implementations of the 8 functions:
> | /*
> |  * Although the specification does not demand that this function is
> |  * async-singal-safe, our syslog_r() implemetation needs it.
> |  */
> | and add the following comment to the callers of the function:
> | /*
> |  * XXX current implementation of the following functions is async-signal-safe:
> |  *	....
> |  */
> | Otherwise we may break the implementation by accident in future.
> | 
> | Another way is to define the functions as async-signal-safe in our
> | manpage, but I think that is overkill.

> If we decide to go this way, I think it is better to document them both
> in the man page and the source.

Well, if we do not document it in the man page, we are free to change
the implemetation of the 8 functions to not async-signal-safe.
Of course we should change the implementation of syslog_ss (or syslog_a)
at that time, though.

>      Aside from being reentrant, openlog_r(), closelog_r(), setlogmask_r,()
>      syslog_r(), vsetlog_r() are also async-signal-safe.  Due to that fact,
>      syslog_r() and vsyslog_r() have the following limitations:

>      1.   The format string cannot contain multi-byte character sequences.

>      2.   Floating point formats are not supported and print ``UnS''.

>      3.   The time of the event is not sent to syslogd(8).

>      4.   The error string in the %m format is not printed symbolically but as
>           ``Error %d''.

>      Because of the above limitations the reentrant versions of the syslog(3)
>      functions should only be used where reentrancy or async-signal-safety is
>      required.  For more information about async-signal-safe functions and
>      signal handlers, see signal(7).

I believe we should avoid the word "reentrant", and should use
"MT-safe" or "multithread-safe" instead, because the word "reentrant"
may mean async-signal-safe in some technical context.
For example, Wikipedia (http://en.wikipedia.org/wiki/Reentrant) says:
	To be reentrant, a function must hold no static data, must not
	return a pointer to static data, must work only on the data
	provided to it by the caller, and must not call non-reentrant
	functions.
Many POSIX "_r" functions are not reentrant in this Wikipedia's sense,
and using the word "reentrant" in the man page may confuse users.
-- 
soda