Linux time函数

CTIME（3） Linux 程序员手册 CTIME（3）
NAME
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gm-
time_r, localtime_r - transform date and time to broken-down time or
ASCII
asctime， ctime， gmtime， localtime， mktime， asctime_r， ctime_r， gm- time_r， localtime_r - 将日期和时间转换为细分时间或 ASCII

   #include <time.h>
   char *asctime(const struct tm *tm);
   char *asctime_r(const struct tm *tm, char *buf);

char *asctime（const struct tm *tm）;char *asctime_r（const struct tm *tm， char *buf）;
char *ctime(const time_t *timep);
char *ctime_r(const time_t *timep, char *buf);
char *ctime（const time_t *timep）;char *ctime_r（const time_t *timep， char *buf）;
struct tm *gmtime(const time_t *timep);
struct tm *gmtime_r(const time_t *timep, struct tm *result);
struct tm *gmtime（const time_t *timep）;struct tm *gmtime_r（const time_t *timep， struct tm *result）;
struct tm *localtime(const time_t *timep);
struct tm *localtime_r(const time_t *timep, struct tm *result);
struct tm *localtime（const time_t *timep）;struct TM *localtime_r（const time_t *timep， struct tm *result）;
time_t mktime(struct tm *tm);
time_t mktime（struct tm tm）;
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
glibc 的特征测试宏要求（见feature_test_macros（7））：
asctime_r(), ctime_r(), gmtime_r(), localtime_r():
_POSIX_C_SOURCE
|| / Glibc versions <= 2.19: / _BSD_SOURCE || _SVID_SOURCE
asctime_r（）， ctime_r（）， gmtime_r（）， localtime_r（）： _POSIX_C_SOURCE ||/ Glibc 版本 <= 2.19： / _BSD_SOURCE ||_SVID_SOURCE
DESCRIPTION
The ctime(), gmtime() and localtime() functions all take an argument of
data type time_t, 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).
ctime（）、gmtime（） 和 localtime（） 函数都采用数据类型为 time_t 的参数，该参数表示日历时间。当解释为绝对时间值时，它表示自纪元 1970-01-01 00：00：00 +0000 （UTC） 以来经过的秒数。
The asctime() and mktime() functions both take an argument representing
broken-down time, which is a representation separated into year, month,
day, and so on.
asctime（） 和 mktime（） 函数都接受一个表示细分时间的参数，该参数分为年、月、日等。
Broken-down time is stored in the structure tm, which is defined in
<time.h> as follows:
细分时间存储在结构 tm 中，该结构在 中定义如下：
struct tm {
int tm_sec; / Seconds (0-60) /
int tm_min; / Minutes (0-59) /
int tm_hour; / Hours (0-23) /
int tm_mday; / Day of the month (1-31) /
int tm_mon; / Month (0-11) /
int tm_year; / Year - 1900 /
int tm_wday; / Day of the week (0-6, Sunday = 0) /
int tm_yday; / Day in the year (0-365, 1 Jan = 0) /
int tm_isdst; / Daylight saving time /
};
struct tm { int tm_sec; / 秒 （0-60） / int tm_min; / 分钟 （0-59） / int tm_hour; / 小时 （0-23） / int tm_mday; / 月份中的某一天 （1-31） / int tm_mon; / 月份 （0-11） / int tm_year; / 年份 - 1900 / int tm_wday; / 星期几 （0-6， 星期日 = 0） / int tm_yday; / 一年中的一天 （0-365， 1 月 1 日 = 0） / int tm_isdst; / 夏令时 */ };
The members of the tm structure are:
TM 结构的成员是：
tm_sec 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.
tm_sec 分钟后的秒数，通常在 0 到 59 的范围内，但最多可以达到 60 以允许闰秒。
tm_min The number of minutes after the hour, in the range 0 to 59.
tm_min 小时后的分钟数，范围为 0 到 59。
tm_hour The number of hours past midnight, in the range 0 to 23.
tm_hour 午夜过后的小时数，范围为 0 到 23。
tm_mday The day of the month, in the range 1 to 31.
tm_mday 月份中的某一天，范围为 1 到 31。
tm_mon The number of months since January, in the range 0 to 11.
tm_mon 自 1 月以来的月数，范围为 0 到 11。
tm_year The number of years since 1900.
tm_year 自1900年以来的年数。
tm_wday The number of days since Sunday, in the range 0 to 6.
tm_wday 自星期日以来的天数，范围为 0 到 6。
tm_yday The number of days since January 1, in the range 0 to 365.
tm_yday 自 1 月 1 日以来的天数，范围为 0 到 365。
tm_isdst A flag that indicates whether daylight saving time is in ef-
fect at the time described. The value is positive if day-
light saving time is in effect, zero if it is not, and nega-
tive if the information is not available.
tm_isdst 指示夏令时在所述时间是否有效的标志。如果夏令时有效，则该值为正，如果不是，则该值为零，如果信息不可用，则该值为负。
The call ctime(t) is equivalent to asctime(localtime(t)). It converts
the calendar time t into a null-terminated string of the form
调用 ctime（t） 等价于 asctime（localtime（t））。它将日历时间 t 转换为以 null 结尾的字符串，形式为
“Wed Jun 30 21:49:08 1993\n”
“星期三 6月 30 21：49：08 1993\n”
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
tzname, timezone, and daylight (see tzset(3)) with information about
the current timezone. The reentrant version ctime_r() 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 tzname, timezone, and daylight.
一周中几天的缩写是“周日”、“周一”、“周二”、“周三”、“周四”、“周五”和“周六”。月份的缩写是“1月”、“2月”、“3月”、“4月”、“5月”、“6月”、“7月”、“8月”、“9月”、“10月”、“11月”和“12月”。返回值指向静态分配的字符串，该字符串可能会被对任何日期和时间函数的后续调用覆盖。该函数还设置外部变量 tzname、时区和日光（参见 tzset（3））以及有关当前时区的信息。可重入版本 ctime_r（） 执行相同的操作，但将字符串存储在用户提供的缓冲区中，该缓冲区应至少容纳 26 个字节。它不需要设置 tzname、时区和日光。
The gmtime() function converts the calendar time timep 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 overwrit-
ten by subsequent calls to any of the date and time functions. The gm-
time_r() function does the same, but stores the data in a user-supplied
struct.
gmtime（） 函数将日历时间 timep 转换为细分时间表示形式，以协调世界时 （UTC） 表示。当年份不适合整数时，它可能会返回 NULL。返回值指向静态分配的结构，该结构可能会被对任何日期和时间函数的后续调用所覆盖。gm- time_r（） 函数执行相同的操作，但将数据存储在用户提供的结构中。
The localtime() function converts the calendar time timep to broken-
down time representation, expressed relative to the user’s specified
timezone. The function acts as if it called tzset(3) and sets the ex-
ternal variables tzname with information about the current timezone,
timezone with the difference between Coordinated Universal Time (UTC)
and local standard time in seconds, and daylight 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 localtime_r() function does the same, but stores the data in a
user-supplied struct. It need not set tzname, timezone, and daylight.
localtime（） 函数将日历时间 timep 转换为细分时间表示形式，相对于用户指定的时区表示。该函数的行为就像它调用 tzset（3） 一样，如果夏令时规则在一年中的某些时间适用，则将外部变量 tzname 设置为有关当前时区的信息、时区（以秒为单位）协调世界时 （UTC） 与当地标准时间之间的差异以及夏令时设置为非零值。返回值指向静态分配的结构，该结构可能会被对任何日期和时间函数的后续调用覆盖。localtime_r（） 函数执行相同的操作，但将数据存储在用户提供的结构中。它不需要设置 tzname、时区和日光。
The asctime() function converts the broken-down time value tm into a
null-terminated string with the same format as ctime(). The return
value points to a statically allocated string which might be overwrit-
ten by subsequent calls to any of the date and time functions. The as-
ctime_r() function does the same, but stores the string in a user-sup-
plied buffer which should have room for at least 26 bytes.
asctime（） 函数将分解的时间值 tm 转换为与 ctime（） 格式相同的以 null 结尾的字符串。返回值指向静态分配的字符串，该字符串可能会被对任何日期和时间函数的后续调用所覆盖。as- ctime_r（） 函数执行相同的操作，但将字符串存储在用户支持的缓冲区中，该缓冲区应至少具有 26 个字节的空间。
The mktime() 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 tm_wday and tm_yday fields.
The value specified in the tm_isdst field informs mktime() whether or
not daylight saving time (DST) is in effect for the time supplied in
the tm structure: a positive value means DST is in effect; zero means
that DST is not in effect; and a negative value means that mktime()
should (use timezone information and system databases to) attempt to
determine whether DST is in effect at the specified time.
mktime（） 函数将分解的时间结构（表示为本地时间）转换为日历时间表示形式。该函数忽略调用方在tm_wday和tm_yday字段中提供的值。tm_isdst字段中指定的值通知 mktime（） 夏令时 （DST） 是否对 tm 结构中提供的时间有效：正值表示 DST 有效;零表示 DST 无效;负值表示 mktime（） 应（使用时区信息和系统数据库）尝试确定 DST 是否在指定时间生效。
The mktime() function modifies the fields of the tm structure as fol-
lows: tm_wday and tm_yday are set to values determined from the con-
tents 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); tm_isdst 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 mktime()
also sets the external variable tzname with information about the cur-
rent timezone.
mktime（） 函数将 tm 结构的字段修改为 fol- lows：tm_wday 和 tm_yday 设置为由其他字段的参数确定的值;如果结构成员超出其有效间隔，则它们将被规范化（例如，将 10 月 40 日更改为 11 月 9 日）;tm_isdst（无论其初始值如何）分别设置为正值或 0，以指示 DST 在指定时间是否有效。调用 mktime（） 还会设置外部变量 tzname，其中包含有关当前时区的信息。
If the specified broken-down time cannot be represented as calendar
time (seconds since the Epoch), mktime() returns (time_t) -1 and does
not alter the members of the broken-down time structure.
如果指定的细分时间不能表示为日历时间（自纪元以来的秒数），mktime（） 返回 （time_t） -1，并且不会更改细分时间结构的成员。
RETURN VALUE
On success, gmtime() and localtime() return a pointer to a struct tm.
返回值 成功时，gmtime（） 和 localtime（） 返回指向结构体 tm 的指针。
On success, gmtime_r() and localtime_r() return the address of the
structure pointed to by result.
成功后，gmtime_r（） 和 localtime_r（） 返回 result 指向的结构的地址。
On success, asctime() and ctime() return a pointer to a string.
成功时，asctime（） 和 ctime（） 返回指向字符串的指针。
On success, asctime_r() and ctime_r() return a pointer to the string
pointed to by buf.
成功后，asctime_r（） 和 ctime_r（） 返回指向 buf 指向的字符串的指针。
On success, mktime() returns the calendar time (seconds since the
Epoch), expressed as a value of type time_t.
成功后，mktime（） 返回日历时间（自纪元以来的秒数），表示为 time_t 类型的值。
On error, mktime() returns the value (time_t) -1. The remaining func-
tions return NULL on error. On error, errno is set to indicate the
cause of the error.
出错时，mktime（） 返回值 （time_t） -1。其余功能在出错时返回 NULL。出错时，errno 设置为指示错误的原因。
ERRORS
EOVERFLOW
The result cannot be represented.
错误溢出 无法表示结果。