scc

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

ctime.3 (2683B)

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