ctime(S) 6 January 1993 ctime(S) Name ctime, localtime, gmtime, asctime, strftime, tzset - convert date and time to string Syntax cc . . . -lc #include <sys/types.h> #include <time.h> extern long altzone; char *asctime (tm) struct tm *tm; char *ctime (clock) time_t *clock; extern int daylight; struct tm *gmtime (timer) time_t *timer; struct tm *localtime (clock) time_t *clock; extern long timezone; extern char *tzname[2]; void tzset () cc . . . -lintl size_t strftime (s, maxsize, format, timeptr) char *s; size_t maxsize; char *format; struct tm *timeptr; Description 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 00:00:00 Greenwich Mean Time (GMT) on January 1, 1970. This point is arbitrary and does not have any spe- cial significance. ctime converts the time pointed to by clock representing seconds since the epoch to local time in the form of a string. ctime is equivalent to asctime(localtime[clock]). The timet type is defined in the sys/types.h header file. localtime converts 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 corrects for the timezone and seasonal time adjustments. The output is the same as that generated by tzset. The timet type is defined in the sys/types.h header file. The return value is a pointer to a 26-character string in the following form. All the fields have constant width. Fri Sep 13 00:00:00 1986\n\0 localtime and gmtime return pointers to tm structures, described below. localtime corrects for the main time zone and possible alternate (Day- light Savings) time zone; gmtime converts directly to Coordinated Univer- sal Time (UTC), which is the same as Greenwich Mean Time (GMT). asctime converts a tm structure to a 26-character string, and returns a pointer to the string. The asctime 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%3d %.2d:%.2d:%.2d %d\n", wday_name[timeptr->tm_wday], mon_name[timeptr->tm_mon], timeptr->tm_min, timeptr->tm_sec, 1900 + timeptr->tm_year); return result; } Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file. The structure declaration is: struct tm { int tm_sec; /* seconds after the minute -- [0, 59] */ 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 GMT (east < 0) */ char tm_name[LTZNMAX]; /* name of timezone */ }; tmisdst is non-zero if the alternate time zone is in effect. Set the LANG environment variable to specify the language that strftime uses for output. If LANG is empty, unset, or set to an unsupported lan- guage, the last language requested is used (the default is the usa- english strings). The strftime function places its output (according to the format string format and the time values contained in the structure pointed to by timeptr), followed by the null character (\0) in consecutive bytes start- ing at s. The maximum length of the output string is specified by max- size, the maximum number of characters including the terminating null character. The strftime function converts and formats the time values contained in the structure pointed to by timeptr under control of the format string format. The string format is a character string that can contain two types of objects. These are plain characters, which are simply copied to the output string, and directives. Each directive is introduced by the percent character (%). The %d, %H, %I, %j, %m, %M, %S, %U, %w, %W, %y, %Z, and %% directives are independent of the program's current locale (see locale(M)). The strings used to replace the %a, %A, %b, %B, %c, %p, %x, and %X directives are dependent on the program's current locale, and are defined using the utility timtbl(M)). The directives are: %a is replaced by the locale's abbreviated weekday name %A is replaced by the locale's full weekday name %b is replaced by the locale's abbreviated month name %B is replaced by the locale's full month name %c is replaced by the locale's appropriate date and time represen- tation %d is replaced by the day of the month as a decimal number (01-31) %D is replaced by the date (%m/%d/%y). %h is replaced by the locale's abbreviated month name %H is replaced by the hour (24-hour clock) as a decimal number (00-23) %I is replaced by the hour (12-hour clock) as a decimal number (01-12) %j is replaced by the day of the year as a decimal number (001- 366) %m is replaced by the month as a decimal number (01-12) %M is replaced by the minute as a decimal number (00-59) %n is replaced by a newline character. %p is replaced by the locale's equivalent of AM or PM. %r is replaced by the time in AM or PM notation according to the British or US conventions (%I:%M:%S\[AM|PM]). %S is replaced by the second as a decimal number (00-61) %t is replaced by a tab character. %T is replaced by the time (%H:%M:%S). %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number (00-53). %w is replaced by the weekday as a decimal number [0(Sunday)-6]. %W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (00-53). %x is replaced by the locale's appropriate date representation. %X is replaced by the locale's appropriate time representation. %y is replaced by the year without a century as a decimal number (00-99). %Y is replaced by the year with a century as a decimal number. %Z is replaced by the timezone name, or by no characters if no timezone exists. %% is replaced by % The external long variable timezone contains the difference, in seconds, between GMT and the main time zone; the external long variable altzone contains the difference, in seconds, between GMT and the alternate time zone; both, timezone and altzone default to 0 (GMT). The external vari- able 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", " " }; 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, 1989. 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. LTZNMAX specifies the maximum number bytes in the timezone name. tzset uses the value of the environment variable TZ to set time conver- sion information used by localetime(), ctime(), strftime() and mktime(). If TZ is absent from the environment, implementation-defined default time zone information is used. For example, the setting for New Jersey in 1986 could be "EST5EDT4,117/2:00:00,299/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, 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, the ending date of the alternate time zone is the 299th day at 2 AM, and daylight is set to non-zero. Starting and ending times are relative to the current 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. 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 value The strftime function returns the number of characters placed in the string s (not including the terminating null character), or zero if the length of the output string would exceed maxsize. In the latter case, the content of the output string s is undefined. Zero is also returned by strftime if the function detects a situation which would lead to infinite recursion; for example, if a format string refers to itself. Note 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 annu- ally if the full form of the TZ variable is specified. See also difftime(S), environ(M), getenv(S), mktime(S), nlcxtime(S), printf(S), profile(M), putenv(S), stime(S), strftime(S), time(S), timezone(F), timtbl(M) Standards conformance asctime, ctime, gmtime and localtime are conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; 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. strftime is conformant with: ANSI X3.159-1989 Programming Language -- C; IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); X/Open Portability Guide, Issue 3, 1989; and NIST FIPS 151-1. tzset is conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); and NIST FIPS 151-1.