1CTIME(3) 386BSD Programmer's Manual CTIME(3) 2 3NNAAMMEE 4 aassccttiimmee, ccttiimmee, ddiiffffttiimmee, ggmmttiimmee, llooccaallttiimmee, mmkkttiimmee - transform binary 5 date and time value to ASCII 6 7SSYYNNOOPPSSIISS 8 ##iinncclluuddee <<ssyyss//ttyyppeess..hh>> 9 10 _e_x_t_e_r_n _c_h_a_r *_t_z_n_a_m_e[_2]; 11 12 _c_h_a_r * 13 ccttiimmee(_c_o_n_s_t _t_i_m_e__t *_c_l_o_c_k) 14 15 _d_o_u_b_l_e 16 ddiiffffttiimmee(_t_i_m_e__t _t_i_m_e_1, _t_i_m_e__t _t_i_m_e_0) 17 18 ##iinncclluuddee <<ttiimmee..hh>> 19 20 _c_h_a_r * 21 aassccttiimmee(_c_o_n_s_t _s_t_r_u_c_t _t_m *_t_m) 22 23 _s_t_r_u_c_t _t_m * 24 llooccaallttiimmee(_c_o_n_s_t _t_i_m_e__t *_c_l_o_c_k) 25 26 _s_t_r_u_c_t _t_m * 27 ggmmttiimmee(_c_o_n_s_t _t_i_m_e__t *_c_l_o_c_k) 28 29 _t_i_m_e__t 30 mmkkttiimmee(_s_t_r_u_c_t _t_m *_t_m) 31 32DDEESSCCRRIIPPTTIIOONN 33 The functions ccttiimmee(), ggmmttiimmee() and llooccaallttiimmee() all take as an argument a 34 time value representing the time in seconds since the Epoch (00:00:00 35 UTC, January 1, 1970; see time(3)). 36 37 The function llooccaallttiimmee() converts the time value pointed at by _c_l_o_c_k, and 38 returns a pointer to a ``_s_t_r_u_c_t _t_m'' (described below) which contains the 39 broken-out time information for the value after adjusting for the current 40 time zone (and any other factors such as Daylight Saving Time). Time 41 zone adjustments are performed as specified by the TZ environmental 42 variable (see tzset(3)). The function llooccaallttiimmee() uses tzset to 43 initialize time conversion information if tzset has not already been 44 called by the process. 45 46 After filling in the tm structure, llooccaallttiimmee() sets the _t_m__i_s_d_s_t'th 47 element of _t_z_n_a_m_e to a pointer to an ASCII string that's the time zone 48 abbreviation to be used with llooccaallttiimmee()'s return value. 49 50 The function ggmmttiimmee() similarly converts the time value, but without any 51 time zone adjustment, and returns a pointer to a tm structure (described 52 below). 53 54 The ccttiimmee() function adjusts the time value for the current time zone in 55 the same manner as llooccaallttiimmee(), and returns a pointer to a 26-character 56 string of the form: 57 58 Thu Nov 24 18:22:48 1986\n\0 59 60 All the fields have constant width. 61 62 The aassccttiimmee() function converts the broken down time in the structure _t_m 63 pointed at by *_t_m to the form shown in the example above. 64 65 66 The function mmkkttiimmee() converts the broken-down time, expressed as local 67 time, in the structure pointed to by tm into a time value with the same 68 encoding as that of the values returned by the time(3) function, that is, 69 seconds from the Epoch, UTC. 70 71 The original values of the _t_m__w_d_a_y and _t_m__y_d_a_y components of the 72 structure are ignored, and the original values of the other components 73 are not restricted to their normal ranges. (A positive or zero value for 74 _t_m__i_s_d_s_t causes mmkkttiimmee() to presume initially that summer time (for 75 example, Daylight Saving Time) is or is not in effect for the specified 76 time, respectively. A negative value for _t_m__i_s_d_s_t causes the mmkkttiimmee() 77 function to attempt to divine whether summer time is in effect for the 78 specified time.) 79 80 On successful completion, the values of the _t_m__w_d_a_y and _t_m__y_d_a_y 81 components of the structure are set appropriately, and the other 82 components are set to represent the specified calendar time, but with 83 their values forced to their normal ranges; the final value of _t_m__m_d_a_y is 84 not set until _t_m__m_o_n and _t_m__y_e_a_r are determined. MMkkttiimmee() returns the 85 specified calendar time; if the calendar time cannot be represented, it 86 returns -1; 87 88 The ddiiffffttiimmee() function returns the difference between two calendar 89 times, (_t_i_m_e_1 - _t_i_m_e_0), expressed in seconds. 90 91 External declarations as well as the tm structure definition are in the 92 <_t_i_m_e._h> include file. The tm structure includes at least the following 93 fields: 94 95 int tm_sec; /* seconds (0 - 60) */ 96 int tm_min; /* minutes (0 - 59) */ 97 int tm_hour; /* hours (0 - 23) */ 98 int tm_mday; /* day of month (1 - 31) */ 99 int tm_mon; /* month of year (0 - 11) */ 100 int tm_year; /* year - 1900 */ 101 int tm_wday; /* day of week (Sunday = 0) */ 102 int tm_yday; /* day of year (0 - 365) */ 103 int tm_isdst; /* is summer time in effect? */ 104 char *tm_zone; /* abbreviation of timezone name */ 105 long tm_gmtoff; /* offset from UTC in seconds */ 106 107 The field _t_m__i_s_d_s_t is non-zero if summer time is in effect. 108 109 The field _t_m__g_m_t_o_f_f is the offset (in seconds) of the time represented 110 from UTC, with positive values indicating east of the Prime Meridian. 111 112SSEEEE AALLSSOO 113 date(1), gettimeofday(2), getenv(3), time(3), tzset(3), tzfile(5) 114 115HHIISSTTOORRYY 116 This manual page is derived from the time package contributed to Berkeley 117 by Arthur Olsen and which appeared in 4.3BSD. 118 119BBUUGGSS 120 Except for ddiiffffttiimmee() and mmkkttiimmee(), these functions leaves their result 121 in an internal static object and return a pointer to that object. 122 Subsequent calls to these function will modify the same object. 123 124 The _t_m__z_o_n_e field of a returned tm structure points to a static array of 125 characters, which will also be overwritten by any subsequent calls (as 126 well as by subsequent calls to tzset(3) and tzsetwall(3)). 127 128 Use of the external variable _t_z_n_a_m_e is discouraged; the _t_m__z_o_n_e entry in 129 the tm structure is preferred. 130 131 132 Avoid using out-of-range values with mmkkttiimmee() when setting up lunch with 133 promptness sticklers in Riyadh. 134 1354.3 Berkeley Distribution April 19, 1991 3 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199