From 2e74cb648ecc27f48ed5c4e161884ed978b55b3d Mon Sep 17 00:00:00 2001 From: cheloha Date: Mon, 6 Dec 2021 02:48:55 +0000 Subject: [PATCH] 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@ --- lib/libc/sys/gettimeofday.2 | 155 +++++++++++++++++++++--------------- 1 file changed, 93 insertions(+), 62 deletions(-) diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 index d12078671bc..33e6d27547d 100644 --- 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 -- 2.20.1