[unix-history] / usr / man / man3 / ctime.3

.TH CTIME 3 
.SH NAME
ctime, localtime, gmtime, asctime, timezone \-  convert date and time to ASCII
.SH SYNOPSIS
.B char *ctime(clock)
.br
.B long *clock;
.PP
.B #include <time.h>
.PP
.B struct tm *localtime(clock)
.br
.B long *clock;
.PP
.B struct tm *gmtime(clock)
.br
.B long *clock;
.PP
.B char *asctime(tm)
.br
.B struct tm *tm;
.PP
.B char *timezone(zone, dst)
.SH DESCRIPTION
.I Ctime
converts a time pointed to by
.I clock
such as returned by
.IR time (2)
into ASCII
and returns a pointer to a
26-character string
in the following form.
All the fields have constant width.
.PP
    Sun Sep 16 01:03:52 1973\\n\\0
.PP
.I Localtime
and
.I gmtime
return pointers to structures containing
the broken-down time.
.I Localtime
corrects for the time zone and possible daylight savings time;
.I gmtime
converts directly to GMT, which is the time UNIX uses.
.I Asctime
converts a broken-down time to ASCII and returns a pointer
to a 26-character string.
.PP
The structure declaration from the include file is:
.RS
.PP
.nf
.so /usr/include/time.h
.fi
.RE
.PP
These quantities give the time on a 24-hour clock,
day of month (1-31), month of year (0-11), day of week
(Sunday = 0), year \- 1900, day of year (0-365),
and a flag that is nonzero if daylight saving time is in effect.
.PP
When local time is called for,
the program consults the system to determine the time zone and
whether the standard U.S.A. daylight saving time adjustment is
appropriate.
The program knows about the peculiarities
of this conversion in 1974 and 1975;
if necessary,
a table for these years can be extended.
.PP
.I Timezone
returns the name of the time zone associated with its first argument,
which is measured in minutes westward from Greenwich.
If the second argument is 0, the standard name is used,
otherwise the Daylight Saving version.
If the required name does not appear in a table
built into the routine,
the difference from GMT is produced; e.g.
in Afghanistan
.I timezone(-(60*4+30), 0)
is appropriate because it is 4:30 ahead of GMT
and the string
.B GMT+4:30
is produced.
.SH "SEE ALSO"
time(2)
.SH BUGS
The return values point to static data
whose content is overwritten by each call.
Commit	Line	Data
e2137ef3 TL	1	.TH CTIME 3
	2	.SH NAME
	3	ctime, localtime, gmtime, asctime, timezone \- convert date and time to ASCII
	4	.SH SYNOPSIS
	5	.B char *ctime(clock)
	6	.br
	7	.B long *clock;
	8	.PP
	9	.B #include <time.h>
	10	.PP
	11	.B struct tm *localtime(clock)
	12	.br
	13	.B long *clock;
	14	.PP
	15	.B struct tm *gmtime(clock)
	16	.br
	17	.B long *clock;
	18	.PP
	19	.B char *asctime(tm)
	20	.br
	21	.B struct tm *tm;
	22	.PP
	23	.B char *timezone(zone, dst)
	24	.SH DESCRIPTION
	25	.I Ctime
	26	converts a time pointed to by
	27	.I clock
	28	such as returned by
	29	.IR time (2)
	30	into ASCII
	31	and returns a pointer to a
	32	26-character string
	33	in the following form.
	34	All the fields have constant width.
	35	.PP
	36	Sun Sep 16 01:03:52 1973\\n\\0
	37	.PP
	38	.I Localtime
	39	and
	40	.I gmtime
	41	return pointers to structures containing
	42	the broken-down time.
	43	.I Localtime
	44	corrects for the time zone and possible daylight savings time;
	45	.I gmtime
	46	converts directly to GMT, which is the time UNIX uses.
	47	.I Asctime
	48	converts a broken-down time to ASCII and returns a pointer
	49	to a 26-character string.
	50	.PP
	51	The structure declaration from the include file is:
	52	.RS
	53	.PP
	54	.nf
	55	.so /usr/include/time.h
	56	.fi
	57	.RE
	58	.PP
	59	These quantities give the time on a 24-hour clock,
	60	day of month (1-31), month of year (0-11), day of week
	61	(Sunday = 0), year \- 1900, day of year (0-365),
	62	and a flag that is nonzero if daylight saving time is in effect.
	63	.PP
	64	When local time is called for,
65	the program consults the system to determine the time zone and
66	whether the standard U.S.A. daylight saving time adjustment is
67	appropriate.
68	The program knows about the peculiarities
69	of this conversion in 1974 and 1975;
70	if necessary,
71	a table for these years can be extended.
72	.PP
73	.I Timezone
74	returns the name of the time zone associated with its first argument,
75	which is measured in minutes westward from Greenwich.
76	If the second argument is 0, the standard name is used,
77	otherwise the Daylight Saving version.
78	If the required name does not appear in a table
79	built into the routine,
80	the difference from GMT is produced; e.g.
81	in Afghanistan
82	.I timezone(-(60*4+30), 0)
83	is appropriate because it is 4:30 ahead of GMT
84	and the string
85	.B GMT+4:30
86	is produced.
87	.SH "SEE ALSO"
88	time(2)
89	.SH BUGS
90	The return values point to static data
91	whose content is overwritten by each call.