Linux程序员手册 第3部分
更新日期： 2019-03-06

名称

asctime，ctime，gmtime，localtime，mktime，asctime_r，ctime_r，gmtime_r，localtime_r-将日期和时间转换为细分时间或ASCII

语法

#include <time.h>

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);

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);

time_t mktime(struct tm *tm);

glibc的功能测试宏要求(请参阅feature_test_macros(7))：

asctime_r()，ctime_r()，gmtime_r()，localtime_r()：

_POSIX_C_SOURCE || / * Glibc版本

说明

ctime()，gmtime()和localtime()函数均采用数据类型time_t的参数，该参数表示日历时间。当解释为绝对时间值时，它表示自1970年1月1日00:00:00 +0000(UTC)纪元以来经过的秒数。

asctime()和mktime()函数均采用表示细分时间的参数，该细分时间分为年，月，日等。

故障时间存储在结构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 */
};

tm结构的成员是：

tm_sec

分钟后的秒数，通常为0到59，但最多可以为60，以允许leap秒。

tm_min

小时后的分钟数，范围为0到59。

tm_hour

午夜之后的小时数，范围为0到23。

tm_mday

每月的某天，范围为1到31。

tm_mon

自一月以来的月数，范围为0到11。

tm_year

自1900年以来的年数。

tm_wday

从星期日开始的天数，范围为0到6。

tm_yday

自1月1日以来的天数，范围为0到365。

tm_isdst

一个标志，指示夏时制是否在所述时间生效。如果夏令时有效，则该值为正；如果不设置夏令时，则为零；如果该信息不可用，则该值为负。

调用ctime(t)等效于asctime(localtime(t))。它将日历时间t转换为以下形式的以空值终止的字符串

"Wed Jun 30 21:49:08 1993\n"

星期几的缩写是" Sun"，" Mon"，" Tue"，" Wed"，" Thu"，" Fri"和" Sat"。月份的缩写是" Jan"，" Feb"，" Mar"，" Apr"，" May"，" Jun"，" Jul"，" Aug"，" Sep"，" Oct"，" Nov"，和" Dec"。返回值指向静态分配的字符串，该字符串可能会被后续对任何日期和时间函数的调用所覆盖。该函数还使用有关当前时区的信息来设置外部变量tzname，时区和日光(请参阅tzset(3))。可重入版本ctime_r()进行相同的操作，但是将字符串存储在用户提供的缓冲区中，该缓冲区应至少有26个字节的空间。它不需要设置tzname，时区和日光。

gmtime()函数将日历时间timep转换为细分时间表示，以协调世界时(UTC)表示。当年份不适合整数时，它可能返回NULL。返回值指向静态分配的结构，该结构可能会被随后对任何日期和时间函数的调用所覆盖。 gmtime_r()函数执行相同的操作，但是将数据存储在用户提供的结构中。

localtime()函数将日历时间timep转换为细分的时间表示形式，相对于用户指定的时区表示。该函数就好像调用了tzset(3)一样，将外部变量tzname设置为具有有关当前时区的信息，时区的时差为协调世界时(UTC)和本地标准时间(以秒为单位)，如果日光为日光，则日光为非零值节省时间规则在一年中的某些时候适用。返回值指向静态分配的结构，该结构可能会被随后对任何日期和时间函数的调用所覆盖。 localtime_r()函数执行相同的操作，但是将数据存储在用户提供的结构中。它不需要设置tzname，时区和日光。

asctime()函数将分解的时间值tm转换为与ctime()格式相同的以空值结尾的字符串。返回值指向静态分配的字符串，该字符串可能会被后续对任何日期和时间函数的调用所覆盖。 asctime_r()函数的功能相同，但是将字符串存储在用户提供的缓冲区中，该缓冲区应至少有26个字节的空间。

mktime()函数将分解的时间结构(以本地时间表示)转换为日历时间表示。该函数将忽略调用方在tm_wday和tm_yday字段中提供的值。在tm_isdst字段中指定的值通知mktime()在tm结构中提供的时间中夏令时(DST)是否有效：正值表示DST有效；零表示DST无效；负值表示mktime()应该(使用时区信息和系统数据库)尝试确定DST在指定时间是否有效。

mktime()函数修改tm结构的字段，如下所示：tm_wday和tm_yday设置为从其他字段的内容确定的值；如果结构成员超出其有效间隔，则将其标准化(例如，将10月40日更改为11月9日)；将tm_isdst设置为(无论其初始值如何)为正值或设置为0，以指示DST在指定时间是否有效。调用mktime()还会设置外部变量tzname以及有关当前时区的信息。

如果指定的细分时间不能表示为日历时间(自大纪元以来的秒数)，则mktime()返回(time_t)-1，并且不会更改细分时间结构的成员。

返回值

成功时，gmtime()和localtime()返回指向struct tm的指针。

成功时，gmtime_r()和localtime_r()返回结果指向的结构的地址。

成功时，asctime()和ctime()返回指向字符串的指针。

成功时，asctime_r()和ctime_r()返回指向buf指向的字符串的指针。

成功时，mktime()返回日历时间(自纪元以来的秒数)，表示为time_t类型的值。

错误时，mktime()返回值(time_t)-1。其余函数在出错时返回NULL。发生错误时，将设置errno以指示错误原因。

错误说明

EOVERFLOW

结果无法表示。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

POSIX.1-2001。 C89和C99指定asctime()，ctime()，gmtime()，localtime()和mktime()。 POSIX.1-2008将asctime()，asctime_r()，ctime()和ctime_r()标记为过时，建议改为使用strftime(3)。

备注

四个函数asctime()，ctime()，gmtime()和localtime()返回指向静态数据的指针，因此不是线程安全的。线程安全版本asctime_r()，ctime_r()，gmtime_r()和localtime_r()由SUSv2指定。

POSIX.1-2001说：" asctime()，ctime()，gmtime()和localtime()函数应在两个静态对象之一中返回值：细分时间结构和char类型的数组。执行这些功能中的任何一个都可能会被其他任何功能覆盖在这些对象中的任何一个中返回的信息。"这可以在glibc实现中发生。

在包括glibc在内的许多实现中，tm_mday中的0被解释为表示上个月的最后一天。

struct tm的glibc版本具有其他字段

const char *tm_zone;      /* Timezone abbreviation */

在包含之前设置_BSD_SOURCE时定义。这是BSD扩展，存在于4.3BSD-Reno中。

根据POSIX.1-2001，要求localtime()的行为就像调用tzset(3)一样，而localtime_r()没有此要求。对于可移植代码，应在localtime_r()之前调用tzset(3)。

另外参见

date(1)，gettimeofday(2)，time(2)，utime(2)，clock(3)，difftime(3)，strftime(3)，strptime(3)，timegm(3)，tzset(3)，时间(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。