Hi Scott, Scott Cheloha wrote on Wed, Jun 30, 2021 at 03:15:31PM -0500:
> As it would turn out, there are not one, but *two* simplified > interfaces to setitimer(2). We just cleaned up the alarm(3) manpage, > but did you know there is also a ualarm(3) interface? I certainly didn't... :-) > Luckily it's basically the same interface as alarm(3). So, I have > taken the rewritten manpage from alarm.3 and transposed it into > ualarm.3. The only details that change are the units (microseconds > instead of seconds) and the additional input, "interval", which I have > noted in the DESCRIPTION. Uh, oh, to my naive ears (naive with respect to matters of time-related functions), this sounds like a typical case where we likely want one manual page documenting both alarm(3) and ualarm(3), not two pages. Basically, the rule of thumb is: if two functions have a very similar purpose, share most of their properties (including important parts of the syntax and/or semantics of their arguments, return values, behaviour, error handling or implementation, such that describing them separately results in considerable duplication of text, and if describing them together is beneficial for the user in so far as it makes it easier to highlight the (few) differences, then describe them together (unless that grows the number of functions sharing the same manual page too much, but 2 is certainly not too much). > All the changes over there apply here re describing what the interface > actually does. It basically does the same thing so I see no reason > not to reuse what I wrote for that page. Do you see any reason to not put all the information into the alarm(3) manual page? Should i give merging the two a try, or do you want to? > Given that alarm(3), ualarm(3), and setitimer(2) all poke at the same > underlying per-process timer I think it makes sense to mention all > three interfaces in the CAVEATS section of both alarm.3 and ualarm.3. > (A getitimer.2 cleanup is coming, don't fret.) Can the current wording below CAVEATS, "confusing behavior", be made more precise, explaining what actually happens rather than merely calling it "confusing"? For example, saying that they all override each other or something like that? Or saying that behavior is undefined when more than one of them is used (isn't that what POSIX says)? > The only thing I'm unsure about is how to talk about the input limits. > useconds_t is uint32_t on all platforms. Is there a more graceful way > to tell people the limit than the literal number as we do now? Maybe > UINT32_MAX? POSIX defines the type but does not define a USECONDS_MAX > constant. I'm confused. It seems i fail to find useconds_t in POSIX. I only see suseconds_t there, in <sys/types.h>, which must be signed, include [-1, 1000000], and not be wider than long. Also, our manual says ualarm(3) is -xpg4.2. That's basically -susv1, isn't it? So i would expect ualarm(3) to appear in modern POSIX, too. Was it deleted at some point? I think it would be ideal for the manual page text to state which values can be used in a *portable* way. If, for some reason, that is not desirable, then the main text should say which values can be used on OpenBSD, and STANDARDS should say that using values above XYZ is an extension. Yours, Ingo
