Bug 239966 - timer_create(2): undefined and incorrect symbols mentioned as possible value for the evp->sigev_notify field
Summary: timer_create(2): undefined and incorrect symbols mentioned as possible value ...
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Guangyuan Yang
URL:
Keywords: easy, patch
Depends on:
Blocks:
 
Reported: 2019-08-19 13:15 UTC by Bertrand Petit
Modified: 2021-10-01 07:15 UTC (History)
4 users (show)

See Also:


Attachments
timer_create(2) patch (846 bytes, patch)
2021-09-21 03:23 UTC, Felix Johnson
no flags Details | Diff
timer_create(2) patch (1.79 KB, patch)
2021-09-22 05:15 UTC, Felix Johnson
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Bertrand Petit 2019-08-19 13:15:38 UTC
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.
Comment 1 Felix Johnson freebsd_triage 2021-09-21 03:23:00 UTC
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.
Comment 2 Bertrand Petit 2021-09-21 07:54:11 UTC
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?
Comment 3 Felix Johnson freebsd_triage 2021-09-22 05:15:19 UTC
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.
Comment 4 Bertrand Petit 2021-09-23 15:34:07 UTC
That is the right way to handle this syscall. Thank you.