![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tm.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / odist / pax / man / man3|
Return to tm.3 CVS log | Up to [Research Unix] / researchv10no / cmd / odist / pax / man / man3 |
1.1 root 1: .de L \" literal font
2: .ft 5
3: .it 1 }N
4: .if !\\$1 \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
5: ..
6: .de LR
7: .}S 5 1 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
8: ..
9: .de RL
10: .}S 1 5 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
11: ..
12: .de EX \" start example
13: .ta 1i 2i 3i 4i 5i 6i
14: .PP
15: .RS
16: .PD 0
17: .ft 5
18: .nf
19: ..
20: .de EE \" end example
21: .fi
22: .ft
23: .PD
24: .RE
25: .PP
26: ..
27: .TH TM 3
28: .SH NAME
29: tm \- time conversion support
30: .SH SYNOPSIS
31: .L "#include <tm.h>"
32: .SH DESCRIPTION
33: The
34: .I tm
35: library supports conversion between
36: string date specifications,
37: .L time_t
38: clock values and
39: .L "struct tm"
40: values.
41: .L localtime()
42: and
43: .L gmtime()
44: (see
45: .IR ctime (3))
46: are used to determine local time zone information.
47: .PP
48: .L time_t
49: values are the number of seconds since the epoch,
50: .BR "Jan 1 00:00:00 GMT 1970" ,
51: with leap seconds omitted.
52: .PP
53: The global variable
54: .L "int tm_info.flags"
55: contains flags that allow all programs using the library
56: to be controlled in a consistent manner.
57: .L tm_info.flags
58: is initialized by the
59: .L tminit()
60: routine described below, and may be explicitly reset after
61: .L tminit()
62: is called.
63: The flags are:
64: .TP
65: .L TM_ADJUST
66: Set by
67: .L tminit()
68: if
69: .L localtime()
70: and
71: .L gmtime()
72: do not compensate for leap seconds.
73: .TP
74: .L TM_LEAP
75: .L time_t
76: values are interpreted as if they include leap seconds.
77: Set by
78: .L tminit()
79: if the
80: .L leap
81: option is set in the
82: .L TM_OPTIONS
83: environment variable.
84: .TP
85: .L TM_UTC
86: Times are relative to
87: .B UTC
88: (universal coordinated time, i.e.,
89: .BR GMT ).
90: Otherwise times are relative to the local time zone.
91: Set by
92: .L tminit()
93: if the time zone name matches one of
94: .L tm_info.format[43]
95: through
96: .L tm_info.format[46]
97: described below.
98: If the time zone name is not determined by
99: .L localtime()
100: then the environment variables
101: .L TZNAME
102: (as described in BSD 4.3) and
103: .L TZ
104: (as described in System V)
105: are checked, in order.
106: If this fails then the time zone name is constructed using
107: the local time zone offset.
108: .PP
109: The routines are:
110: .TP
111: .L "time_t tmdate(char* date, char** end, time_t* clock)"
112: Parses the date specification
113: .L date
114: using the
115: .L tm_info.format
116: string table (described below)
117: and returns the equivalent
118: .L time_t
119: value.
120: If
121: .RL non- NULL ,
122: .L end
123: is set to the position of the first unrecognized character in
124: .LR date .
125: .L clock
126: is used to provide default values for omitted components in
127: .LR date .
128: If
129: .L clock
130: is
131: .L NULL
132: then the current time is used.
133: .TP
134: .L "struct tm* tmfix(struct tm* tp)"
135: Corrects any out of bounds fields in
136: .L tp
137: and returns
138: .L tp
139: as its value.
140: The corrections start with
141: .L tp->tm_sec
142: and propagate down to
143: .LR tp->tm_year .
144: For example, if
145: .L tp->tm_sec
146: were 61 then it would change to 1 and
147: .L tp->tm_min
148: would be incremented by 1, and so on.
149: .LR tp->tm_wday ,
150: .LR tp->tm_yday
151: and
152: .L tp->tm_isdst
153: are not changed as these can be computed from the other fields.
154: .TP
155: .L "char* tmform(char* buf, char* format, time_t* clock)"
156: Formats the date pointed to by
157: .L clock
158: into the buffer
159: .L buf
160: according to the format specification
161: .LR format .
162: If
163: .L format
164: is
165: .L NULL
166: or empty then the string
167: .L tm_info.format[40]
168: is used.
169: If
170: .L clock
171: is
172: .L NULL
173: then the current time is used.
174: A pointer to the end of
175: .L buf
176: (i.e., the terminating
177: .LR "'\e0'" )
178: is returned.
179: .RS
180: .PP
181: .L format
182: is in the style of
183: .IR printf (3),
184: where
185: .BI % field
186: causes the corresponding fixed size field to be placed in
187: .LR buf ,
188: zero padded if necessary, and \e\fIc\fP and \e\fInnn\fP
189: sequences are interpreted as in the C language.
190: Otherwise invalid
191: .BI % field
192: specifications and all other characters in
193: .L format
194: are copied into
195: .L buf
196: without change.
197: String field values are taken from the
198: .L tm_info.format
199: string table.
200: The
201: .I fields
202: are:
203: .TP
204: .PD 0
205: .B %
206: .B %
207: character.
208: .TP
209: .B a
210: Abbreviated weekday name.
211: .TP
212: .B A
213: Full weekday name.
214: .TP
215: .B b
216: Abbreviated month name.
217: .TP
218: .B c
219: .IR ctime (3)
220: style date without the trailing
221: .BR newline .
222: .TP
223: .B C
224: .IR date (1)
225: style date.
226: .TP
227: .B d
228: Day of month number.
229: .TP
230: .B D
231: Date as
232: .IR mm / dd / yy .
233: .TP
234: .B e
235: Blank padded day of month number.
236: .TP
237: .B E
238: Unpadded day of month number.
239: .TP
240: .B h
241: Abbreviated month name.
242: .TP
243: .B H
244: 24-hour clock hour.
245: .TP
246: .B i
247: International
248: .IR date (1)
249: date that includes the time zone type name.
250: .TP
251: .B I
252: 12-hour clock hour.
253: .TP
254: .B j
255: 1-offset Julian date.
256: .TP
257: .B J
258: 0-offset Julian date.
259: .TP
260: .B l
261: .IR ls (1)
262: .B \-l
263: date that lists recent dates with
264: .IR hh : mm
265: and distant dates with
266: .IR yyyy .
267: .TP
268: .B m
269: Month number.
270: .TP
271: .B M
272: Minutes.
273: .TP
274: .B n
275: .B newline
276: character.
277: .TP
278: .B p
279: Meridian (e.g.,
280: .B AM
281: or
282: .BR PM ).
283: .TP
284: .B r
285: 12-hour time as
286: .IR hh : mm : ss
287: .IR meridian .
288: .TP
289: .B R
290: 24-hour time as
291: .IR hh : mm .
292: .TP
293: .B S
294: Seconds.
295: .TP
296: .B t
297: .B tab
298: character.
299: .TP
300: .B T
301: 24-hour time as
302: .IR hh : mm : ss .
303: .TP
304: .B U
305: Week number with Sunday as the first day.
306: .TP
307: .B w
308: Weekday number.
309: .TP
310: .B W
311: Week number with Monday as the first day.
312: .TP
313: .B x
314: Local date style, using
315: .LR tm_info.format[39] ,
316: that includes the month, day and year.
317: .TP
318: .B X
319: Local time style, using
320: .LR tm_info.format[38] ,
321: that includes the hours and minutes.
322: .TP
323: .B y
324: 2-digit year.
325: .TP
326: .B Y
327: 4-digit year.
328: .TP
329: .B z
330: Time zone type name.
331: .TP
332: .B Z
333: Time zone name.
334: .TP
335: .BI + flag
336: .TP
337: .BI \- flag
338: Temporarily (until
339: .L tmform()
340: returns) sets (+) or clears (\-) the
341: .L tm_info.flags
342: flags specified by
343: .IR flag :
344: .RS
345: .TP
346: .B l
347: .L TM_LEAP
348: .TP
349: .B u
350: .L TM_UTC
351: .RE
352: .TP
353: .B #
354: Number of seconds since the epoch.
355: .PD
356: .RE
357: .TP
358: .L "void tminit()"
359: Implicitly called by the other
360: .I tm
361: library routines to initialize global data, including the
362: .L tm_info.format
363: table and the
364: .L tm_info.flags
365: global flags.
366: Global data should only be modified after an explicit call to
367: .LR tminit() .
368: .TP
369: .L "time_t tmleap(time_t* clock)"
370: Returns a
371: .L time_t
372: value for the time pointed to by
373: .L clock
374: with leap seconds adjusted for external
375: routines that do not handle leap seconds.
376: If
377: .L clock
378: is
379: .L NULL
380: then the current time is used.
381: Adjustments are only done if the
382: .L TM_ADJUST
383: flag is set in
384: .LR tm_info.flags .
385: .TP
386: .L "struct tm* tmmake(time_t* clock)"
387: Returns a pointer to the
388: .L tm
389: struct corresponding to the time pointed to by
390: .LR clock .
391: If
392: .L clock
393: is
394: .L NULL
395: then the current time is used.
396: .TP
397: .L "time_t tmtime(struct tm* tp, int west)"
398: Returns the
399: .L time_t
400: value corresponding to
401: .LR tp .
402: If
403: .L west
404: is
405: .L TM_LOCALZONE
406: then
407: .L tm
408: is relative to the local time zone,
409: otherwise
410: .L west
411: is the number of minutes west of
412: .B UTC
413: with daylight savings time taken into account.
414: .LR tp->tm_wday ,
415: .LR tp->tm_yday
416: and
417: .L tp->tm_isdst
418: are ignored in the conversion.
419: .PP
420: The library routines use a table of date strings pointed to by
421: .LR "char** tm_info.format" .
422: The indices in
423: .L tm_info.format
424: are fixed by category.
425: .L tm_info.format
426: may be changed to point to other tables
427: according to local language and date conventions.
428: The contents by index (showing the USA English values) are:
429: .RS
430: .TP
431: .PD 0
432: .B 0-11
433: 3-character abbreviated month names.
434: .TP
435: .B 12-23
436: Full month names.
437: .TP
438: .B 24-30
439: 3-character abbreviated weekday names.
440: .TP
441: .B 31-37
442: Full weekday names.
443: .TP
444: .B 38
445: .L tmform()
446: local time format used by the
447: .B %X
448: field.
449: .TP
450: .B 39
451: .L tmform()
452: local date format used by the
453: .B %x
454: field.
455: .TP
456: .B 40
457: .L tmform()
458: format used if the
459: .L format
460: argument is
461: .L NULL
462: or empty.
463: .TP
464: .B 41-42
465: Meridian names: AM, PM.
466: .TP
467: .B 43-46
468: .B UTC
469: time zone names: GMT, UTC, UCT, CUT.
470: .TP
471: .B 47-50
472: Daylight savings time suffix names: DST.
473: .TP
474: .B 51-54
475: Suffixes to be ignored when matching strings in
476: .LR tmform() .
477: .TP
478: .B 55-61
479: Time part names: second, hour, minute, day, week, month, year.
480: .TP
481: .B 62-65
482: Hours of the day names: midnight, morning, noon, evening.
483: .TP
484: .B 66-68
485: Relative day names: yesterday, today, tomorrow.
486: .TP
487: .B 69-71
488: Past relative time references: last, ago, past.
489: .TP
490: .B 72-75
491: Current relative time references: this, now, current.
492: .TP
493: .B 75-77
494: Future relative time references: next, hence, coming.
495: .TP
496: .B 78-80
497: Exact relative time references: exactly.
498: .TP
499: .B 81-85
500: Noise words to be ignored: at, in, on.
501: .PD
502: .RE
503: .PP
504: Low level support functions and data are described in
505: .LR <tm.h> .
506: .SH EXAMPLES
507: .EX
508: #include <tm.h>
509: main() {
510: int i;
511: time_t t;
512: char buf[128];
513: struct {
514: char* date;
515: char* format;
516: } x[] = {
517: "now", "%i",
518: "2 months ago", "%C",
519: "this Wednesday noon", "%x %I:%M %p",
520: "last December 25", "%A",
521: 0, 0
522: };
523: for (i = 0; x[i].date; i++) {
524: t = tmdate(x[i].date, (char*)0, (time_t*)0);
525: (void)tmform(buf, x[i].format, &t);
526: puts(buf);
527: }
528: }
529: .EE
530: produces
531: .EX
532: Fri Sep 30 12:10:14 USA EDT 1988
533: Fri Jul 1 00:00:00 EDT 1988
534: 10/05/88 12:00 PM
535: Friday
536: .EE
537: .SH "SEE ALSO"
538: date(1), time(2), ctime(3)
539: .SH BUGS
540: .L "struct tm"
541: values may get clobbered by the
542: .I tm
543: library routines as the
544: .IR ctime (3)
545: routines typically return pointers to a single static
546: .L "struct tm"
547: area.
548: .L tmdate()
549: uses an internal international time zone name table that will
550: probably always be incomplete.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.