Subject: Re: syslog_r (Re: CVS commit: src/lib/libc)
To: Christos Zoulas <firstname.lastname@example.org>
From: SODA Noriyuki <email@example.com>
Date: 10/28/2006 03:30:46
>>>>> On Fri, 27 Oct 2006 13:54:30 -0400,
firstname.lastname@example.org (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
Many POSIX "_r" functions are not reentrant in this Wikipedia's sense,
and using the word "reentrant" in the man page may confuse users.