Commit 94d0fb3c53faa567f20a20eae12bac7cfdfa2639

Guillem Jover 2024-03-08T03:05:24

man: Do not install timeval(3bsd) nor timespec(3bsd) These are system types, which we should not be documenting. Rewrite the man pages around the TIMEVAL_TO_TIMESPEC and TIMESPEC_TO_TIMEVAL macros.

diff --git a/man/Makefile.am b/man/Makefile.am
index 27aae67..12539ba 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -174,13 +174,11 @@ dist_man_MANS = \
 	timercmp.3bsd \
 	timerisset.3bsd \
 	timersub.3bsd \
-	timespec.3bsd \
 	timespecadd.3bsd \
 	timespecclear.3bsd \
 	timespeccmp.3bsd \
 	timespecisset.3bsd \
 	timespecsub.3bsd \
-	timeval.3bsd \
 	tree.3bsd \
 	# EOL
 
diff --git a/man/TIMESPEC_TO_TIMEVAL.3bsd b/man/TIMESPEC_TO_TIMEVAL.3bsd
index e47176e..28ebcf4 100644
--- a/man/TIMESPEC_TO_TIMEVAL.3bsd
+++ b/man/TIMESPEC_TO_TIMEVAL.3bsd
@@ -1 +1,100 @@
-.so man3/timeval.3bsd
+.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jukka Ruohonen.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 12, 2011
+.Dt TIMEVAL_TO_TIMESPEC 3bsd
+.Os
+.Sh NAME
+.Nm TIMEVAL_TO_TIMESPEC ,
+.Nm TIMESPEC_TO_TIMEVAL
+.Nd time structures conversion macros
+.Sh LIBRARY
+.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
+.ds doc-str-Lb-libbsd \*[str-Lb-libbsd]
+.Lb libbsd
+.Sh SYNOPSIS
+.In sys/time.h
+(See
+.Xr libbsd 7
+for include usage.)
+.Ft void
+.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts"
+.Ft void
+.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts"
+.Sh DESCRIPTION
+The
+.Va timeval
+structure represents elapsed time, in whole seconds,
+and the rest of the elapsed time in microseconds.
+.Pp
+The
+.Va timespec
+structure represents elapsed time, in whole seconds,
+and the rest of the elapsed time in nanoseconds.
+.Pp
+A microsecond is equal to one millionth of a second,
+1000 nanoseconds, or 1/1000 milliseconds.
+To ease the conversions, the macros
+.Fn TIMEVAL_TO_TIMESPEC
+and
+.Fn TIMESPEC_TO_TIMEVAL
+can be used to convert between
+.Em struct timeval
+and
+.Em struct timespec .
+.Sh EXAMPLES
+It can be stressed that the traditional
+.Tn UNIX
+.Va timeval
+and
+.Va timespec
+structures represent elapsed time, measured by the system clock.
+The following sketch implements a function suitable
+for use in a context where the
+.Va timespec
+structure is required for a conditional timeout:
+.Bd -literal -offset indent
+static void
+example(struct timespec *spec, time_t minutes)
+{
+	struct timeval elapsed;
+
+	(void)gettimeofday(&elapsed, NULL);
+
+	TIMEVAL_TO_TIMESPEC(&elapsed, spec);
+
+	/* Add the offset for timeout in minutes. */
+	spec->tv_sec = spec->tv_sec + minutes * 60;
+}
+.Ed
+.Pp
+A better alternative would use the more precise
+.Xr clock_gettime 2 .
+.Sh SEE ALSO
+.Xr timeradd 3bsd
diff --git a/man/TIMEVAL_TO_TIMESPEC.3bsd b/man/TIMEVAL_TO_TIMESPEC.3bsd
index e47176e..7741548 100644
--- a/man/TIMEVAL_TO_TIMESPEC.3bsd
+++ b/man/TIMEVAL_TO_TIMESPEC.3bsd
@@ -1 +1 @@
-.so man3/timeval.3bsd
+.so man3/TIMESPEC_TO_TIMEVAL.3bsd
diff --git a/man/timespec.3bsd b/man/timespec.3bsd
deleted file mode 100644
index e47176e..0000000
--- a/man/timespec.3bsd
+++ /dev/null
@@ -1 +0,0 @@
-.so man3/timeval.3bsd
diff --git a/man/timeval.3bsd b/man/timeval.3bsd
deleted file mode 100644
index 59613e1..0000000
--- a/man/timeval.3bsd
+++ /dev/null
@@ -1,134 +0,0 @@
-.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $
-.\"
-.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
-.\" All rights reserved.
-.\"
-.\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Jukka Ruohonen.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
-.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
-.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-.\" POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd April 12, 2011
-.Dt timeval 3bsd
-.Os
-.Sh NAME
-.Nm timeval ,
-.Nm timespec
-.Nd time structures
-.Sh LIBRARY
-.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
-.ds doc-str-Lb-libbsd \*[str-Lb-libbsd]
-.Lb libbsd
-.Sh SYNOPSIS
-.In sys/time.h
-(See
-.Xr libbsd 7
-for include usage.)
-.Ft void
-.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts"
-.Ft void
-.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts"
-.Sh DESCRIPTION
-The
-.In sys/time.h
-header, included by
-.In time.h ,
-defines various structures related to time and timers.
-.Bl -enum -offset 1n
-.It
-The following structure is used by
-.Xr gettimeofday 2 ,
-among others:
-.Bd -literal -offset indent
-struct timeval {
-	time_t		tv_sec;
-	suseconds_t	tv_usec;
-};
-.Ed
-.Pp
-The
-.Va tv_sec
-member represents the elapsed time, in whole seconds.
-The
-.Va tv_usec
-member captures rest of the elapsed time,
-represented as the number of microseconds.
-.It
-The following structure is used by
-.Xr nanosleep 2 ,
-among others:
-.Bd -literal -offset indent
-struct timespec {
-	time_t		tv_sec;
-	long		tv_nsec;
-};
-.Ed
-.Pp
-The
-.Va tv_sec
-member is again the elapsed time in whole seconds.
-The
-.Va tv_nsec
-member represents the rest of the elapsed time in nanoseconds.
-.Pp
-A microsecond is equal to one millionth of a second,
-1000 nanoseconds, or 1/1000 milliseconds.
-To ease the conversions, the macros
-.Fn TIMEVAL_TO_TIMESPEC
-and
-.Fn TIMESPEC_TO_TIMEVAL
-can be used to convert between
-.Em struct timeval
-and
-.Em struct timespec .
-.El
-.Sh EXAMPLES
-It can be stressed that the traditional
-.Tn UNIX
-.Va timeval
-and
-.Va timespec
-structures represent elapsed time, measured by the system clock.
-The following sketch implements a function suitable
-for use in a context where the
-.Va timespec
-structure is required for a conditional timeout:
-.Bd -literal -offset indent
-static void
-example(struct timespec *spec, time_t minutes)
-{
-	struct timeval elapsed;
-
-	(void)gettimeofday(&elapsed, NULL);
-
-	_DIAGASSERT(spec != NULL);
-	TIMEVAL_TO_TIMESPEC(&elapsed, spec);
-
-	/* Add the offset for timeout in minutes. */
-	spec->tv_sec = spec->tv_sec + minutes * 60;
-}
-.Ed
-.Pp
-A better alternative would use the more precise
-.Xr clock_gettime 2 .
-.Sh SEE ALSO
-.Xr timeradd 3bsd