![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ctime.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to ctime.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 1: .\" Copyright (c) 1989 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" This code is derived from software contributed to Berkeley by
5: .\" Arthur Olson.
6: .\"
7: .\" Redistribution and use in source and binary forms are permitted provided
8: .\" that: (1) source distributions retain this entire copyright notice and
9: .\" comment, and (2) distributions including binaries display the following
10: .\" acknowledgement: ``This product includes software developed by the
11: .\" University of California, Berkeley and its contributors'' in the
12: .\" documentation or other materials provided with the distribution and in
13: .\" all advertising materials mentioning features or use of this software.
14: .\" Neither the name of the University nor the names of its contributors may
15: .\" be used to endorse or promote products derived from this software without
16: .\" specific prior written permission.
17: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
18: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
19: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
20: .\"
21: .\" @(#)ctime.3 6.13 (Berkeley) 6/23/90
22: .\"
23: .TH CTIME 3 "June 23, 1990"
24: .SH NAME
25: asctime, ctime, difftime, gmtime, localtime, mktime, tzset, tzsetwall \- convert date and time to ASCII
26: .SH SYNOPSIS
27: .nf
28: .B extern char *tzname[2];
29: .PP
30: .B void tzset()
31: .PP
32: .B void tzsetwall()
33: .PP
34: .B #include <sys/types.h>
35: .PP
36: .B char *ctime(clock)
37: .B time_t *clock;
38: .PP
39: .B double difftime(time1, time0)
40: .B time_t time1;
41: .B time_t time0;
42: .PP
43: .B #include <time.h>
44: .PP
45: .B char *asctime(tm)
46: .B struct tm *tm;
47: .PP
48: .B struct tm *localtime(clock)
49: .B long *clock;
50: .PP
51: .B struct tm *gmtime(clock)
52: .B long *clock;
53: .PP
54: .B time_t mktime(tm)
55: .B struct tm *tm;
56: .fi
57: .SH DESCRIPTION
58: .I Tzset
59: uses the value of the environment variable
60: .B TZ
61: to set time conversion information used by
62: .IR localtime .
63: If
64: .B TZ
65: does not appear in the environment,
66: the best available approximation to local wall clock time, as specified
67: by the
68: .IR tzfile (5)-format
69: file
70: .B localtime
71: in the system time conversion information directory, is used by
72: .IR localtime .
73: If
74: .B TZ
75: appears in the environment but its value is a null string,
76: Coordinated Universal Time (UTC) is used (without leap second
77: correction). If
78: .B TZ
79: appears in the environment and its value is not a null string:
80: .IP
81: if the value begins with a colon, it is used as a pathname of a file
82: from which to read the time conversion information;
83: .IP
84: if the value does not begin with a colon, it is first used as the
85: pathname of a file from which to read the time conversion information,
86: and, if that file cannot be read, is used directly as a specification of
87: the time conversion information.
88: .PP
89: When
90: .B TZ
91: is used as a pathname, if it begins with a slash,
92: it is used as an absolute pathname; otherwise,
93: it is used as a pathname relative to a system time conversion information
94: directory.
95: The file must be in the format specified in
96: .IR tzfile (5).
97: .PP
98: When
99: .B TZ
100: is used directly as a specification of the time conversion information,
101: it must have the following syntax (spaces inserted for clarity):
102: .IP
103: \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
104: .PP
105: Where:
106: .RS
107: .TP 15
108: .IR std " and " dst
109: Three or more bytes that are the designation for the standard
110: .RI ( std )
111: or summer
112: .RI ( dst )
113: time zone. Only
114: .I std
115: is required; if
116: .I dst
117: is missing, then summer time does not apply in this locale.
118: Upper- and lowercase letters are explicitly allowed. Any characters
119: except a leading colon
120: .RB ( : ),
121: digits, comma
122: .RB ( , ),
123: minus
124: .RB ( \(mi ),
125: plus
126: .RB ( \(pl ),
127: and ASCII NUL are allowed.
128: .TP
129: .I offset
130: Indicates the value one must add to the local time to arrive at
131: Coordinated Universal Time. The
132: .I offset
133: has the form:
134: .RS
135: .IP
136: \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
137: .RE
138: .IP
139: The minutes
140: .RI ( mm )
141: and seconds
142: .RI ( ss )
143: are optional. The hour
144: .RI ( hh )
145: is required and may be a single digit. The
146: .I offset
147: following
148: .I std
149: is required. If no
150: .I offset
151: follows
152: .IR dst ,
153: summer time is assumed to be one hour ahead of standard time. One or
154: more digits may be used; the value is always interpreted as a decimal
155: number. The hour must be between zero and 24, and the minutes (and
156: seconds) \(em if present \(em between zero and 59. If preceded by a
157: .RB `` \(mi '',
158: the time zone shall be east of the Prime Meridian; otherwise it shall be
159: west (which may be indicated by an optional preceding
160: .RB `` \(pl '').
161: .TP
162: .I rule
163: Indicates when to change to and back from summer time. The
164: .I rule
165: has the form:
166: .RS
167: .IP
168: \fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
169: .RE
170: .IP
171: where the first
172: .I date
173: describes when the change from standard to summer time occurs and the
174: second
175: .I date
176: describes when the change back happens. Each
177: .I time
178: field describes when, in current local time, the change to the other
179: time is made.
180: .IP
181: The format of
182: .I date
183: is one of the following:
184: .RS
185: .TP 10
186: .BI J n
187: The Julian day
188: .I n
189: .RI "(1\ \(<=" "\ n\ " "\(<=\ 365).
190: Leap days are not counted; that is, in all years \(em including leap
191: years \(em February 28 is day 59 and March 1 is day 60. It is
192: impossible to explicitly refer to the occasional February 29.
193: .TP
194: .I n
195: The zero-based Julian day
196: .RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
197: Leap days are counted, and it is possible to refer to February 29.
198: .TP
199: .BI M m . n . d
200: The
201: .IR d' th
202: day
203: .RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
204: of week
205: .I n
206: of month
207: .I m
208: of the year
209: .RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
210: .RI "1\ \(<=" "\ m\ " "\(<=\ 12,
211: where week 5 means ``the last
212: .I d
213: day in month
214: .IR m ''
215: which may occur in either the fourth or the fifth week). Week 1 is the
216: first week in which the
217: .IR d' th
218: day occurs. Day zero is Sunday.
219: .RE
220: .IP "" 15
221: The
222: .I time
223: has the same format as
224: .I offset
225: except that no leading sign
226: .RB (`` \(mi ''
227: or
228: .RB `` \(pl '')
229: is allowed. The default, if
230: .I time
231: is not given, is
232: .BR 02:00:00 .
233: .RE
234: .LP
235: If no
236: .I rule
237: is present in
238: .BR TZ ,
239: the rules specified
240: by the
241: .IR tzfile (5)-format
242: file
243: .B posixrules
244: in the system time conversion information directory are used, with the
245: standard and summer time offsets from UTC replaced by those specified by
246: the
247: .I offset
248: values in
249: .BR TZ .
250: .PP
251: For compatibility with System V Release 3.1, a semicolon
252: .RB ( ; )
253: may be used to separate the
254: .I rule
255: from the rest of the specification.
256: .PP
257: If the
258: .B TZ
259: environment variable does not specify a
260: .IR tzfile (5)-format
261: and cannot be interpreted as a direct specification,
262: UTC is used.
263: .PP
264: .I Tzsetwall
265: sets things up so that
266: .I localtime
267: returns the best available approximation of local wall clock time.
268: .PP
269: .I Ctime\^
270: converts a long integer, pointed to by
271: .IR clock ,
272: representing the time in seconds since
273: 00:00:00 UTC, January 1, 1970,
274: and returns a pointer to a
275: 26-character string
276: of the form
277: .br
278: .ce
279: .eo
280: Thu Nov 24 18:22:48 1986\n\0
281: .ec
282: .br
283: All the fields have constant width.
284: .PP
285: .IR Localtime\^
286: and
287: .I gmtime\^
288: return pointers to ``tm'' structures, described below.
289: .I Localtime\^
290: corrects for the time zone and any time zone adjustments
291: (such as Daylight Saving Time in the U.S.A.).
292: Before doing so,
293: .I localtime\^
294: calls
295: .I tzset\^
296: (if
297: .I tzset\^
298: has not been called in the current process).
299: After filling in the ``tm'' structure,
300: .I localtime
301: sets the
302: .BR tm_isdst 'th
303: element of
304: .B tzname
305: to a pointer to an
306: ASCII string that's the time zone abbreviation to be used with
307: .IR localtime 's
308: return value.
309: .PP
310: .I Gmtime\^
311: converts to Coordinated Universal Time.
312: .PP
313: .I Asctime\^
314: converts a time value contained in a
315: ``tm'' structure to a 26-character string,
316: as shown in the above example,
317: and returns a pointer
318: to the string.
319: .PP
320: .I Mktime\^
321: converts the broken-down time,
322: expressed as local time,
323: in the structure pointed to by
324: .I tm
325: into a calendar time value with the same encoding as that of the values
326: returned by the
327: .I time
328: function.
329: The original values of the
330: .B tm_wday
331: and
332: .B tm_yday
333: components of the structure are ignored,
334: and the original values of the other components are not restricted
335: to their normal ranges.
336: (A positive or zero value for
337: .B tm_isdst
338: causes
339: .I mktime
340: to presume initially that summer time (for example, Daylight Saving Time
341: in the U.S.A.)
342: respectively,
343: is or is not in effect for the specified time.
344: A negative value for
345: .B tm_isdst
346: causes the
347: .I mktime
348: function to attempt to divine whether summer time is in effect
349: for the specified time.)
350: On successful completion, the values of the
351: .B tm_wday
352: and
353: .B tm_yday
354: components of the structure are set appropriately,
355: and the other components are set to represent the specified calendar time,
356: but with their values forced to their normal ranges; the final value of
357: .B tm_mday
358: is not set until
359: .B tm_mon
360: and
361: .B tm_year
362: are determined.
363: .I Mktime\^
364: returns the specified calendar time;
365: If the calendar time cannot be represented,
366: it returns
367: .BR -1 .
368: .PP
369: .I Difftime\^
370: returns the difference between two calendar times,
371: .I time1
372: -
373: .IR time0,
374: expressed in seconds.
375: .PP
376: Declarations of all the functions and externals, and the ``tm'' structure,
377: are in the
378: .B <time.h>\^
379: header file.
380: The structure (of type)
381: .B struct tm
382: includes the following fields:
383: .RS
384: .PP
385: .nf
386: .ta .5i +\w'long tm_gmtoff;\0\0'u
387: int tm_sec; /\(** seconds (0 - 60) \(**/
388: int tm_min; /\(** minutes (0 - 59) \(**/
389: int tm_hour; /\(** hours (0 - 23) \(**/
390: int tm_mday; /\(** day of month (1 - 31) \(**/
391: int tm_mon; /\(** month of year (0 - 11) \(**/
392: int tm_year; /\(** year \- 1900 \(**/
393: int tm_wday; /\(** day of week (Sunday = 0) \(**/
394: int tm_yday; /\(** day of year (0 - 365) \(**/
395: int tm_isdst; /\(** is summer time in effect? \(**/
396: char \(**tm_zone; /\(** abbreviation of timezone name \(**/
397: long tm_gmtoff; /\(** offset from UTC in seconds \(**/
398: .fi
399: .RE
400: .PP
401: The
402: .I tm_zone
403: and
404: .I tm_gmtoff
405: fields exist, and are filled in, only if arrangements to do
406: so were made when the library containing these functions was
407: created.
408: There is no guarantee that these fields will continue to exist
409: in this form in future releases of this code.
410: .PP
411: .I Tm_isdst\^
412: is non-zero if summer time is in effect.
413: .PP
414: .I Tm_gmtoff
415: is the offset (in seconds) of the time represented
416: from UTC, with positive values indicating east
417: of the Prime Meridian.
418: .SH FILES
419: .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
420: /usr/share/zoneinfo time zone information directory
421: .br
422: /usr/share/zoneinfo/localtime local time zone file
423: .br
424: /usr/share/zoneinfo/posixrules used in converting POSIX-style TZ's
425: .br
426: /usr/share/zoneinfo/GMT for UTC leap seconds
427: .sp
428: If
429: .I /usr/share/zoneinfo/GMT
430: is absent,
431: UTC leap seconds are loaded from
432: .IR /usr/share/zoneinfo/posixrules .
433: .SH SEE ALSO
434: time(2), getenv(3), tzfile(5)
435: .SH NOTES
436: The return values point to static data
437: whose content is overwritten by each call.
438: The
439: .B tm_zone
440: field of a returned
441: .B "struct tm"
442: points to a static array of characters, which
443: will also be overwritten at the next call
444: (and by calls to
445: .I tzset
446: or
447: .IR tzsetwall ).
448: .PP
449: Avoid using out-of-range values with
450: .I mktime
451: when setting up lunch with promptness sticklers in Riyadh.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.