2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" References consulted:
|
|
|
|
.\" Linux libc source code
|
|
|
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
|
|
|
.\" 386BSD man pages
|
|
|
|
.\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
|
|
|
|
.\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
|
|
|
|
.\" Modified 2001-11-13, aeb
|
|
|
|
.\" Modified 2001-12-13, joey, aeb
|
2004-11-16 13:35:20 +00:00
|
|
|
.\" Modified 2004-11-16, mtk
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2004-11-16 13:35:20 +00:00
|
|
|
.TH CTIME 3 2004-11-16 "" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
|
|
|
|
localtime_r \- transform date and time to broken-down time or ASCII
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <time.h>
|
|
|
|
.sp
|
|
|
|
.BI "char *asctime(const struct tm *" tm );
|
|
|
|
.br
|
|
|
|
.BI "char *asctime_r(const struct tm *" tm ", char *" buf );
|
|
|
|
.sp
|
|
|
|
.BI "char *ctime(const time_t *" timep );
|
|
|
|
.br
|
|
|
|
.BI "char *ctime_r(const time_t *" timep ", char *" buf );
|
|
|
|
.sp
|
|
|
|
.BI "struct tm *gmtime(const time_t *" timep );
|
|
|
|
.br
|
|
|
|
.BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
|
|
|
|
.sp
|
|
|
|
.BI "struct tm *localtime(const time_t *" timep );
|
|
|
|
.br
|
|
|
|
.BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
|
|
|
|
.sp
|
|
|
|
.BI "time_t mktime(struct tm *" tm );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBctime\fP(), \fBgmtime\fP() and \fBlocaltime\fP() functions all take
|
2004-11-03 13:51:07 +00:00
|
|
|
an argument of data type \fItime_t\fP which represents calendar time.
|
|
|
|
When interpreted as an absolute time value, it represents the number of
|
|
|
|
seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
|
|
|
|
Time (UTC).
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBasctime\fP() and \fBmktime\fP() functions both take an argument
|
2004-11-03 13:51:07 +00:00
|
|
|
representing broken-down time which is a representation
|
|
|
|
separated into year, month, day, etc.
|
|
|
|
.PP
|
|
|
|
Broken-down time is stored
|
|
|
|
in the structure \fItm\fP which is defined in \fI<time.h>\fP as follows:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
struct tm {
|
2006-04-26 05:49:24 +00:00
|
|
|
int tm_sec; /* seconds */
|
|
|
|
int tm_min; /* minutes */
|
|
|
|
int tm_hour; /* hours */
|
|
|
|
int tm_mday; /* day of the month */
|
|
|
|
int tm_mon; /* month */
|
|
|
|
int tm_year; /* year */
|
|
|
|
int tm_wday; /* day of the week */
|
|
|
|
int tm_yday; /* day in the year */
|
|
|
|
int tm_isdst; /* daylight saving time */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
The members of the \fItm\fP structure are:
|
|
|
|
.TP
|
|
|
|
.I tm_sec
|
|
|
|
The number of seconds after the minute, normally in the range 0 to 59,
|
2006-04-26 05:49:35 +00:00
|
|
|
but can be up to 60 to allow for leap seconds.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.I tm_min
|
|
|
|
The number of minutes after the hour, in the range 0 to 59.
|
|
|
|
.TP
|
|
|
|
.I tm_hour
|
|
|
|
The number of hours past midnight, in the range 0 to 23.
|
|
|
|
.TP
|
|
|
|
.I tm_mday
|
|
|
|
The day of the month, in the range 1 to 31.
|
|
|
|
.TP
|
|
|
|
.I tm_mon
|
|
|
|
The number of months since January, in the range 0 to 11.
|
|
|
|
.TP
|
|
|
|
.I tm_year
|
|
|
|
The number of years since 1900.
|
|
|
|
.TP
|
|
|
|
.I tm_wday
|
|
|
|
The number of days since Sunday, in the range 0 to 6.
|
|
|
|
.TP
|
|
|
|
.I tm_yday
|
|
|
|
The number of days since January 1, in the range 0 to 365.
|
|
|
|
.TP
|
|
|
|
.I tm_isdst
|
|
|
|
A flag that indicates whether daylight saving time is in effect at the
|
|
|
|
time described. The value is positive if daylight saving time is in
|
|
|
|
effect, zero if it is not, and negative if the information is not
|
|
|
|
available.
|
|
|
|
.PP
|
|
|
|
The call
|
|
|
|
.BI ctime( t )
|
|
|
|
is equivalent to
|
|
|
|
.BI asctime(localtime( t )) \fR.
|
|
|
|
It converts the calendar time \fIt\fP into a string of the form
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
"Wed Jun 30 21:49:08 1993\\n"
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed',
|
|
|
|
`Thu', `Fri', and `Sat'. The abbreviations for the months are `Jan',
|
|
|
|
`Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and
|
|
|
|
`Dec'. The return value points to a statically allocated string which
|
|
|
|
might be overwritten by subsequent calls to any of the date and time
|
|
|
|
functions. The function also sets the external variable \fItzname\fP (see
|
|
|
|
.BR tzset (3))
|
|
|
|
with information about the current time zone.
|
2005-10-19 07:07:02 +00:00
|
|
|
The re-entrant version \fBctime_r\fP() does the same, but stores the
|
2004-11-03 13:51:07 +00:00
|
|
|
string in a user-supplied buffer of length at least 26. It need not
|
|
|
|
set \fItzname\fP.
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBgmtime\fP() function converts the calendar time \fItimep\fP to
|
2004-11-03 13:51:07 +00:00
|
|
|
broken-down time representation, expressed in Coordinated Universal Time
|
|
|
|
(UTC). It may return NULL when the year does not fit into an integer.
|
|
|
|
The return value points to a statically allocated struct which might be
|
|
|
|
overwritten by subsequent calls to any of the date and time functions.
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBgmtime_r\fP() function does the same, but stores the data in a
|
2004-11-03 13:51:07 +00:00
|
|
|
user-supplied struct.
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBlocaltime\fP() function converts the calendar time \fItimep\fP to
|
2004-11-03 13:51:07 +00:00
|
|
|
broken-time representation, expressed relative to the user's specified
|
|
|
|
time zone. The function acts as if it called
|
|
|
|
.BR tzset (3)
|
|
|
|
and sets the external variables \fItzname\fP with
|
|
|
|
information about the current time zone, \fItimezone\fP with the difference
|
|
|
|
between Coordinated Universal Time (UTC) and local standard time in
|
|
|
|
seconds, and \fIdaylight\fP to a non-zero value if daylight savings
|
|
|
|
time rules apply during some part of the year.
|
|
|
|
The return value points to a statically allocated struct which might be
|
|
|
|
overwritten by subsequent calls to any of the date and time functions.
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBlocaltime_r\fP() function does the same, but stores the data in a
|
2004-11-03 13:51:07 +00:00
|
|
|
user-supplied struct. It need not set \fItzname\fP.
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBasctime\fP() function converts the broken-down time value
|
|
|
|
\fItm\fP into a string with the same format as \fBctime\fP().
|
2004-11-03 13:51:07 +00:00
|
|
|
The return value points to a statically allocated string which might be
|
|
|
|
overwritten by subsequent calls to any of the date and time functions.
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBasctime_r\fP() function does the same, but stores the string in
|
2004-11-03 13:51:07 +00:00
|
|
|
a user-supplied buffer of length at least 26.
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBmktime\fP() function converts a broken-down time structure, expressed
|
2004-11-03 13:51:07 +00:00
|
|
|
as local time, to calendar time representation. The function ignores
|
|
|
|
the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP
|
|
|
|
and recomputes them from the other information in the broken-down time
|
|
|
|
structure.
|
|
|
|
If structure members are outside their legal interval, they will be
|
|
|
|
normalized (so that, e.g., 40 October is changed into 9 November).
|
2005-10-19 07:07:02 +00:00
|
|
|
Calling \fBmktime\fP() also sets the external variable \fItzname\fP with
|
2004-11-03 13:51:07 +00:00
|
|
|
information about the current time zone. If the specified broken-down
|
|
|
|
time cannot be represented as calendar time (seconds since the epoch),
|
2005-10-19 07:07:02 +00:00
|
|
|
\fBmktime\fP() returns a value of (time_t)(\-1) and does not alter the
|
2004-11-03 13:51:07 +00:00
|
|
|
\fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
Each of these functions returns the value described, or NULL
|
2005-10-19 07:07:02 +00:00
|
|
|
(\-1 in case of \fBmktime\fP()) in case an error was detected.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
The four functions
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR asctime (),
|
|
|
|
.BR ctime (),
|
|
|
|
.BR gmtime ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR localtime ()
|
2004-11-03 13:51:07 +00:00
|
|
|
return a pointer to static data and hence are not thread-safe.
|
|
|
|
Thread-safe versions
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR asctime_r (),
|
|
|
|
.BR ctime_r (),
|
|
|
|
.BR gmtime_r ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR localtime_r ()
|
2004-11-03 13:51:07 +00:00
|
|
|
are specified by SUSv2, and available since libc 5.2.5.
|
|
|
|
.LP
|
2004-11-16 13:35:20 +00:00
|
|
|
In many implementations, including
|
|
|
|
.IR glibc ,
|
|
|
|
a 0 in
|
|
|
|
.I tm_mday
|
|
|
|
is interpreted as meaning the last day of the preceding month.
|
|
|
|
.LP
|
2004-11-03 13:51:07 +00:00
|
|
|
The glibc version of struct tm has additional fields
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
long tm_gmtoff; /* Seconds east of UTC */
|
|
|
|
const char *tm_zone; /* Timezone abbreviation */
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
defined when _BSD_SOURCE was set before including
|
|
|
|
.IR <time.h> .
|
|
|
|
This is a BSD extension, present in 4.3BSD-Reno.
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:30 +00:00
|
|
|
SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR date (1),
|
|
|
|
.BR gettimeofday (2),
|
|
|
|
.BR time (2),
|
|
|
|
.BR utime (2),
|
|
|
|
.BR clock (3),
|
|
|
|
.BR difftime (3),
|
|
|
|
.BR strftime (3),
|
|
|
|
.BR strptime (3),
|
2006-04-26 07:26:36 +00:00
|
|
|
.BR tzset (3),
|
|
|
|
.BR time (7)
|