（ standard c libraries translation ）time家族

asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - transform date and time to broken-down time or ASCII
asctime,ctimegmtime,localtime,mktime,asctime_r,ctime_r,gmtime_r,localtime_r-把日期和时间转换成broken-down时间或者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);

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到现在所经过的秒数。

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时间的参数，具体包含了年，月，日等等。

Broken-down time is stored in the structure tm which is defined in <time.h> as follows:

           struct tm {
               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 */
           };

The members of the tm structure are:

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.
表示分之后的秒数，一般情况下是在0到59的区间，但是会从60上面跳过（应该算是一个中间状态）

tm_min    The number of minutes after the hour, in the range 0 to 59.
表示小时之后的分数，区间是0到59

tm_hour   The number of hours past midnight, in the range 0 to 23.
表示从午夜到现在经过的小时数，区间是0到23

tm_mday   The day of the month, in the range 1 to 31.
月的天数，区间是1到31

tm_mon    The number of months since January, in the range 0 to 11.
从1月份到现在的月数，区间是0到11

tm_year   The number of years since 1900.
从1900到现在的年数

tm_wday   The number of days since Sunday, in the range 0 to 6.
从周日到现在的天数，区间0到6

tm_yday   The number of days since January 1, in the range 0 to 365.
从1月1号到现在的天数，区间0到365

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.

The call ctime(t) is equivalent to asctime(localtime(t)).  It converts the calendar time t into a null-terminated string of the form
      "Wed Jun 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.
ctime(t)等价与asctime(localtime(t))，他们都把日历时间转换成一个字符串，格式是：
        "Wed Jun 30 21:49:08 1993\n"
        周的缩略语是"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", and "Sat"。月的缩略语是："Jan", "Feb", "Mar",  "Apr",  "May",  "Jun",  "Jul",  "Aug", "Sep", "Oct", "Nov", and "Dec"。返回值指向一个存有日期和时间的字符串。他们也可以获取到tzname,timezone,daylight等时区方面的信息，可重入版本ctime_r()也有类似的功能，但是把结果存储在一个用户提供的buffer里面，这个buffer至少有26个字节，不一定需要设置tzname,timezone和daylight。

       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 overwritten by subsequent calls to any of the date and time functions.  The gmtime_r() function does the same, but stores the data in a user-supplied struct.
        gmtime()函数把日历时间转换成broken-down时间，和UTC一致，如果年不是int型的话可能会返回NULL，返回值指向一个静态的结构体，可能会被后续的日期和时间调用所覆盖，gmtime_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 external 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()函数把日历时间转换成broken-down时间，传递相对与user的时区信息，函数表现的像调用tzset()和设置外部的变量tzname等时区相关的信息，不同于UTC和当前标准时间，在部分年期间，非0的daylight值保存了时间规则，返回值指向一个静态的结构体，可能会被后续的日期和时间调用所覆盖，localtime_r()函数有相同的作用，但是用用户提供的结构体来存储数据，tzname,timezone和daylight不是必需的。

       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 overwritten by subsequent calls to any of the date and time functions.  The asctime_r()  function  does the same, but stores the string in a user-supplied buffer which should have room for at least 26 bytes.
        asctime函数转换broken-down时间值tm到一个NULL结尾的字符串里面，格式跟ctime()一样，返回值指向一个静态的结构体，可能会被后续的日期和时间调用所覆盖，asctime_r()函数有相同的作用，但是用用户提供的结构体来存储数据，但是用户提供的存储结果的string buffer至少要有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()函数吧broken-down时间结构体，通过localtime拿到的，转换成日历时间，这个函数忽略日历时间的tm_wday和tm_yday，XXX
       The  mktime()  function  modifies  the fields of the tm structure as follows: tm_wday and tm_yday 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);  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 current timezone.
        XXX
       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.
        如果指定的broken-down时间不能被转换成日历时间，mktime()返回-1,并且不会改变broken-time结构体里面的值

RETURN VALUE
       Each of these functions returns the value described, or NULL (-1 in case of mktime()) in case an error was detected.
       这些函数返回描述的值，或者NULL（mktime返回-1）当检测到错误的时候。


       The four functions asctime(), ctime(), gmtime() and localtime() return a pointer to static data and hence are not  thread-safe.   Thread-safe  versions  asctime_r(), ctime_r(), gmtime_r() and localtime_r() are specified by SUSv2, and available since libc 5.2.5.
        asctime(),ctime(),gmtime()和localtime()返回一个静态数据，因此不是线程安全的，asctime_r(),ctime_r(),gmtime_r()和localtime_r()是线程安全的，在libc5.2.5之后有提供。

