diff options
Diffstat (limited to 'newctime.3.txt')
| -rw-r--r-- | newctime.3.txt | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/newctime.3.txt b/newctime.3.txt new file mode 100644 index 000000000000..2957a6ce9355 --- /dev/null +++ b/newctime.3.txt @@ -0,0 +1,171 @@ +NEWCTIME(3) Library Functions Manual NEWCTIME(3) + +NAME + asctime, ctime, difftime, gmtime, localtime, mktime - convert date and + time + +SYNOPSIS + #include <time.h> + + extern char *tzname[]; /* (optional) */ + + char *ctime(time_t const *clock); + + char *ctime_r(time_t const *clock, char *buf); + + double difftime(time_t time1, time_t time0); + + char *asctime(struct tm const *tm); + + char *asctime_r(struct tm const *restrict tm, + char *restrict result); + + struct tm *localtime(time_t const *clock); + + struct tm *localtime_r(time_t const *restrict clock, + struct tm *restrict result); + + struct tm *localtime_rz(timezone_t restrict zone, + time_t const *restrict clock, + struct tm *restrict result); + + struct tm *gmtime(time_t const *clock); + + struct tm *gmtime_r(time_t const *restrict clock, + struct tm *restrict result); + + time_t mktime(struct tm *tm); + + time_t mktime_z(timezone_t restrict zone, + struct tm *restrict tm); + + cc ... -ltz + +DESCRIPTION + Ctime converts a long integer, pointed to by clock, and returns a + pointer to a string of the form + Thu Nov 24 18:22:48 1986\n\0 + Years requiring fewer than four characters are padded with leading + zeroes. For years longer than four characters, the string is of the + form + Thu Nov 24 18:22:48 81986\n\0 + with five spaces before the year. These unusual formats are designed + to make it less likely that older software that expects exactly 26 + bytes of output will mistakenly output misleading values for out-of- + range years. + + The *clock timestamp represents the time in seconds since 1970-01-01 + 00:00:00 Coordinated Universal Time (UTC). The POSIX standard says + that timestamps must be nonnegative and must ignore leap seconds. Many + implementations extend POSIX by allowing negative timestamps, and can + therefore represent timestamps that predate the introduction of UTC and + are some other flavor of Universal Time (UT). Some implementations + support leap seconds, in contradiction to POSIX. + + Localtime and gmtime return pointers to "tm" structures, described + below. Localtime corrects for the time zone and any time zone + adjustments (such as Daylight Saving Time in the United States). After + filling in the "tm" structure, localtime sets the tm_isdst'th element + of tzname to a pointer to a string that's the time zone abbreviation to + be used with localtime's return value. + + Gmtime converts to Coordinated Universal Time. + + Asctime converts a time value contained in a "tm" structure to a + string, as shown in the above example, and returns a pointer to the + string. + + Mktime converts the broken-down time, expressed as local time, in the + structure pointed to by tm into a calendar time value with the same + encoding as that of the values returned by the time function. The + original values of the tm_wday and tm_yday components of the structure + are ignored, and the original values of the other components are not + restricted to their normal ranges. (A positive or zero value for + tm_isdst causes mktime to presume initially that daylight saving time + respectively, is or is not in effect for the specified time. A + negative value for tm_isdst causes the mktime function to attempt to + divine whether daylight saving time is in effect for the specified + time; in this case it does not use a consistent rule and may give a + different answer when later presented with the same argument.) On + successful completion, the values of the tm_wday and tm_yday components + of the structure are set appropriately, and the other components are + set to represent the specified calendar time, but with their values + forced to their normal ranges; the final value of tm_mday is not set + until tm_mon and tm_year are determined. Mktime returns the specified + calendar time; If the calendar time cannot be represented, it returns + -1. + + Difftime returns the difference between two calendar times, (time1 - + time0), expressed in seconds. + + Ctime_r, localtime_r, gmtime_r, and asctime_r are like their unsuffixed + counterparts, except that they accept an additional argument specifying + where to store the result if successful. + + Localtime_rz and mktime_z are like their unsuffixed counterparts, + except that they accept an extra initial zone argument specifying the + time zone to be used for conversion. If zone is null, UT is used; + otherwise, zone should be have been allocated by tzalloc and should not + be freed until after all uses (e.g., by calls to strftime) of the + filled-in tm_zone fields. + + Declarations of all the functions and externals, and the "tm" + structure, are in the <time.h> header file. The structure (of type) + struct tm includes the following fields: + + int tm_sec; /* seconds (0-60) */ + int tm_min; /* minutes (0-59) */ + int tm_hour; /* hours (0-23) */ + int tm_mday; /* day of month (1-31) */ + int tm_mon; /* month of year (0-11) */ + int tm_year; /* year - 1900 */ + int tm_wday; /* day of week (Sunday = 0) */ + int tm_yday; /* day of year (0-365) */ + int tm_isdst; /* is daylight saving time in effect? */ + char *tm_zone; /* time zone abbreviation (optional) */ + long tm_gmtoff; /* offset from UT in seconds (optional) */ + + Tm_isdst is non-zero if daylight saving time is in effect. + + Tm_gmtoff is the offset (in seconds) of the time represented from UT, + with positive values indicating east of the Prime Meridian. The + field's name is derived from Greenwich Mean Time, a precursor of UT. + + In struct tm the tm_zone and tm_gmtoff fields exist, and are filled in, + only if arrangements to do so were made when the library containing + these functions was created. Similarly, the tzname variable is + optional. There is no guarantee that these fields and this variable + will continue to exist in this form in future releases of this code. + +FILES + /usr/share/zoneinfo time zone information directory + /usr/share/zoneinfo/localtime local time zone file + /usr/share/zoneinfo/posixrules used with POSIX-style TZ's + /usr/share/zoneinfo/GMT for UTC leap seconds + + If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from + /usr/share/zoneinfo/posixrules. + +SEE ALSO + getenv(3), newstrftime(3), newtzset(3), time(2), tzfile(5) + +NOTES + The return values of asctime, ctime, gmtime, and localtime point to + static data overwritten by each call. The tzname variable (once set) + and the tm_zone field of a returned struct tm both point to an array of + characters that can be freed or overwritten by later calls to the + functions localtime, tzfree, and tzset, if these functions affect the + time zone information that specifies the abbreviation in question. The + remaining functions and data are thread-safe. + + Asctime, asctime_r, ctime, and ctime_r behave strangely for years + before 1000 or after 9999. The 1989 and 1999 editions of the C + Standard say that years from -99 through 999 are converted without + extra spaces, but this conflicts with longstanding tradition and with + this implementation. The 2011 edition says that the behavior is + undefined if the year is before 1000 or after 9999. Traditional + implementations of these two functions are restricted to years in the + range 1900 through 2099. To avoid this portability mess, new programs + should use strftime instead. + + NEWCTIME(3) |