In FreeBSD 11.2, the timer_create(2) manpage mentions the SIGEV_SIGNO symbol as a possible value for the evp->sigev_notify field. This symbol is not defined in any of the base headers. I suppose it should had been written as SIGEV_SIGNAL instead. Likewise, in the same manpage, SIGEV_THREAD_ID is mentioned for the same struct member, however this (defined) symbol refers to kernel threads. I guess that SIGEV_THREAD should had been used instead. For reference, please see /usr/include/sys/signal.h and https://pubs.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_04.html#tag_02_04_02 It looks like the error arose from a confusion between the acceptable value of the evp->sigev_signo field and the names of the fields these values refer to, evp->sigev_signo for the SIGEV_SIGNAL value, and evp->sigev_notify_thread_id for the SIGEV_THREAD value. Since I'm trying for the first time to use that syscall I may be wrong.
Created attachment 228079 [details] timer_create(2) patch Clarify the use of evp->sigev_notify. SIGEV_SIGNO -> SIGEV_SIGNAL SIGEV_THREAD_ID -> SIGEV_THREAD By breaking the sigev_notify cases into two paragraphs, I feel the intent is much clearer, even if some words are repeated.
That is indeed clearer however this appears to be inaccurate. If I correctly understand this syscall, for the SIGEV_THREAD case, according to POSIX, no signal is queued when the timer fires. Instead evp->sigev_notify_function is called within the context of "a newly created thread with thread attributes specified by sigev_notify_attributes." sigev_notify_thread_id looks to play no role for this case. Note: I haven't reviewed the implementation, my comment is only based on the POSIX specification. Should we mention that sigev_notify_thread_id is not part of POSIX? Shouldn't we also mention the SIGEV_NONE case?
Created attachment 228113 [details] timer_create(2) patch Rather than trying to describe the notification methods in timer_create(2), add a cross-reference to to sigevent(3). That page has a complete description of all the notification methods, including SIGEV_NONE. FreeBSD supports a number of additional clocks beyond CLOCK_MONOTONIC and CLOCK_REALTIME. Add the POSIX-compliant clocks to the list and mention clock_getres(2) for the other clocks. The default value for sigev_signo depends on clock_id. Document the possible default signal values.
That is the right way to handle this syscall. Thank you.
(In reply to Felix Johnson from comment #3) Do you mind opening a review for this? It looks good to me, but I am not an expert on the technical side of this.