Bug 46731

Summary: difftime(3) may suggest that time_t can be a non-arithmetic type
Product: Documentation Reporter: Michał Górny (mgorny)
Component: man-pagesAssignee: Michael Kerrisk (mtk.manpages)
Status: RESOLVED CODE_FIX    
Severity: normal CC: mtk.manpages
Priority: P1    
Hardware: All   
OS: Linux   
Kernel Version: Subsystem:
Regression: No Bisected commit-id:
Attachments: Patch changing the wording to the more exact problem

Description Michał Górny 2012-08-30 19:25:09 UTC 
Created attachment 78851 [details]
Patch changing the wording to the more exact problem

The difftime(3) manpage[1] states:

NOTES
       On a POSIX system, time_t is an arithmetic type, and one could just define

              #define difftime(t1,t0) (double)(t1 - t0)

       when the possible overflow in the subtraction is not a concern.  On other
       systems, the data type time_t might use some other encoding where
       subtraction doesn't work directly.

---

When I first read this, I got confused that time_t may actually be a non-arithmetic type. But the C99 standard explicitly lists (in 7.23.1):

3   The types declared are size_t (described in 7.17); clock_t and time_t which
    are arithmetic types capable of representing times

---

I think that particular paragraphs should be re-worked to explicitly state what differences can arise in time_t implementations and what is the reason that they can't be used to compute time differences. As far as I understand, the only issue is that time_t can express time in units other than seconds.

I'm attaching a patch with my wording for that.

[1]:http://man7.org/linux/man-pages/man3/difftime.3.html
Comment 1 Michael Kerrisk 2012-12-21 16:31:24 UTC 
Garrett, I've applied a different patch from what you suggest, essentially just making EACCES a synonym of EPERM.

index bb2d9a5..b1772d5 100644
--- a/man2/sysctl.2
+++ b/man2/sysctl.2
@@ -78,6 +78,7 @@ Otherwise, a value of \-1 is returned and
 is set to indicate the error.
 .SH ERRORS
 .TP
+.TP
 .B EFAULT
 The invocation asked for the previous value by setting
 .I oldval
@@ -88,7 +89,7 @@ non-NULL, but allowed zero room in
 .I name
 was not found.
 .TP
-.B EPERM
+.BR EACCES ", " EPERM
 No search permission for one of the encountered "directories",
 or no read permission where
 .I oldval
lines 1-21/21 (END)
Comment 2 Michael Kerrisk 2012-12-21 18:18:53 UTC 
Ooops -- sorry. That was pasted into the wrong bug...
Comment 3 Michael Kerrisk 2012-12-22 01:48:12 UTC 
This text:

       On other
       systems, the data type time_t might use some other encoding where
       subtraction doesn't work directly.

Seems to have come from Debian in 206. I'm not sure why I merged it back then, since it doesn't make much sense. I've deleted it now. That's quite different from your patch, but hopefully it addresses your problem.