gettimeofday.2: miscellaneous manpage cleanup

Highlights:

- Tweak the one-liner description.
- Better variable names.
- Reorder DESCRIPTION to reflect the importance of each interface.
- Advise against using gettimeofday(2) for measuring elapsed time.
- Isolate discussion of the historical timezone parameter to its
  own paragraph at the end of the DESCRIPTION.
- Update ERRORS.  Mention the securelevel(7) EPERM for settimeofday(2).
- Expand SEE ALSO.
- Note settimeofday(2) in STANDARDS.  It is available on many systems.

Discussed with jmc@, millert@, and deraadt@.  Possibly discussed with
schwarze@, though I can't find the email.

Thread: https://marc.info/?t=162765632800002&r=1&w=2

"reads fine to me" jmc@, ok millert@

diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2
index d120786..33e6d27 100644 (file)
--- a/lib/libc/sys/gettimeofday.2
+++ b/lib/libc/sys/gettimeofday.2
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: gettimeofday.2,v 1.31 2019/09/04 14:27:55 cheloha Exp $
+.\"    $OpenBSD: gettimeofday.2,v 1.32 2021/12/06 02:48:55 cheloha Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,103 +29,127 @@
 .\"
 .\"     @(#)gettimeofday.2     8.2 (Berkeley) 5/26/95
 .\"
-.Dd $Mdocdate: September 4 2019 $
+.Dd $Mdocdate: December 6 2021 $
 .Dt GETTIMEOFDAY 2
 .Os
 .Sh NAME
 .Nm gettimeofday ,
 .Nm settimeofday
-.Nd get/set date and time
+.Nd get or set the time of day
 .Sh SYNOPSIS
 .In sys/time.h
 .Ft int
-.Fn gettimeofday "struct timeval *tp" "struct timezone *tzp"
+.Fn gettimeofday "struct timeval *now" "struct timezone *tz"
 .Ft int
-.Fn settimeofday "const struct timeval *tp" "const struct timezone *tzp"
+.Fn settimeofday "const struct timeval *now" "const struct timezone *tz"
 .Sh DESCRIPTION
-The system's notion of the current Greenwich time is obtained with the
+The
+.Fn gettimeofday
+function writes the absolute value of the system's Coordinated Universal Time
+.Pq UTC
+clock to
+.Fa now
+unless
+.Fa now
+is
+.Dv NULL .
+.Pp
+The UTC clock's absolute value is the time elapsed since
+Jan 1 1970 00:00:00 +0000
+.Pq the Epoch .
+The clock normally advances continuously,
+though it may jump discontinuously if a process calls
+.Fn settimeofday
+or
+.Xr clock_settime 2 .
+For this reason,
 .Fn gettimeofday
-call and set with the
+is not generally suitable for measuring elapsed time.
+Whenever possible,
+use
+.Xr clock_gettime 2
+to measure elapsed time with one of the system's monotonic clocks instead.
+.Pp
+The
 .Fn settimeofday
-call.
-The time is expressed in seconds and microseconds
-since midnight (0 hour), January 1, 1970.
-The resolution of the system clock is hardware dependent, and the time
-may be updated continuously or in
-.Dq ticks .
-If
-.Fa tp
+function sets the system's UTC clock to the absolute value
+.Fa now
+unless
+.Fa now
 is
-.Dv NULL ,
-the time will not be returned or set.
+.Dv NULL .
+Only the superuser may set the clock.
+If the system
+.Xr securelevel 7
+is 2 or greater the clock may only be advanced.
+This limitation prevents a malicious superuser
+from setting arbitrary timestamps on files.
+Setting the clock cancels any ongoing
+.Xr adjtime 2
+adjustment.
+.Pp
 The structure pointed to by
-.Fa tp
+.Fa now
 is defined in
 .In sys/time.h
 as:
 .Bd -literal
 struct timeval {
-       time_t          tv_sec;         /* seconds since Jan. 1, 1970 */
+       time_t          tv_sec;         /* seconds */
        suseconds_t     tv_usec;        /* and microseconds */
 };
 .Ed
 .Pp
 The
-.Fa tzp
-parameter is historical and timezone information is no longer
-tracked by the system.
-All code should pass
-.Dv NULL
-for
-.Fa tzp .
-For
-.Fn gettimeofday ,
-if
-.Fa tzp
-is
-.Pf non- Dv NULL
-an empty
-.Dv timezone
-structure will be returned.
-For
-.Fn settimeofday ,
-if
-.Fa tzp
-is
-.Pf non- Dv NULL
-its contents are ignored.
-.Pp
-Only the superuser may set the time of day.
-If the system securelevel is greater than 1 (see
-.Xr init 8 ) ,
-the time may only be advanced.
-This limitation is imposed to prevent a malicious superuser
-from setting arbitrary time stamps on files.
-The system time can still be adjusted backwards using the
-.Xr adjtime 2
-system call even when the system is secure.
+.Fa tz
+argument is historical:
+the system no longer maintains timezone information in the kernel.
+The
+.Fa tz
+argument should always be
+.Dv NULL .
+.Fn gettimeofday
+zeroes
+.Fa tz
+if it is not
+.Dv NULL .
+.Fn settimeofday
+ignores the contents of
+.Fa tz
+if it is not
+.Dv NULL .
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS
 .Fn gettimeofday
 and
 .Fn settimeofday
-will succeed unless:
+will fail if:
 .Bl -tag -width Er
 .It Bq Er EFAULT
-An argument address referenced invalid memory.
+.Fa now
+or
+.Fa tz
+are not
+.Dv NULL
+and reference invalid memory.
 .El
 .Pp
-In addition,
 .Fn settimeofday
-may return the following errors:
+will also fail if:
 .Bl -tag -width Er
 .It Bq Er EINVAL
-.Fa tp
-specified a microsecond value less than zero or greater than or equal to
-1 million.
+.Fa now
+specifies a microsecond value less than zero or greater than or equal to
+one million.
+.It Bq Er EPERM
+The caller is not the superuser.
 .It Bq Er EPERM
-A user other than the superuser attempted to set the time.
+The system
+.Xr securelevel 7
+is 2 or greater and
+.Fa now
+specifies a time in the past.
 .El
 .Sh SEE ALSO
 .Xr date 1 ,
@@ -133,14 +157,21 @@ A user other than the superuser attempted to set the time.
 .Xr clock_gettime 2 ,
 .Xr getitimer 2 ,
 .Xr ctime 3 ,
-.Xr time 3
+.Xr time 3 ,
+.Xr timeradd 3
 .Sh STANDARDS
 The
 .Fn gettimeofday
 function conforms to
 .St -p1003.1-2008 .
+.Pp
+The
+.Fn settimeofday
+function is non-standard,
+though many systems offer it.
 .Sh HISTORY
-As predecessors of these functions, former system calls
+As predecessors of these functions,
+former system calls
 .Fn time
 and
 .Fn stime