On Fri, 30 Jul 2021 13:01:21 -0500, Scott Cheloha wrote: > NAME > > - get "the" time of day.
I don't like having "the" in there. I'd suggest leaving this as it is or simply shortening to either "get time" or "get the time". > SYNOPSIS > > - Not a fan of the "tloc" variable name. Use "now" as we do in other > pages to reinforce the meaning of its contents. Sure. > DESCRIPTION > > - Clean this up. In particular, format the Epoch date like we do in > other pages. We don't need two paragraphs, either. > > - Mention that we call gettimeofday(2). Not strictly necessary, but > useful for people tracing system calls to know what the library > is doing. This seems like the kind of implementation detail that shouldn't be in the man page. For instance, there's no reason why time(3) couldn't be implemented via clock_gettime(2). If someone is really curious the source is available. > Part of me wants to tell the reader not to use time() to measure > elapsed time. Then again, time() is low-res so it isn't misused > nearly as often as gettimeofday(2). Yeah, I wouldn't worry about it. > I'm also leaning toward omitting the full description of the UTC clock > and its behavior. Not completely sure. I think it is fine to have that info present. > RETURN VALUES > > - There are no relevant error cases, remove them. > > The underlying system call, gettimeofday(2), will not fail in this > context unless the stack is corrupted, which we cannot account for > anyway. > > - Just say that time() always succeeds. Right, looks good. > I cribbed this bit from another page to put something in the Return > Values section, but the return value is already described in the > Description. > > Maybe we don't need this section at all anymore? I think it is useful to have the section. I know I search by the section to find this information. > STANDARDS > > - This section is missing. Our time() conforms to the latest > standard. Great. > HISTORY > > - Rework this a bit. > > - Note the fate of the historical time() system call. Fine. - todd
