Wed Oct 27 19:16:04 2010 UTC ()
markup improvements, document ctype_r, time_t is not a "long integer"


(christos)
diff -r1.32 -r1.33 src/lib/libc/time/ctime.3
cvs diff -r1.32 -r1.33 src/lib/libc/time/ctime.3 (expand / switch to unified diff)

--- src/lib/libc/time/ctime.3 2010/05/15 13:54:52 1.32
+++ src/lib/libc/time/ctime.3 2010/10/27 19:16:04 1.33
@@ -1,15 +1,15 @@ @@ -1,15 +1,15 @@
1.\" $NetBSD: ctime.3,v 1.32 2010/05/15 13:54:52 pgoyette Exp $ 1.\" $NetBSD: ctime.3,v 1.33 2010/10/27 19:16:04 christos Exp $
2.Dd February 2, 2010 2.Dd October 27, 2010
3.Dt CTIME 3 3.Dt CTIME 3
4.Os 4.Os
5.Sh NAME 5.Sh NAME
6.Nm asctime , 6.Nm asctime ,
7.Nm asctime_r , 7.Nm asctime_r ,
8.Nm ctime , 8.Nm ctime ,
9.Nm ctime_r , 9.Nm ctime_r ,
10.Nm difftime , 10.Nm difftime ,
11.Nm gmtime , 11.Nm gmtime ,
12.Nm gmtime_r , 12.Nm gmtime_r ,
13.Nm localtime , 13.Nm localtime ,
14.Nm localtime_r , 14.Nm localtime_r ,
15.Nm mktime 15.Nm mktime
@@ -31,42 +31,52 @@ @@ -31,42 +31,52 @@
31.Fn asctime_r "const struct tm restrict tm" "char * restrict buf" 31.Fn asctime_r "const struct tm restrict tm" "char * restrict buf"
32.Ft struct tm * 32.Ft struct tm *
33.Fn localtime "const time_t *clock" 33.Fn localtime "const time_t *clock"
34.Ft struct tm * 34.Ft struct tm *
35.Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result" 35.Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result"
36.Ft struct tm * 36.Ft struct tm *
37.Fn gmtime "const time_t *clock" 37.Fn gmtime "const time_t *clock"
38.Ft struct tm * 38.Ft struct tm *
39.Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result" 39.Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result"
40.Ft time_t 40.Ft time_t
41.Fn mktime "struct tm *tm" 41.Fn mktime "struct tm *tm"
42.Sh DESCRIPTION 42.Sh DESCRIPTION
43.Fn ctime 43.Fn ctime
44converts a long integer, pointed to by 44converts a
 45.Tp time_t ,
 46pointed to by
45.Fa clock , 47.Fa clock ,
46representing the time in seconds since 48representing the time in seconds since
4700:00:00 UTC, 1970-01-01, 4900:00:00 UTC, 1970-01-01,
48and returns a pointer to a 50and returns a pointer to a
49string of the form 51string of the form
50.D1 Thu Nov 24 18:22:48 1986\en\e0 52.D1 Thu Nov 24 18:22:48 1986\en\e0
51Years requiring fewer than four characters are padded with leading zeroes. 53Years requiring fewer than four characters are padded with leading zeroes.
52For years longer than four characters, the string is of the form 54For years longer than four characters, the string is of the form
53.D1 Thu Nov 24 18:22:48 81986\en\e0 55.D1 Thu Nov 24 18:22:48 81986\en\e0
54with five spaces before the year. 56with five spaces before the year.
55These unusual formats are designed to make it less likely that older 57These unusual formats are designed to make it less likely that older
56software that expects exactly 26 bytes of output will mistakenly output 58software that expects exactly 26 bytes of output will mistakenly output
57misleading values for out-of-range years. 59misleading values for out-of-range years.
58.Pp 60.Pp
59.Fn Localtime 61.Fn ctime_r
 62is similar to
 63.Fn ctime ,
 64except it places the result of the convertion on the
 65.Fa buf
 66argument which should be 26 or more bytes long, instead of using a global
 67static buffer.
 68.Pp
 69.Fn localtime
60and 70and
61.Fn gmtime 71.Fn gmtime
62return pointers to 72return pointers to
63.Va tm 73.Va tm
64structures, described below. 74structures, described below.
65.Fn localtime 75.Fn localtime
66corrects for the time zone and any time zone adjustments 76corrects for the time zone and any time zone adjustments
67(such as Daylight Saving Time in the U.S.A.). 77(such as Daylight Saving Time in the U.S.A.).
68After filling in the 78After filling in the
69.Va tm 79.Va tm
70structure, 80structure,
71.Fn localtime 81.Fn localtime
72sets the 82sets the
@@ -89,27 +99,28 @@ functions provide the same functionality @@ -89,27 +99,28 @@ functions provide the same functionality
89.Fn gmtime 99.Fn gmtime
90and 100and
91.Fn localtime 101.Fn localtime
92differing in that the caller must supply a buffer area 102differing in that the caller must supply a buffer area
93.Fa result 103.Fa result
94in which the result is stored; also, 104in which the result is stored; also,
95.Fn localtime_r 105.Fn localtime_r
96does not imply initialization of the local time conversion information; 106does not imply initialization of the local time conversion information;
97the application may need to do so by calling 107the application may need to do so by calling
98.Xr tzset 3 . 108.Xr tzset 3 .
99.Pp 109.Pp
100.Fn asctime 110.Fn asctime
101converts a time value contained in a 111converts a time value contained in a
102``tm'' structure to a string, 112.Dq tm
 113structure to a string,
103as shown in the above example, 114as shown in the above example,
104and returns a pointer to the string. 115and returns a pointer to the string.
105.Pp 116.Pp
106.Fn mktime 117.Fn mktime
107converts the broken-down time, 118converts the broken-down time,
108expressed as local time, 119expressed as local time,
109in the structure pointed to by 120in the structure pointed to by
110.Fa tm 121.Fa tm
111into a calendar time value with the same encoding as that of the values 122into a calendar time value with the same encoding as that of the values
112returned by the 123returned by the
113.Xr time 3 124.Xr time 3
114function. 125function.
115The original values of the 126The original values of the