[src/trunk]: src Move some of the discussion from the messy ctime(3) to tm(3).

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

details:   https://anonhg.NetBSD.org/src/rev/27b67d503935
branches:  trunk
changeset: 764141:27b67d503935
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Apr 12 08:39:26 2011 +0000

description:
Move some of the discussion from the messy ctime(3) to tm(3).

diffstat:

 lib/libc/time/ctime.3    |  57 ++++++-----------------------------------------
 share/man/man3/timeval.3 |   5 ++-
 share/man/man3/tm.3      |  30 ++++++++++++++++++++++++-
 3 files changed, 40 insertions(+), 52 deletions(-)

diffs (153 lines):

diff -r ba7526a61abc -r 27b67d503935 lib/libc/time/ctime.3
--- a/lib/libc/time/ctime.3     Tue Apr 12 08:22:48 2011 +0000
+++ b/lib/libc/time/ctime.3     Tue Apr 12 08:39:26 2011 +0000
@@ -1,5 +1,8 @@
-.\" $NetBSD: ctime.3,v 1.38 2011/01/24 19:37:35 njoly Exp $
-.Dd December 14, 2010
+.\" $NetBSD: ctime.3,v 1.39 2011/04/12 08:39:26 jruoho Exp $
+.\"
+.\" XXX: Lincense missing?
+.\"
+.Dd April 12, 2011
 .Dt CTIME 3
 .Os
 .Sh NAME
@@ -103,7 +106,8 @@
 (such as Daylight Saving Time in the U.S.A.).
 After filling in the
 .Va tm
-structure,
+structure described in
+.Xr tm 3 ,
 .Fn localtime
 sets the
 .Fa tm_isdst Ns 'th
@@ -250,52 +254,6 @@
 .Fa tz
 argument previously returned by
 .Fa tzalloc .
-.Pp
-The structure (of type)
-.Va "struct tm"
-includes the following fields:
-.Bd -literal -offset indent
-int tm_sec;    /* seconds after the minute [0,61] */
-int tm_min;    /* minutes after the hour [0,59] */
-int tm_hour;   /* hours since midnight [0,23] */
-int tm_mday;   /* day of the month [1,31] */
-int tm_mon;    /* months since January [0,11] */
-int tm_year;   /* years since 1900 */
-int tm_wday;   /* day of week [0,6] (Sunday = 0) */
-int tm_yday;   /* day of year [0,365] (Jan 1 = 0) */
-int tm_isdst;  /* daylight savings flag */
-long tm_gmtoff;        /* offset from UTC in seconds */
-char *tm_zone; /* abbreviation of timezone name */
-.Ed
-.Pp
-The
-.Fa tm_zone
-and
-.Fa tm_gmtoff
-fields exist, and are filled in, only if arrangements to do
-so were made when the library containing these functions was
-created.
-There is no guarantee that these fields will continue to exist
-in this form in future releases of this code.
-The
-.Fa tm_zone
-field will become invalid and point to freed storage if the corresponding
-.Va "struct tm"
-was returned by
-.Fn localtime_rz
-and the
-.Ft "const timezone_t"
-.Fa tz
-argument has been freed by
-.Fn tzfree .
-.Pp
-.Fa tm_isdst
-is non-zero if summer time is in effect.
-.Pp
-.Fa tm_gmtoff
-is the offset (in seconds) of the time represented
-from UTC, with positive values indicating east
-of the Prime Meridian.
 .Sh RETURN VALUES
 On success the
 .Fn asctime
@@ -401,6 +359,7 @@
 .Xr getenv 3 ,
 .Xr strftime 3 ,
 .Xr time 3 ,
+.Xr tm 3 ,
 .Xr tzset 3 ,
 .Xr tzfile 5
 .Sh STANDARDS
diff -r ba7526a61abc -r 27b67d503935 share/man/man3/timeval.3
--- a/share/man/man3/timeval.3  Tue Apr 12 08:22:48 2011 +0000
+++ b/share/man/man3/timeval.3  Tue Apr 12 08:39:26 2011 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: timeval.3,v 1.11 2010/06/08 05:50:01 jruoho Exp $
+.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 8, 2010
+.Dd April 12, 2011
 .Dt TIMEVAL 3
 .Os
 .Sh NAME
@@ -185,4 +185,5 @@
 .Xr clock_gettime 2 .
 .Sh SEE ALSO
 .Xr timeradd 3 ,
+.Xr tm 3 ,
 .Xr bintime_add 9
diff -r ba7526a61abc -r 27b67d503935 share/man/man3/tm.3
--- a/share/man/man3/tm.3       Tue Apr 12 08:22:48 2011 +0000
+++ b/share/man/man3/tm.3       Tue Apr 12 08:39:26 2011 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: tm.3,v 1.1 2011/04/12 08:22:49 jruoho Exp $
+.\" $NetBSD: tm.3,v 1.2 2011/04/12 08:39:26 jruoho Exp $
 .\"
 .\" Copyright (c) 2011 Jukka Ruohonen <jruohonen%iki.fi@localhost>
 .\" All rights reserved.
@@ -82,6 +82,34 @@
 .Va tm_zone
 are defined in
 .St -p1003.1-2008 .
+.Ss NetBSD Extensions
+The
+.Va tm_zone
+and
+.Va tm_gmtoff
+fields exist, and are filled in by applicable library routines,
+only if arrangements to do so were made when the library containing
+these functions was created.
+There is no guarantee that these fields will continue to exist
+in this form in future releases of
+. Nx .
+.Pp
+The
+.Fa tm_gmtoff
+field denotes the offset (in seconds) of the time represented
+from UTC, with positive values indicating east
+of the Prime Meridian.
+The
+.Vt tm_zone
+field will become invalid and point to freed storage if the corresponding
+.Va "struct tm"
+was returned by
+.Xr localtime_rz 3
+and the
+.Ft "const timezone_t"
+.Fa tz
+argument has been freed by
+.Xr tzfree 3 .
 .Sh SEE ALSO
 .Xr timeval 3
 .Sh STANDARDS