ctime(3)
- NetBSD Manual Pages
CTIME(3) CTIME(3)
NAME
asctime, asctime_r, ctime, ctime_r, difftime, gmtime,
gmtime_r, localtime, localtime_r, mktime - convert date
and time to ASCII
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <time.h>
extern char *tzname[2];
char *ctime(const time_t *clock);
char *ctime_r(const time_t *clock, char *buf);
double difftime(time_t time1, time_t time0);
char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *, char *buf);
struct tm *localtime(const time_t *clock);
struct tm *localtime_r(const time_t *clock, struct tm *result);
struct tm *gmtime(const time_t *clock);
struct tm *gmtime_r(const time_t *clock, struct tm *result);
time_t mktime(struct tm *tm);
DESCRIPTION
Ctime converts a long integer, pointed to by clock, repre-
senting the time in seconds since 00:00:00 UTC,
1970-01-01, and returns a pointer to a 26-character string
of the form
Thu Nov 24 18:22:48 1986\n\0
All the fields have constant width.
The ctime_r function provides the same functionality as
ctime differing in that the caller must supply a buffer
area buf with a size of at least 26 bytes, in which the
result is stored.
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 U.S.A.). After filling in the ``tm'' structure,
localtime sets the tm_isdst'th element of tzname to a
pointer to an ASCII string that's the time zone abbrevia-
tion to be used with localtime's return value.
Gmtime converts to Coordinated Universal Time.
The gmtime_r and localtime_r functions provide the same
1
CTIME(3) CTIME(3)
functionality as gmtime and localtime differing in that
the caller must supply a buffer area result in which the
result is stored; also, localtime_r does not imply ini-
tialization of the local time conversion information; the
application may need to do so by calling tzset.
Asctime converts a time value contained in a ``tm'' struc-
ture to a 26-character string, as shown in the above exam-
ple, and returns a pointer to the string.
The asctime_r function provides the same functionality as
asctime differing in that the caller must supply a buffer
area buf with a size of at least 26 bytes, in which the
result is stored.
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 summer time (for example, Daylight Saving Time in the
U.S.A.) 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 summer time
is in effect for the specified time.) On successful com-
pletion, the values of the tm_wday and tm_yday components
of the structure are set appropriately, and the other com-
ponents 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.
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 after the minute (0 - 61) */
int tm_min; /* minutes after the hour (0 - 59) */
int tm_hour; /* hours since midnight (0 - 23) */
int tm_mday; /* day of the month (1 - 31) */
int tm_mon; /* months since January (0 - 11) */
int tm_year; /* years since 1900 */
int tm_wday; /* day of week (Sunday = 0) */
int tm_yday; /* day of year (0 - 365, 0 = Jan 1) */
int tm_isdst; /* is summer time in effect? */
2
CTIME(3) CTIME(3)
long tm_gmtoff; /* offset from UTC in seconds */
char *tm_zone; /* abbreviation of timezone name */
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. There is no guar-
antee that these fields will continue to exist in this
form in future releases of this code.
Tm_isdst is non-zero if summer time is in effect.
Tm_gmtoff is the offset (in seconds) of the time repre-
sented from UTC, with positive values indicating east of
the Prime Meridian.
FILES
/etc/localtime local time zone file
/usr/share/zoneinfo time zone information
directory
/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), strftime(3), tzset(3), time(3), tzfile(5)
STANDARDS
The ctime(), difftime(), asctime(), localtime(), gmtime()
and mktime() functions conform to ANSI X3.159-1989 (``ANSI
C''). The ctime_r(), asctime_r(), localtime_r() and
gmtime_r() functions conform to IEEE Std1003.1c-1995
(``POSIX'').
NOTES
The return values point to static data; the data is over-
written by each call. The tm_zone field of a returned
struct tm points to a static array of characters, which
will also be overwritten at the next call (and by calls to
tzset).
Avoid using out-of-range values with mktime when setting
up lunch with promptness sticklers in Riyadh.
3
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.