Linux -- asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r函数

翻译自Ubuntu 19版本下的Linux Programmer's Manual

1. 函数名：asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - 转换日期和时间成分解时间（修正时间）或者ASCII格式的字符串。

2. 概要：

      #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 versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
   

3. 描述：
     ctime()、gmtime()和localtime()函数都接受数据类型time_t的参数，该参数表示日历时间(时间戳)。当解释为绝对的时间值时，它表示从纪元(1970-01-01 00:00:00 +0000 (UTC)开始经过的秒数。
     asctime()和mktime()函数都接受一个表示分解时间的参数，该参数是一个以年、月、日等格式分隔的表示的tm结构。
     分解时间存储在tm结构体中，tm在time.h头文件中定义如下:

   	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, Sunday = 0) */
            int tm_yday;   /* 一年中的一天 (0-365, 1 Jan = 0) */
            int tm_isdst;  /* 夏令时 */
        };
   

   tm结构的成员包括:
     tm_sec：一分钟后的秒数，通常在0到59之间，但可以到60，允许闰秒。
     tm_min：一小时后的分钟数，在0到59之间。
     tm_hour：半夜过后的小时数，在0到23之间。
     tm_mday:一个月中的一天，在1到31之间。
     tm_mon:从1月份以来的月数，在0到11之间。
     tm_year:从1900年以来的年数。
     tm_isdst：在所述时间内，指示夏令时是否有效的标志。如果夏令时有效，则该值为正;如果不有效，则为零;如果信息不可用，则为负。
     调用ctime(t)等价于asctime(localtime(t))。它将日历时间t转换为以\0结尾的字符串形式“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、timezone和timezone(参见tzset(3))，其中包含关于当前时区的信息。可重入版本ctime_r()执行相同的操作，但将字符串存储在用户提供的缓冲区中，该缓冲区应该至少有26个字节的空间。它不需要设置tzname、timezone和daylight。
     gmtime()函数的作用是:将日历时间timep转换为分解时间表示，用世界标准时间(UTC)表示。当年份不符合整数时，它可能返回NULL。返回值指向一个静态分配的结构，该结构可能会被接下来的任何日期和时间函数调用覆盖(也就是说这些函数共用一块tm结构体的内存，前面函数返回的值，可能会被后面调用的时间函数覆盖掉)。函数gmtime_r()执行相同的操作，但将数据存储在用户提供的结构中。
     localtime()函数的作用是:将日历时间timep转换为相对于用户指定时区(比如东八区（UTC/GMT+08:00）)表示的分解时间。这个函数的行为好像是它调用了tzset(3)并设置包含当前时区信息的外部变量tzname，将timezone设为世界标准时间(UTC)和本地标准时间的差值(以秒为单位)，如果日光节约时间规则适用于一年中的某些时间，则daylight为非零值。返回值指向一个静态分配的结构，该结构可能会被接下来的任何日期和时间函数调用覆盖。函数localtime_r()执行相同的操作，但将数据存储在用户提供的结构中。它不需要设置tzname、timezone和daylight。
     asctime()函数的作用是:将分解时间值tm转换为以\0结尾的字符串，格式与ctime()相同。返回值指向一个静态分配的字符串，该字符串可能被接下来任何日期和时间函数调用覆盖。函数asctime_r()执行相同的操作，但将字符串存储在一个用户支持的缓冲区中，该缓冲区应该至少有26个字节的空间。
     mktime()函数的作用是:将分解时间的结构体(表示为本地时间)转换为日历时间表示。该函数忽略调用者在tm_wday和tm_yday字段中提供的值。tm_isdst字段中指定的值通知mktime()，对于tm结构中提供的时间，夏令时(DST)是否有效:正值表示DST有效;零表示DST无效;负值意味着mktime()应该(使用时区信息和系统数据库)尝试确定DST是否在指定的时间有效。
     mktime()函数的作用是:将tm_wday和tm_yday设置为从其他字段的内容中确定的值;如果结构成员超出其有效间隔，则对其进行规范化(例如，将10月40日更改为11月9日);将tm_isdst(无论其初始值如何)设置为正值或0，以指示DST在指定的时间是否有效。调用mktime()还将使用有关当前时区的信息设置外部变量tzname。
     如果指定的分解时间不能表示为日历时间(纪元之后的秒)，则mktime()返回(time_t) -1，并且不更改分解时间结构的成员。
   

4. 返回值：
     成功时，gmtime()和localtime()返回指向struct tm的指针。
     成功时，gmtime_r()和localtime_r()返回result指向的结构的地址。
     成功时，asctime()和ctime()返回一个指向字符串的指针。
     成功时，asctime_r()和ctime_r()返回一个指向字符串指针和指向buf的指针。
     成功时，mktime()返回日历时间(纪元之后的秒)，表示为time_t类型的值。
     在出现错误时，mktime()返回值(time_t)-1。其余函数在出现错误时返回NULL。在出现错误时，将errno设置为指示错误的原因。

5. ERRORS：
     EOVERFLOW：结果无法表示。

6. 扩展：
   time - 获取时间，以秒为单位

   #include <time.h>
   
   	time_t time(time_t *tloc);
   

7. 描述：
      返回从纪元(1970-01-01 00:00:00 +0000 (UTC)开始的秒数。
   如果tloc不是NULL，返回值也存储在tloc指向的内存中。
   返回值：
     在成功时，返回纪元后以秒为单位的时间值。
     在出现错误时，返回((time_t) -1)，并适当地设置errno。

8. 补充：

   #define time_t  long int 
   

   本地时间=UTC时间+8
   为了避免值被覆盖，可以使用函数asctime_r, ctime_r, gmtime_r, localtime_r，把获取到的时间值保存到用户的buf中。

9. 例子：

   #include <stdio.h>
   #include <time.h>
   #include <stdlib.h>
   
   int main(void)
   {
   	time_t timestamp;
   	char *tm_str=NULL;
   	if((time_t)-1==(timestamp=time(NULL)))
   	{
   		perror("time");
   		exit(EXIT_FAILURE);
   	}
   	if(NULL==(tm_str=ctime(&timestamp)))
   	{
   		perror("ctime");
   		exit(EXIT_FAILURE);
   	}
   	fprintf(stderr,"%s", tm_str);
   	exit(EXIT_SUCCESS);
   }
   

   #include <stdio.h>
   #include <time.h>
   #include <stdlib.h>
   
   int main(void)
   {
   	time_t timestamp;
   	struct tm *UTC_tm=NULL;
   	extern long timezone;
   	if((time_t)-1==(timestamp=time(NULL)))
   	{
   		perror("time");
   		exit(EXIT_FAILURE);
   	}
   	if(NULL==(UTC_tm=gmtime(&timestamp)))
   	{
   		perror("gmtime");
   		exit(EXIT_FAILURE);
   	}
         
   	fprintf(stderr,"UTC time:%d:%d:%d\n", UTC_tm->tm_hour,UTC_tm->tm_min,UTC_tm->tm_sec);
   
   	printf("timezone:%lds\n",timezone);
   	
   	exit(EXIT_SUCCESS);
   }