1CTIME(3)                   Library Functions Manual                   CTIME(3)
2
3
4

NAME

6       ctime,  localtime, gmtime, asctime, timezone, tzset -  convert date and
7       time to ASCII
8

SYNOPSIS

10       void tzset()
11
12       char *ctime(clock)
13       time_t *clock;
14
15       #include <time.h>
16
17       char *asctime(tm)
18       struct tm *tm;
19
20       struct tm *localtime(clock)
21       time_t *clock;
22
23       struct tm *gmtime(clock)
24       time_t *clock;
25
26       char *timezone(zone, dst)
27

DESCRIPTION

29       Tzset uses the value of the environment variable TZ to set up the  time
30       conversion information used by localtime.
31
32       If  TZ  does  not  appear  in  the  environment, the TZDEFAULT file (as
33       defined in tzfile.h) is used by localtime.  If this file fails for  any
34       reason,  the  GMT  offset  as  provided by the kernel is used.  In this
35       case, DST is ignored, resulting in the time  being  incorrect  by  some
36       amount  if  DST  is currently in effect.  If this fails for any reason,
37       GMT is used.
38
39       If TZ appears in the environment but its value is a null string, Green‐
40       wich  Mean  Time  is used; if TZ appears and begins with a slash, it is
41       used as the absolute pathname of the tzfile(5)-format file  from  which
42       to  read the time conversion information; if TZ appears and begins with
43       a character other than a slash, it's used as a pathname relative to the
44       system  time  conversion information directory, defined as TZDIR in the
45       include file tzfile.h.  If this file fails for any reason, GMT is used.
46
47       Programs that always wish to use local wall clock time  should  explic‐
48       itly remove the environmental variable TZ with unsetenv(3).
49
50       Ctime converts a long integer, pointed to by clock, such as returned by
51       time(2) into ASCII and returns a pointer to a  26-character  string  in
52       the following form.  All the fields have constant width.
53
54           Sun Sep 16 01:03:52 1973\n
55
56       Localtime  and gmtime return pointers to structures containing the bro‐
57       ken-down time.  Localtime corrects for the time zone and possible  day‐
58       light  savings time; gmtime converts directly to GMT, which is the time
59       UNIX uses.  Asctime converts a broken-down time to ASCII and returns  a
60       pointer to a 26-character string.
61
62       The structure declaration from the include file is:
63
64              struct tm {
65                   int tm_sec;    /* 0-59  seconds */
66                   int tm_min;    /* 0-59  minutes */
67                   int tm_hour;   /* 0-23  hour */
68                   int tm_mday;   /* 1-31  day of month */
69                   int tm_mon;    /* 0-11  month */
70                   int tm_year;   /* 0-    year - 1900 */
71                   int tm_wday;   /* 0-6   day of week (Sunday = 0) */
72                   int tm_yday;   /* 0-365 day of year */
73                   int tm_isdst;  /* flag: daylight savings time in effect */
74                   char **tm_zone;         /* abbreviation of timezone name */
75                   long tm_gmtoff;         /* offset from GMT in seconds */
76              };
77
78       Tm_isdst is non-zero if a time zone adjustment such as Daylight Savings
79       time is in effect.
80
81       Tm_gmtoff is the offset (in seconds) of the time represented from  GMT,
82       with positive values indicating East of Greenwich.
83
84       Timezone  remains  for  compatibility  reasons only; it's impossible to
85       reliably map timezone's arguments (zone, a "minutes west of GMT"  value
86       and dst, a "daylight saving time in effect" flag) to a time zone abbre‐
87       viation.
88
89       If the environmental string TZNAME exists, timezone returns its  value,
90       unless  it  consists  of two comma separated strings, in which case the
91       second string is returned if dst is non-zero, else  the  first  string.
92       If  TZNAME  doesn't exist, zone is checked for equality with a built-in
93       table of values, in which case timezone returns the time zone  or  day‐
94       light  time  zone  abbreviation  associated  with  that  value.  If the
95       requested zone does not appear in the table, the difference from GMT is
96       returned;  e.g.  in Afghanistan, timezone(-(60*4+30), 0) is appropriate
97       because it is 4:30 ahead of GMT, and the string GMT+4:30  is  returned.
98       Programs  that in the past used the timezone function should return the
99       zone name as set by localtime to assure correctness.
100

FILES

102       /usr/share/zoneinfotime zone information directory
103       /etc/localtime     local time zone file
104

SEE ALSO

106       gettimeofday(2), getenv(3), time(3), tzfile(5), environ(7)
107

NOTE

109       The return values point to static data whose content is overwritten  by
110       each  call.   The  tm_zone  field  of  a returned struct tm points to a
111       static array of characters, which will also be overwritten at the  next
112       call (and by calls to tzset).
113
114
115
1164th Berkeley Distribution      November 27, 1996                      CTIME(3)
Impressum