Commit | Line | Data |
---|---|---|
463d6749 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
97561530 | 5 | .\" @(#)ctime.3 6.9 (Berkeley) %G% |
463d6749 | 6 | .\" |
3f00558b | 7 | .TH CTIME 3 "" |
463d6749 KM |
8 | .UC 4 |
9 | .SH NAME | |
14f8b702 | 10 | ctime, localtime, gmtime, asctime, timezone, tzset \- convert date and time to ASCII |
463d6749 KM |
11 | .SH SYNOPSIS |
12 | .nf | |
94c2eda1 KB |
13 | .B void tzset() |
14 | .PP | |
463d6749 | 15 | .B char *ctime(clock) |
94c2eda1 | 16 | .B time_t *clock; |
463d6749 | 17 | .PP |
2ad48aae | 18 | .B #include <time.h> |
463d6749 | 19 | .PP |
94c2eda1 KB |
20 | .B char *asctime(tm) |
21 | .B struct tm *tm; | |
22 | .PP | |
463d6749 | 23 | .B struct tm *localtime(clock) |
94c2eda1 | 24 | .B time_t *clock; |
463d6749 KM |
25 | .PP |
26 | .B struct tm *gmtime(clock) | |
94c2eda1 | 27 | .B time_t *clock; |
463d6749 KM |
28 | .PP |
29 | .B char *timezone(zone, dst) | |
30 | .fi | |
94c2eda1 | 31 | .fi |
463d6749 | 32 | .SH DESCRIPTION |
14f8b702 KB |
33 | \fITzset\fP uses the value of the environment variable \fBTZ\fP to |
34 | set up the time conversion information used by \fIlocaltime\fP. | |
35 | .PP | |
36 | If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP | |
37 | file (as defined in \fItzfile.h\fP) is used by \fIlocaltime\fP. If | |
38 | this file fails for any reason, the GMT offset as provided by the | |
39 | kernel is used. In this case, DST is ignored, resulting in the time | |
40 | being incorrect by some amount if DST is currently in effect. If | |
41 | this fails for any reason, GMT is used. | |
42 | .PP | |
43 | If \fBTZ\fP appears in the environment but its value is a null string, | |
44 | Greenwich Mean Time is used; if \fBTZ\fP appears and begins with a | |
45 | slash, it is used as the absolute pathname of the \fItzfile\fP(5)-format | |
46 | file from which to read the time conversion information; if \fBTZ\fP | |
47 | appears and begins with a character other than a slash, it's used as | |
48 | a pathname relative to the system time conversion information directory, | |
1d4ed604 KB |
49 | defined as \fBTZDIR\fP in the include file \fItzfile.h\fP. If this file |
50 | fails for any reason, the GMT offset as provided by the kernel is | |
51 | used, as described above. If this fails for any reason, GMT is used. | |
14f8b702 KB |
52 | .PP |
53 | Programs that always wish to use local wall clock time should explicitly | |
54 | remove the environmental variable \fBTZ\fP with \fIunsetenv\fP(3). | |
94c2eda1 KB |
55 | .PP |
56 | \fICtime\fP converts a long integer, pointed to by \fIclock\fP, | |
97561530 | 57 | such as returned by \fItime\fP(3), into ASCII and returns a pointer |
94c2eda1 KB |
58 | to a 26-character string in the following form. All the fields |
59 | have constant width. | |
463d6749 KM |
60 | .PP |
61 | Sun Sep 16 01:03:52 1973\\n\\0 | |
62 | .PP | |
63 | .I Localtime | |
64 | and | |
65 | .I gmtime | |
66 | return pointers to structures containing | |
67 | the broken-down time. | |
68 | .I Localtime | |
69 | corrects for the time zone and possible daylight savings time; | |
70 | .I gmtime | |
71 | converts directly to GMT, which is the time UNIX uses. | |
72 | .I Asctime | |
73 | converts a broken-down time to ASCII and returns a pointer | |
74 | to a 26-character string. | |
75 | .PP | |
76 | The structure declaration from the include file is: | |
463d6749 | 77 | .PP |
8eafd288 | 78 | .RS |
463d6749 | 79 | .nf |
5f90d5f0 KM |
80 | .nr .0 .8i+\w'int tm_isdst'u |
81 | .ta .5i \n(.0u \n(.0u+\w'/* 0-000'u+1n | |
8eafd288 | 82 | struct tm { |
5f90d5f0 KM |
83 | int tm_sec; /* 0-59 seconds */ |
84 | int tm_min; /* 0-59 minutes */ | |
85 | int tm_hour; /* 0-23 hour */ | |
86 | int tm_mday; /* 1-31 day of month */ | |
87 | int tm_mon; /* 0-11 month */ | |
88 | int tm_year; /* 0- year \- 1900 */ | |
89 | int tm_wday; /* 0-6 day of week (Sunday = 0) */ | |
90 | int tm_yday; /* 0-365 day of year */ | |
91 | int tm_isdst; /* flag: daylight savings time in effect */ | |
94c2eda1 KB |
92 | char **tm_zone; /* abbreviation of timezone name */ |
93 | long tm_gmtoff; /* offset from GMT in seconds */ | |
8eafd288 | 94 | }; |
463d6749 KM |
95 | .fi |
96 | .RE | |
97 | .PP | |
94c2eda1 KB |
98 | \fITm_isdst\fP is non-zero if a time zone adjustment such as Daylight |
99 | Savings time is in effect. | |
100 | .PP | |
101 | \fITm_gmtoff\fP is the offset (in seconds) of the time represented | |
102 | from GMT, with positive values indicating East of Greenwich. | |
103 | .PP | |
14f8b702 KB |
104 | \fITimezone\fP remains for compatibility reasons only; it's impossible to |
105 | reliably map timezone's arguments (\fIzone\fP, a "minutes west of GMT" value | |
106 | and \fIdst\fP, a "daylight saving time in effect" flag) to a time zone | |
107 | abbreviation. | |
108 | .PP | |
9d9d28da KB |
109 | If the environmental string \fITZNAME\fP exists, \fItimezone\fP returns |
110 | its value, unless it consists of two comma separated strings, in which | |
111 | case the second string is returned if \fIdst\fP is non-zero, else | |
112 | the first string. If \fITZNAME\fP doesn't exist, \fIzone\fP is checked | |
113 | for equality with a built-in table of values, in which case \fItimezone\fP | |
114 | returns the time zone or daylight time zone abbreviation associated with | |
115 | that value. If the requested \fIzone\fP does not appear in the table, the | |
116 | difference from GMT is returned; e.g. in Afghanistan, | |
117 | \fItimezone(-(60*4+30), 0)\fP is appropriate because it is 4:30 ahead of | |
118 | GMT, and the string \fBGMT+4:30\fP is returned. Programs that in the | |
119 | past used the \fItimezone\fP function should return the zone name as | |
120 | set by \fIlocaltime\fP to assure correctness. | |
94c2eda1 KB |
121 | .SH FILES |
122 | .ta \w'/etc/zoneinfo/localtime\0\0'u | |
123 | /etc/zoneinfo time zone information directory | |
124 | .br | |
125 | /etc/zoneinfo/localtime local time zone file | |
126 | .SH SEE ALSO | |
14f8b702 | 127 | gettimeofday(2), getenv(3), time(3), tzfile(5), environ(7) |
94c2eda1 KB |
128 | .SH NOTE |
129 | The return values point to static data whose content is overwritten by | |
130 | each call. The \fBtm_zone\fP field of a returned \fBstruct tm\fP | |
131 | points to a static array of characters, which will also be overwritten | |
14f8b702 | 132 | at the next call (and by calls to \fItzset\fP). |