618 lines
14 KiB
HTML
618 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of CTIME</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>CTIME</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
|
|
localtime_r - transform date and time to broken-down time or ASCII
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/time.h">time.h</A>></B>
|
|
|
|
<B>char *asctime(const struct tm *</B><I>tm</I><B>);</B>
|
|
<B>char *asctime_r(const struct tm *</B><I>tm</I><B>, char *</B><I>buf</I><B>);</B>
|
|
|
|
<B>char *ctime(const time_t *</B><I>timep</I><B>);</B>
|
|
<B>char *ctime_r(const time_t *</B><I>timep</I><B>, char *</B><I>buf</I><B>);</B>
|
|
|
|
<B>struct tm *gmtime(const time_t *</B><I>timep</I><B>);</B>
|
|
<B>struct tm *gmtime_r(const time_t *</B><I>timep</I><B>, struct tm *</B><I>result</I><B>);</B>
|
|
|
|
<B>struct tm *localtime(const time_t *</B><I>timep</I><B>);</B>
|
|
<B>struct tm *localtime_r(const time_t *</B><I>timep</I><B>, struct tm *</B><I>result</I><B>);</B>
|
|
|
|
<B>time_t mktime(struct tm *</B><I>tm</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<B>asctime_r</B>(),
|
|
|
|
<B>ctime_r</B>(),
|
|
|
|
<B>gmtime_r</B>(),
|
|
|
|
<B>localtime_r</B>():
|
|
|
|
<DL COMPACT><DT id="1"><DD>
|
|
_POSIX_C_SOURCE
|
|
<BR> || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
|
|
</DL>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>ctime</B>(),
|
|
|
|
<B>gmtime</B>()
|
|
|
|
and
|
|
<B>localtime</B>()
|
|
|
|
functions all take
|
|
an argument of data type <I>time_t</I>, which represents calendar time.
|
|
When interpreted as an absolute time value, it represents the number of
|
|
seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
|
|
<P>
|
|
|
|
The
|
|
<B>asctime</B>()
|
|
|
|
and
|
|
<B>mktime</B>()
|
|
|
|
functions both take an argument
|
|
representing broken-down time, which is a representation
|
|
separated into year, month, day, and so on.
|
|
<P>
|
|
|
|
Broken-down time is stored
|
|
in the structure <I>tm</I>, which is defined in <I><<A HREF="file:///usr/include/time.h">time.h</A>></I> as follows:
|
|
<P>
|
|
|
|
|
|
|
|
struct tm {
|
|
<BR> int tm_sec; /* Seconds (0-60) */
|
|
<BR> int tm_min; /* Minutes (0-59) */
|
|
<BR> int tm_hour; /* Hours (0-23) */
|
|
<BR> int tm_mday; /* Day of the month (1-31) */
|
|
<BR> int tm_mon; /* Month (0-11) */
|
|
<BR> int tm_year; /* Year - 1900 */
|
|
<BR> int tm_wday; /* Day of the week (0-6, Sunday = 0) */
|
|
<BR> int tm_yday; /* Day in the year (0-365, 1 Jan = 0) */
|
|
<BR> int tm_isdst; /* Daylight saving time */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
The members of the <I>tm</I> structure are:
|
|
<DL COMPACT>
|
|
<DT id="2"><I>tm_sec</I>
|
|
|
|
<DD>
|
|
The number of seconds after the minute, normally in the range 0 to 59,
|
|
but can be up to 60 to allow for leap seconds.
|
|
<DT id="3"><I>tm_min</I>
|
|
|
|
<DD>
|
|
The number of minutes after the hour, in the range 0 to 59.
|
|
<DT id="4"><I>tm_hour</I>
|
|
|
|
<DD>
|
|
The number of hours past midnight, in the range 0 to 23.
|
|
<DT id="5"><I>tm_mday</I>
|
|
|
|
<DD>
|
|
The day of the month, in the range 1 to 31.
|
|
<DT id="6"><I>tm_mon</I>
|
|
|
|
<DD>
|
|
The number of months since January, in the range 0 to 11.
|
|
<DT id="7"><I>tm_year</I>
|
|
|
|
<DD>
|
|
The number of years since 1900.
|
|
<DT id="8"><I>tm_wday</I>
|
|
|
|
<DD>
|
|
The number of days since Sunday, in the range 0 to 6.
|
|
<DT id="9"><I>tm_yday</I>
|
|
|
|
<DD>
|
|
The number of days since January 1, in the range 0 to 365.
|
|
<DT id="10"><I>tm_isdst</I>
|
|
|
|
<DD>
|
|
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.
|
|
</DL>
|
|
<P>
|
|
|
|
The call
|
|
<B>ctime(</B><I>t</I><B>)</B>
|
|
|
|
is equivalent to
|
|
<B>asctime(localtime(</B><I>t</I><B>))</B><I></I>.
|
|
|
|
It converts the calendar time <I>t</I> into a
|
|
null-terminated string of the form
|
|
<P>
|
|
|
|
|
|
|
|
"Wed Jun 30 21:49:08 1993\n"
|
|
|
|
|
|
<P>
|
|
|
|
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
|
|
variables <I>tzname</I>, <I>timezone</I>, and <I>daylight</I> (see
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tzset">tzset</A></B>(3))
|
|
|
|
with information about the current timezone.
|
|
The reentrant version
|
|
<B>ctime_r</B>()
|
|
|
|
does the same, but stores the
|
|
string in a user-supplied buffer
|
|
which should have room for at least 26 bytes.
|
|
It need not
|
|
set <I>tzname</I>, <I>timezone</I>, and <I>daylight</I>.
|
|
<P>
|
|
|
|
The
|
|
<B>gmtime</B>()
|
|
|
|
function converts the calendar time <I>timep</I> to
|
|
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.
|
|
The
|
|
<B>gmtime_r</B>()
|
|
|
|
function does the same, but stores the data in a
|
|
user-supplied struct.
|
|
<P>
|
|
|
|
The
|
|
<B>localtime</B>()
|
|
|
|
function converts the calendar time <I>timep</I> to
|
|
broken-down time representation,
|
|
expressed relative to the user's specified timezone.
|
|
The function acts as if it called
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tzset">tzset</A></B>(3)
|
|
|
|
and sets the external variables <I>tzname</I> with
|
|
information about the current timezone, <I>timezone</I> with the difference
|
|
between Coordinated Universal Time (UTC) and local standard time in
|
|
seconds, and <I>daylight</I> to a nonzero 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.
|
|
The
|
|
<B>localtime_r</B>()
|
|
|
|
function does the same, but stores the data in a
|
|
user-supplied struct.
|
|
It need not set <I>tzname</I>, <I>timezone</I>, and <I>daylight</I>.
|
|
<P>
|
|
|
|
The
|
|
<B>asctime</B>()
|
|
|
|
function converts the broken-down time value
|
|
<I>tm</I> into a null-terminated string with the same format as
|
|
<B>ctime</B>().
|
|
|
|
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
|
|
<B>asctime_r</B>()
|
|
|
|
function does the same, but stores the string in
|
|
a user-supplied buffer which should have room for at least 26 bytes.
|
|
<P>
|
|
|
|
The
|
|
<B>mktime</B>()
|
|
|
|
function converts a broken-down time structure, expressed
|
|
as local time, to calendar time representation.
|
|
The function ignores
|
|
the values supplied by the caller in the
|
|
<I>tm_wday</I>
|
|
|
|
and
|
|
<I>tm_yday</I>
|
|
|
|
fields.
|
|
The value specified in the
|
|
<I>tm_isdst</I>
|
|
|
|
field informs
|
|
<B>mktime</B>()
|
|
|
|
whether or not daylight saving time (DST)
|
|
is in effect for the time supplied in the
|
|
<I>tm</I>
|
|
|
|
structure:
|
|
a positive value means DST is in effect;
|
|
zero means that DST is not in effect;
|
|
and a negative value means that
|
|
<B>mktime</B>()
|
|
|
|
should (use timezone information and system databases to)
|
|
attempt to determine whether DST is in effect at the specified time.
|
|
<P>
|
|
|
|
The
|
|
<B>mktime</B>()
|
|
|
|
function modifies the fields of the
|
|
<I>tm</I>
|
|
|
|
structure as follows:
|
|
<I>tm_wday</I>
|
|
|
|
and
|
|
<I>tm_yday</I>
|
|
|
|
are set to values determined from the contents of the other fields;
|
|
if structure members are outside their valid interval, they will be
|
|
normalized (so that, for example, 40 October is changed into 9 November);
|
|
<I>tm_isdst</I>
|
|
|
|
is set (regardless of its initial value)
|
|
to a positive value or to 0, respectively,
|
|
to indicate whether DST is or is not in effect at the specified time.
|
|
Calling
|
|
<B>mktime</B>()
|
|
|
|
also sets the external variable <I>tzname</I> with
|
|
information about the current timezone.
|
|
<P>
|
|
|
|
If the specified broken-down
|
|
time cannot be represented as calendar time (seconds since the Epoch),
|
|
<B>mktime</B>()
|
|
|
|
returns
|
|
<I>(time_t) -1</I>
|
|
|
|
and does not alter the
|
|
members of the broken-down time structure.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success,
|
|
<B>gmtime</B>()
|
|
|
|
and
|
|
<B>localtime</B>()
|
|
|
|
return a pointer to a
|
|
<I>struct tm</I>.
|
|
|
|
<P>
|
|
|
|
On success,
|
|
<B>gmtime_r</B>()
|
|
|
|
and
|
|
<B>localtime_r</B>()
|
|
|
|
return the address of the structure pointed to by
|
|
<I>result</I>.
|
|
|
|
<P>
|
|
|
|
On success,
|
|
<B>asctime</B>()
|
|
|
|
and
|
|
<B>ctime</B>()
|
|
|
|
return a pointer to a string.
|
|
<P>
|
|
|
|
On success,
|
|
<B>asctime_r</B>()
|
|
|
|
and
|
|
<B>ctime_r</B>()
|
|
|
|
return a pointer to the string pointed to by
|
|
<I>buf</I>.
|
|
|
|
<P>
|
|
|
|
On success,
|
|
<B>mktime</B>()
|
|
|
|
returns the calendar time (seconds since the Epoch),
|
|
expressed as a value of type
|
|
<I>time_t</I>.
|
|
|
|
<P>
|
|
|
|
On error,
|
|
<B>mktime</B>()
|
|
|
|
returns the value
|
|
<I>(time_t) -1</I>.
|
|
|
|
The remaining functions return NULL on error.
|
|
On error,
|
|
<I>errno</I>
|
|
|
|
is set to indicate the cause of the error.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="11"><B>EOVERFLOW</B>
|
|
|
|
<DD>
|
|
The result cannot be represented.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>asctime</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Unsafe race:asctime locale<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>asctime_r</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe locale<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>ctime</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>
|
|
MT-Unsafe race:tmbuf
|
|
<BR>
|
|
|
|
race:asctime env locale
|
|
<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>ctime_r</B>(),
|
|
|
|
<B>gmtime_r</B>(),
|
|
|
|
<B>localtime_r</B>(),
|
|
|
|
<B>mktime</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe env locale<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>gmtime</B>(),
|
|
|
|
<B>localtime</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Unsafe race:tmbuf env locale<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001.
|
|
C89 and C99 specify
|
|
<B>asctime</B>(),
|
|
|
|
<B>ctime</B>(),
|
|
|
|
<B>gmtime</B>(),
|
|
|
|
<B>localtime</B>(),
|
|
|
|
and
|
|
<B>mktime</B>().
|
|
|
|
POSIX.1-2008 marks
|
|
<B>asctime</B>(),
|
|
|
|
<B>asctime_r</B>(),
|
|
|
|
<B>ctime</B>(),
|
|
|
|
and
|
|
<B>ctime_r</B>()
|
|
|
|
as obsolete,
|
|
recommending the use of
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strftime">strftime</A></B>(3)
|
|
|
|
instead.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The four functions
|
|
<B>asctime</B>(),
|
|
|
|
<B>ctime</B>(),
|
|
|
|
<B>gmtime</B>()
|
|
|
|
and
|
|
<B>localtime</B>()
|
|
|
|
return a pointer to static data and hence are not thread-safe.
|
|
The thread-safe versions,
|
|
<B>asctime_r</B>(),
|
|
|
|
<B>ctime_r</B>(),
|
|
|
|
<B>gmtime_r</B>()
|
|
|
|
and
|
|
<B>localtime_r</B>(),
|
|
|
|
are specified by SUSv2.
|
|
<P>
|
|
|
|
POSIX.1-2001 says:
|
|
"The
|
|
<B>asctime</B>(),
|
|
|
|
<B>ctime</B>(),
|
|
|
|
<B>gmtime</B>(),
|
|
|
|
and
|
|
<B>localtime</B>()
|
|
|
|
functions shall return values in one of two static objects:
|
|
a broken-down time structure and an array of type
|
|
<I>char</I>.
|
|
|
|
Execution of any of the functions may overwrite the information returned
|
|
in either of these objects by any of the other functions."
|
|
This can occur in the glibc implementation.
|
|
<P>
|
|
|
|
In many implementations, including glibc, a 0 in
|
|
<I>tm_mday</I>
|
|
|
|
is interpreted as meaning the last day of the preceding month.
|
|
<P>
|
|
|
|
The glibc version of <I>struct tm</I> has additional fields
|
|
<P>
|
|
|
|
|
|
|
|
const char *tm_zone; /* Timezone abbreviation */
|
|
|
|
|
|
<P>
|
|
|
|
defined when
|
|
<B>_BSD_SOURCE</B>
|
|
|
|
was set before including
|
|
<I><<A HREF="file:///usr/include/time.h">time.h</A>></I>.
|
|
|
|
This is a BSD extension, present in 4.3BSD-Reno.
|
|
<P>
|
|
|
|
According to POSIX.1-2004,
|
|
<B>localtime</B>()
|
|
|
|
is required to behave as though
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tzset">tzset</A></B>(3)
|
|
|
|
was called, while
|
|
<B>localtime_r</B>()
|
|
|
|
does not have this requirement.
|
|
|
|
For portable code,
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tzset">tzset</A></B>(3)
|
|
|
|
should be called before
|
|
<B>localtime_r</B>().
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+date">date</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+gettimeofday">gettimeofday</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+time">time</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+utime">utime</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+clock">clock</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+difftime">difftime</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strftime">strftime</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+strptime">strptime</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+timegm">timegm</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+tzset">tzset</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+time">time</A></B>(7)
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="12"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="13"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="14"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="15"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="16"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="17"><A HREF="#lbAG">ATTRIBUTES</A><DD>
|
|
<DT id="18"><A HREF="#lbAH">CONFORMING TO</A><DD>
|
|
<DT id="19"><A HREF="#lbAI">NOTES</A><DD>
|
|
<DT id="20"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="21"><A HREF="#lbAK">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:38 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|