[src/trunk]: src/lib/libc/time Document the fact that ctime_rz, localtime_rz, ...

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

details:   https://anonhg.NetBSD.org/src/rev/a0d7d2f0de79
branches:  trunk
changeset: 784131:a0d7d2f0de79
user:      apb <apb%NetBSD.org@localhost>
date:      Sat Jan 19 11:56:17 2013 +0000

description:
Document the fact that ctime_rz, localtime_rz, and mktime_z,
accept a NULL timezone_t pointer as a reference to UTC,
and the fact that tzalloc accepts a NULL zone name.

diffstat:

 lib/libc/time/ctime.3 |  34 +++++++++++++++++++++++++++++-----
 1 files changed, 29 insertions(+), 5 deletions(-)

diffs (79 lines):

diff -r 17d7923ccead -r a0d7d2f0de79 lib/libc/time/ctime.3
--- a/lib/libc/time/ctime.3     Sat Jan 19 10:22:25 2013 +0000
+++ b/lib/libc/time/ctime.3     Sat Jan 19 11:56:17 2013 +0000
@@ -1,8 +1,8 @@
-.\" $NetBSD: ctime.3,v 1.46 2011/11/02 23:06:08 christos Exp $
+.\" $NetBSD: ctime.3,v 1.47 2013/01/19 11:56:17 apb Exp $
 .\"
 .\" XXX: License missing?
 .\"
-.Dd November 2, 2011
+.Dd January 19, 2013
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -125,7 +125,10 @@
 but it also takes a
 .Ft "const timezone_t"
 argument, as returned by a previous call to
-.Fn tzalloc .
+.Fn tzalloc ,
+or a null pointer denoting
+Coordinated Universal Time
+.Pq Tn UTC .
 .It Fn difftime "time1" "time2"
 The
 .Fn difftime
@@ -189,7 +192,10 @@
 but it also takes a
 .Ft "const timezone_t"
 argument, returned by a previous call to
-.Fn tzalloc .
+.Fn tzalloc ,
+or a null pointer denoting
+Coordinated Universal Time
+.Pq Tn UTC .
 .It Fn mktime "tm"
 The
 .Fn mktime
@@ -266,7 +272,10 @@
 but it also takes a
 .Ft "const timezone_t"
 argument, returned by a previous call to
-.Fn tzalloc .
+.Fn tzalloc ,
+or a null pointer denoting
+Coordinated Universal Time
+.Pq Tn UTC .
 .It Fn tzalloc "zone"
 The
 .Fn tzalloc
@@ -279,6 +288,12 @@
 .Fn mktime_z
 functions.
 .Pp
+A null pointer may be passed to
+.Fn tzalloc
+instead of a timezone name, to refer to
+Coordinated Universal Time
+.Pq Tn UTC .
+.Pp
 Note that instead of setting the environment variable
 .Va TZ ,
 and globally changing the behavior of the calling program, one can use
@@ -376,6 +391,15 @@
 on failure, setting
 .Va errno
 to indicate the error.
+It may also return
+.Dv NULL
+when the
+.Fa name
+argument is
+.Dv NULL ,
+and this is not an error, but a way of referring to
+Coordinated Universal Time
+.Pq Tn UTC .
 .It
 .Fn tzgetzone
 function returns string containing the name of the timezone given in