翻译的很烂，也没有什么实质性的指导意义，还是对time家族来一个test case吧

cheny.le@cheny-ThinkPad-T420:~/cheny/testCode$ cat time.c #include <stdio.h>#include <time.h>#include <stdlib.h>#include <string.h>#include <sys/timeb.h>#include <sys/time.h>int main(void){time_t my_time, my_time_later;struct tm *my_tm;struct timeb tb;struct tm *tmp_tm = (struct tm *)malloc(sizeof(struct tm));char *result = (char *)malloc(sizeof(char) * 50);//get time_t variabletime(&my_time);//ctime: time_t to char *memset(result, 0x00, 50);strcpy(result, ctime(&my_time));printf("ctime: %s", result);//ctime_r: time_t to char *memset(result, 0x00, 50);ctime_r(&my_time, result);printf("ctime_r: %s", result);//localtime: time_t to tmmemset(result, 0x00, 50);my_tm = localtime(&my_time);printf("tm sec: %d\n", my_tm->tm_sec);strcpy(result, asctime(my_tm));printf("asctime: %s", result);//locatime_r: time_t to tmmemset(result, 0x00, 50);localtime_r(&my_time, tmp_tm);strcpy(result, asctime(tmp_tm));printf("asctime_r: %s", result);//gmtime: time_t to tmmemset(result, 0x00, 50);my_tm = gmtime(&my_time);asctime_r(my_tm, result);printf("gmtime: %s", result);//gmtime_r: time_t to tmmemset(result, 0x00, 50);gmtime_r(&my_time, tmp_tm);asctime_r(tmp_tm, result);printf("gmtime_r: %s", result);//time use for timertime(&my_time);printf("now time: %d\n", (int)my_time);sleep(1);time(&my_time);printf("after time: %d\n", (int)my_time);//mktimelocaltime_r(&my_time, tmp_tm);my_time = mktime(tmp_tm);printf("time_t: %d\n", (int)my_time);//clock use for timerclock_t start, end;int i = 2;int j = 10000;start = clock();printf("start = %ld\n", start);while(i--) {while(j--);printf("10000 times counted\n");}end = clock();printf("end = %ld\n", end);printf("time usage: %f\n", (double)(end - start)/CLOCKS_PER_SEC);//use difftime get time usagei = 2;j = 10000;double diff_ret;time(&my_time);while (i--) {while (j--);printf("10000 times counted\n");}time(&my_time_later);diff_ret = difftime(my_time_later, my_time);printf("time usage:%f\n", diff_ret);//use ftime to get time nowftime(&tb);printf("seconds passed: %ld\n", tb.time);//gettimeofdaystruct timeval tv;struct timezone tz;gettimeofday(&tv, &tz);printf("sec: %ld\n", (long)tv.tv_sec);printf("usec: %ld\n", (long)tv.tv_usec);printf("minutewest: %d\n", tz.tz_minuteswest);printf("dsttime: %d\n", tz.tz_dsttime);free(result);free(tmp_tm);result = NULL;return 0;}

运行结果如下：

cheny.le@cheny-ThinkPad-T420:~/cheny/testCode$ ./a.out
ctime: Fri Dec 27 13:31:49 2013
ctime_r: Fri Dec 27 13:31:49 2013
tm sec: 49
asctime: Fri Dec 27 13:31:49 2013
asctime_r: Fri Dec 27 13:31:49 2013
gmtime: Fri Dec 27 05:31:49 2013
gmtime_r: Fri Dec 27 05:31:49 2013
now time: 1388122309
after time: 1388122310
time_t: 1388122310
start = 0
10000 times counted
10000 times counted
end = 9840000
time usage: 9.840000
10000 times counted
10000 times counted
time usage:10.000000
seconds passed: 1388122329
sec: 1388122329
usec: 715138
minutewest: -480
dsttime: 0

time家族的函数我们一般很少会用到，但是man上面说的又很专业，所以让小弟翻译起来颇费力气，先给出个大致的意思，具体的功能可能还是需要各位从test code里面去学习用法，test code里面有个地方需要提一下：

while (i--) {while (j--);printf("10000 times counted\n");}

之所以要写二重循环，是因为单独的一重循环会被编译器优化掉，所以得到的clock值是0，二重循环就不会有问题哈，这个大家注意一下就好。