On Wed, Jun 30, 2021 at 04:23:42PM -0600, Theo de Raadt wrote: > >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? > > Merging this sounds dangerous. > > Are people's eyes not going to glaze over the different ranges? > > I would argue also argue that the bolding on this sentence > is DANGEROUS: > > This is a simplified interface to setitimer(2). > > Oh, it is a simplified interface! And I know setitimer! I don't need > to read any further! > > And onwards they go .. coding straight into the integer truncation trap.
FWIW, the manpage has literally always led with this bolded implementation detail. From January of 1986: https://svnweb.freebsd.org/csrg/lib/libc/gen/ualarm.3?revision=25789&view=markup > >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)? > > Confusing like a bear trap. Oww, how the hell did that get around my leg. ... specifically, setitimer(2) can handle huge intervals that, when converted to a count of microseconds, will overflow ualarm's return value. So using both interfaces in the same program is error-prone. There's no good reason to do so, and we should discourage programmers from doing so unambiguously.
