ctime(S)

ctime, localtime, gmtime, asctime, tzset -- convert date and time to string

Syntax

cc . . . -lc

#include <time.h>

char *asctime  (const struct tm *tm);
char *asctime_r(const struct tm *tm, char *result);

char *ctime  (const time_t *clock);
char *ctime_r(const time_t *clock, char *result);

struct tm *gmtime  (const time_t *clock);
struct tm *gmtime_r(const time_t *clock, struct tm *result);

struct tm *localtime  (const time_t *clock);
struct tm *localtime_r(const time_t *clock, struct tm *result);

void tzset(void);

extern time_t timezone, altzone;
extern int daylight;
extern char *tzname[2];

Description

asctime- converts a tm structure to a 26-character string

ctime- converts UNIX ``epoch'' time to local time

gmtime- convert time to UTC

localtime- converts time pointed to by clock to tm structure

tzset- changes values of time variables

altzone- difference in seconds between UTC and alternate time zone

daylight- set to non-zero value if alternate time zone exists

timezone- difference in seconds between UTC and local time zone

tzname- contains time zone names

In many of the functions described on this manual page, ``epoch'' is used to describe the moment at which time in the UNIX operating system started. The exact starting point is 1970-01-01 00:00 UTC. This point is arbitrary and does not have any special significance.

The reentrant functions (suffixed by _r) require the user to allocate the necessary space for the return value and pass a pointer to this area using result.

localtime(S) and localtime_r( ) convert the time in seconds pointed to by clock into a tm structure. The time in clock is the number of seconds since the epoch. localtime_r( ) converts the calendar time pointed to by clock into a broken-down time that is stored in the struct tm pointed to by result. It returns result, upon successful completion. The output is the same as that generated by tzset(S).

localtime( ) and gmtime( ) return pointers to tm structures, described below. localtime( ) corrects for the main time zone and possible alternate (Daylight Savings) time zone; gmtime( ) and gmtime_r( ) convert the calendar time pointed to by clock into a broken-down time expressed as Coordinated Universal Time (UTC). gmtime_r( ) stores the broken-down time in the struct tm pointed to by result and returns result upon successful completion.

asctime converts a tm structure to a 26-character string, and returns a pointer to the string. asctime_r( ) converts the broken-down time in the structure pointed to by tm into a string that is placed in the location pointed to by result, which is assumed to hold at least 26 characters. It returns result upon successful completion.

The asctime(S) routine uses the equivalent of the following algorithm to create the date string:

       char *asctime(timeptr)
       struct tm *timeptr;
       {
               static char wday_name[7][3] = {
                       "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
               };
               static char mon_name[12][3] = {
                       "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                       "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
               };
               static char result[26];
   
               sprintf(result, "%.3s %.3s %2d %.2d:%.2d:%.2d %d\n",
                       wday_name[timeptr->tm_wday],
                       mon_name[timeptr->tm_mon],
                       timeptr->tm_mday, timeptr->tm_hour,
                       timeptr->tm_min, timeptr->tm_sec,
                       1900 + timeptr->tm_year);
               return result;
       }

ctime(S) and ctime_r( ) convert the time pointed to by clock representing seconds since the epoch to local time in the form of a 26-character string, and return a pointer to this string. ctime( ) is equivalent to asctime_r(localtime_r(clock,lresult), aresult). ctime_r( ) returns result upon successful completion. The string has the following form. All the fields have constant width.

   Fri Sep 13 00:00:00 1986\n\0

Time zone and daylight savings corrections are made before the string is generated.

Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file. The tm structure declaration is:

   struct  tm {
           int     tm_sec;   /* seconds after the minute -- [0, 61]  */
                             /* 60 and 61 for leap seconds          */
           int     tm_min;   /* minutes after the hour -- [0, 59]    */
           int     tm_hour;  /* hour 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;  /* days since Sunday -- [0, 6]          */
           int     tm_yday;  /* days since January 1 -- [0, 365]     */
           int     tm_isdst; /* flag for daylight savings time      */
           long    tm_tzadj; /* seconds from UTC (east < 0)         */
           char    tm_name[LTZNMAX];  /* name of timezone           */
   };

The value of tm_isdst is positive if daylight savings time is in effect, zero if daylight savings time is not in effect, and negative if the information is not available. (Previously, the value of tm_isdst was defined as non-zero if daylight savings time was in effect.)

The external time_t variable timezone contains the difference, in seconds, between UTC and the local time zone; the external time_t variable altzone contains the difference, in seconds, between UTC and the alternate time zone; both timezone and altzone default to 0 (UTC). The external variable daylight is non-zero if an alternate time zone exists. The time zone names are contained in the external variable tzname, which by default is set to

   char *tzname[2] = { "GMT", "   " };

LTZNMAX specifies the maximum number of bytes in the time zone name.

The functions handle the peculiarities of this conversion for various time periods for the USA (specifically, the years 1974, 1975, 1976, and 1987). The functions handle the new daylight savings time starting with the first Sunday in April, 1987.

tzset( ) uses the contents of the environment variable TZ to override the value of the different external variables. See timezone(F) or environ(M) for the syntax of TZ. tzset( ) also sets the external variable daylight to zero if Daylight Savings Time conversions should never be applied for the time zone in use; otherwise, non-zero.

tzset( ) uses the value of the environment variable TZ to set time conversion information used by localtime(S), ctime(S), strftime(S) and mktime(S). If TZ is absent from the environment, implementation-defined default time zone information is used.

For example, the setting of TZ for New Jersey in 1986 could be

   "EST5EDT4,116/2:00:00,298/2:00:00" .

or simply

   EST5EDT

A southern hemisphere setting could be

   "KDT9:30KST10:00,303/20:00,64/5:00"

When the longer format is used, the variable must be surrounded by double quotes as shown. For more details, see timezone(F) and environ(M).

In the longer version of the New Jersey example of TZ, the following are set by tzset( ):

tzname[0] is EST
timezone is set to 5*60*60
tzname[1] is EDT
altzone is set to 4*60*60
the starting date of the alternate time zone is the 117th day at 2 AM (using zero-based Julian days)
the ending date of the alternate time zone is the 299th day at 2 AM
daylight is set to positive

Starting and ending times are relative to the alternate time. If the alternate time zone start and end dates and the time are not provided, the days for the United States that year are used and the time is 2 AM. If the start and end dates are provided but the time is not provided, the time will be 2 AM. The effects of tzset( ) are thus to change the values of the external variables timezone, altzone, daylight, and tzname. tzset( ) is called by localtime( ) and may also be called explicitly by the user.

Note that in most installations, TZ is set to the correct value by default when the user logs on, via the local /etc/profile file (see profile(M)).

Return values

asctime( ) returns a date string representing the converted time; ctime( ) returns a date string, with time expressed in local time.

gmtime( ) returns a pointer to a tm structure, with time expressed in UTC (which is the same as GMT); localtime( ) returns a pointer to a tm structure, with time expressed in local time.

Diagnostics

If an error occurs, localtime_r( ) and gmtime_r( ) return (struct tm *)NULL.

Notes

The return values for ctime( ), localtime( ) and gmtime( ) point to static data whose content is overwritten by each call.

Setting the time during the interval of change from timezone to altzone or vice versa can produce unpredictable results.

The system administrator must change the Julian start and end days annually if the full form of the TZ variable is specified.

Files

/usr/lib/locale/language/LC_TIME: file containing locale specific date and time information

Standards conformance

asctime(S), ctime(S), gmtime(S) and localtime(S) are conformant with:

X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992;
ANSI X3.159-1989 Programming Language -- C ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

tzset(S) is conformant with:

X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .