scc

simple c99 compiler
git clone git://git.simple-cc.org/scc
Log | Files | Refs | Submodules | README | LICENSE

ctime.3 (2918B)

      1 .TH CTIME 3
      2 .SH NAME
      3 asctime, ctime, gmtime, localtime, mktime - transform date and time to
      4 broken-down time
      5 .SH SYNOPSIS
      6 #include <time.h>
      7 
      8 .nf
      9 char *asctime(const struct tm *tm);
     10 char *ctime(const time_t *timep);
     11 struct tm *gmtime(const time_t *timep);
     12 struct tm *localtime(const time_t *timep);
     13 time_t mktime(struct tm *tm);
     14 .fi
     15 .SH DESCRIPTION
     16 The
     17 .BR ctime ,
     18 .B gmtime
     19 and
     20 .B localtime
     21 functions all take an argument of data type
     22 .BR time_t ,
     23 which represents calendar time.
     24 
     25 The
     26 .B asctime
     27 and
     28 .B mktime
     29 functions both takes an argument representing broken-down time,
     30 which is a representation separated into year, month, day and so on.
     31 
     32 Broken-down time is stored in the struct tm.
     33 
     34 The call
     35 .B ctime(t)
     36 is equivalent to
     37 .BR asctime(localtime(t)) .
     38 It converts the calendar time
     39 .I t
     40 into a null-terminated string of the form:
     41 
     42 	"Wed Jun 30 21:49:08 1993\\n\\0"
     43 
     44 In C locale, the abbreviations for the days of the week are
     45 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", and "Sat";
     46 the abbreviations for the months are "Jan", "Feb", "Mar", "Apr",
     47 "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and "Dec".
     48 
     49 The
     50 .B gmtime
     51 function converts the calendar time
     52 .I timep
     53 into broken-down time representation, expressed as
     54 Coordinated Universal Time (UTC).
     55 It may return NULL if the specified time cannot be converted to UTC.
     56 
     57 The
     58 .B localtime
     59 function converts the calendar time
     60 .I timep
     61 to broken-down time representation,
     62 expressed relative to the user's specified timezone.
     63 
     64 The
     65 .B asctime
     66 function converts the broken-down time value
     67 .I tm
     68 into a null-terminated string with the same format as
     69 .B ctime
     70 function.
     71 
     72 The
     73 .B mktime
     74 function converts a broken-down time structure,
     75 expressed as local time, to calendar time representation.
     76 The function ignores
     77 the values supplied by the caller in the
     78 .B tm_wday
     79 and
     80 .B tm_yday
     81 fields and the original values of other fields
     82 are not restricted to the ranges indicated above.
     83 On successful completion, the values of
     84 .B tm_wday
     85 and
     86 .B tm_yday
     87 are set appropriately and the other components are set to represent
     88 the specified calendar time within their respective ranges.
     89 The final value of
     90 .B tm_mday
     91 is not set until
     92 .B tm_mon
     93 and
     94 .B tm_year
     95 are determined.
     96 
     97 .SH RETURN VALUE
     98 On success,
     99 .B gmtime
    100 and
    101 .B localtime
    102 functions return a pointer to a struct tm.
    103 
    104 On success,
    105 .B asctime
    106 and
    107 .B ctime
    108 functions return a pointer to a string.
    109 
    110 On success,
    111 .B mktime
    112 function returns the calendar time, expressed as a value of type
    113 .BR time_t .
    114 
    115 On error,
    116 .B mktime
    117 function returns the value
    118 .BR (time_t)-1 .
    119 The remaining functions return NULL on error.
    120 On error,
    121 .B errno
    122 is set to indicate the cause of the error.
    123 .SH STANDARDS
    124 .nf
    125 ISO/IEC 9899:1999 7.23.2.3 Paragraph 1,2,3
    126 ISO/IEC 9899:1999 7.23.3.1 Paragraph 1,2,3
    127 ISO/IEC 9899:1999 7.23.3.2 Paragraph 1,2,3
    128 ISO/IEC 9899:1999 7.23.3.3 Paragraph 1,2,3
    129 ISO/IEC 9899:1999 7.23.3.4 Paragraph 1,2,3
    130 .fi
    131 .SH SEE ALSO
    132 .BR time.h (3)