[src/trunk]: src/lib/libc/time Add a manual page for the standard-inspired of...

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

details:   https://anonhg.NetBSD.org/src/rev/520bd2f8184f
branches:  trunk
changeset: 566464:520bd2f8184f
user:      kleink <kleink%NetBSD.org@localhost>
date:      Mon May 10 02:02:00 2004 +0000

description:
Add a manual page for the standard-inspired offtime(3) and friends;
requested by Thomas Klausner.

diffstat:

 lib/libc/time/Makefile.inc |   7 +++-
 lib/libc/time/offtime.3    |  63 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diffs (92 lines):

diff -r 276dc0fbd753 -r 520bd2f8184f lib/libc/time/Makefile.inc
--- a/lib/libc/time/Makefile.inc        Mon May 10 01:50:32 2004 +0000
+++ b/lib/libc/time/Makefile.inc        Mon May 10 02:02:00 2004 +0000
@@ -1,10 +1,10 @@
-#      $NetBSD: Makefile.inc,v 1.9 2001/03/31 19:00:56 kleink Exp $
+#      $NetBSD: Makefile.inc,v 1.10 2004/05/10 02:02:00 kleink Exp $
 
 .PATH: ${.CURDIR}/time
 
 SRCS+= _daylight.c                                                     \
        asctime.c difftime.c localtime.c strftime.c strptime.c
-MAN+=  ctime.3 time2posix.3 tzfile.5 tzset.3 strftime.3 strptime.3
+MAN+=  ctime.3 offtime.3 time2posix.3 tzfile.5 tzset.3 strftime.3 strptime.3
 CFLAGS+=-DALL_STATE -DUSG_COMPAT
 
 MLINKS+=ctime.3 ctime_r.3      \
@@ -16,5 +16,8 @@
        ctime.3 localtime.3     \
        ctime.3 localtime_r.3   \
        ctime.3 mktime.3        \
+       offtime.3 timeoff.3     \
+       offtime.3 timegm.3      \
+       offtime.3 timelocal.3   \
        tzset.3 daylight.3      \
        tzset.3 tzsetwall.3
diff -r 276dc0fbd753 -r 520bd2f8184f lib/libc/time/offtime.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/time/offtime.3   Mon May 10 02:02:00 2004 +0000
@@ -0,0 +1,63 @@
+.\"    $NetBSD: offtime.3,v 1.1 2004/05/10 02:02:00 kleink Exp $
+.\" Written by Klaus Klein, May 10, 2004.
+.\" Public domain.
+.Dd May 10, 2004
+.Dt OFFTIME 3
+.Os
+.Sh NAME
+.Nm offtime ,
+.Nm timeoff ,
+.Nm timegm ,
+.Nm timelocal
+.Nd convert date and time
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In time.h
+.Ft struct tm *
+.Fn offtime "const time_t * clock" "long int offset"
+.Ft time_t
+.Fn timeoff "struct tm * tm" "long int offset"
+.Ft time_t
+.Fn timegm "struct tm * tm"
+.Ft time_t
+.Fn timelocal "struct tm * tm"
+.Sh DESCRIPTION
+These functions are inspired by C standard interfaces named similarly.
+.Pp
+.Fn offtime
+converts the calendar time
+.Fa clock ,
+offset by
+.Fa offset
+seconds,
+into broken-down time, expressed as Coordinated Universal Time (UTC).
+.Pp
+.Fn timeoff
+converts the broken-down time
+.Fa tm ,
+expressed as UTC,
+offset by
+.Fa offset
+seconds,
+into a calendar time value.
+.Pp
+.Fn timegm
+converts the broken-down time
+.Fa tm
+into a calendar time value, effectively being the inverse of
+.Xr gmtime 3 .
+It is equivalent to the C standard function
+.Xr mktime 3
+operating in UTC.
+.Pp
+.Fn timelocal
+converts the broken down time
+.Fa tm ,
+expressed as local time, into a calendar time value.
+It is equivalent to the C standard function
+.Xr mktime 3 ,
+and is provided for symmetry only.
+.Sh SEE ALSO
+.Xr ctime 3 ,
+.Xr tzset 3