[src/trunk]: src/share/man/man3 Add an introductory example.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/07c24dfa2b97
branches:  trunk
changeset: 754967:07c24dfa2b97
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue May 18 07:04:27 2010 +0000

description:
Add an introductory example.

diffstat:

 share/man/man3/timeval.3 |  33 +++++++++++++++++++++++++++++++--
 1 files changed, 31 insertions(+), 2 deletions(-)

diffs (53 lines):

diff -r bdf8d61e5598 -r 07c24dfa2b97 share/man/man3/timeval.3
--- a/share/man/man3/timeval.3  Tue May 18 06:31:17 2010 +0000
+++ b/share/man/man3/timeval.3  Tue May 18 07:04:27 2010 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: timeval.3,v 1.6 2010/05/18 05:57:07 jruoho Exp $
+.\" $NetBSD: timeval.3,v 1.7 2010/05/18 07:04:27 jruoho Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -81,7 +81,7 @@
 .Pp
 The
 .Va tv_sec
-member is again the number of elapsed time in whole seconds.
+member is again the elapsed time in whole seconds.
 The
 .Va tv_nsec
 member represents the rest of the elapsed time in nanoseconds.
@@ -152,5 +152,34 @@
 It is further described in
 .Xr timecounter 9 .
 .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
+(see
+.Xr hz 9 ) .
+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;
+
+       _DIAGASSERT(spec != NULL);
+
+       (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
 .Sh SEE ALSO
 .Xr timeradd 3