ctime(3C)																 ctime(3C)

NAME

       ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asctime_r, tzset - convert date and time to string

SYNOPSIS

       #include <time.h>

       char *ctime(const time_t *clock);

       struct tm *localtime(const time_t *clock);

       struct tm *gmtime(const time_t *clock);

       char *asctime(const struct tm *tm);

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

       void tzset(void);

       char *ctime_r(const time_t *clock, char *buf, int buflen);

       struct tm *localtime_r(const time_t *restrict clock, struct tm *restrict res);

       struct tm *gmtime_r(const time_t *restrict clock, struct tm *restrict res);

       char *asctime_r(const struct tm *restrict tm, char *restrict buf, int buflen);

   Standard conforming
       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

       char *ctime_r(const time_t *clock, char *buf);

       char *asctime_r(const struct tm *tm, char *buf);

       The  ctime()  function  converts  the  time pointed to by clock, representing the time in seconds since the Epoch (00:00:00 UTC, January 1,
       1970), to local time in the form of a 26-character string, as shown below. Time zone and  daylight  savings  corrections  are  made  before
       string generation. The fields are in constant width:

	      Fri Sep 13 00:00:00 1986


       The ctime() function is equivalent to:

	      asctime(localtime(clock))

       The  ctime(),  asctime(),  gmtime(), and localtime() functions return values in one of two thread-specific data objects: a broken-down time
       structure and an array of char. Execution of any of the functions can overwrite the information returned in either of these objects by  any
       of the other functions executed by the same thread.

       The  ctime_r()  function  has the same functionality as ctime() except that the caller must supply a buffer buf with length buflen to store
       the result; buf must be at least 26 bytes. The standard-conforming ctime_r() function does not take a buflen parameter.

       The localtime() and gmtime() functions return pointers to tm structures (see below). The localtime() function corrects for  the	main  time
       zone  and  possible  alternate ("daylight savings") time zone; the gmtime() function converts directly to Coordinated Universal Time (UTC),
       which is what the UNIX system uses internally.

       The localtime_r() and gmtime_r() functions have the same functionality as localtime() and gmtime() respectively,  except  that  the  caller
       must supply a buffer res to store the result.

       The  asctime()  function  converts  a tm structure to a 26-character string, as shown in the previous example, and returns a pointer to the
       string.

       The asctime_r() function has the same functionality as asctime() except that the caller must supply a buffer buf with length buflen for the
       result  to  be  stored.	 The  buf  argument must be at least 26 bytes. The standard-conforming asctime_r() function does not take a buflen
       parameter.  The asctime_r() function returns a pointer to buf upon success.  In case of failure, NULL is returned and errno is set.

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

       int   tm_sec;	/* seconds after the minute -- [0, 60] */
			/* 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 alternate daylight savings time */

       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 was in effect.

       The  external  time_t variable altzone contains the difference, in seconds, between Coordinated Universal Time and the alternate time zone.
       The external variable timezone contains the difference, in seconds, between UTC and local standard time.  The  external	variable  daylight
       indicates  whether  time should reflect daylight savings time. 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", "" };

       These  functions know about the peculiarities of this conversion for various time periods for the U.S. (specifically, the years 1974, 1975,
       and 1987). They start handling the new daylight savings time starting with the first Sunday in April, 1987.

       The tzset() function uses the contents of the environment variable TZ to override the value of the  different  external	variables.  It	is
       called by asctime() and can also be called by the user. If TZ is not specified or has an invalid setting, tzset() uses GMT0. See environ(5)
       for a description of the TZ environment variable.

       Starting and ending times are relative to the current local time zone. If the alternate time zone start and end dates and the time are  not
       provided,  the days for the United States that year will be used and the time will be 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() change the values of the external  variables  timezone,  altzone,  day-
       light, and tzname.

       Note  that  in  most installations, TZ is set to the correct value by default when the user logs on, using the local /etc/default/init file
       (see TIMEZONE(4)).

       Upon successful completion, the gmtime() and localtime() functions return a pointer to a struct tm. If an error is detected,  gmtime()  and
       localtime() return a null pointer.

       Upon  successful completion, the gmtime_r() and localtime_r() functions return the address of the structure pointed to by the res argument.
       If an error is detected, gmtime_r() and localtime_r() return a null pointer and set errno to indicate the error.

       The ctime_r() and asctime_r() functions will fail if:

       ERANGE	       The length of the buffer supplied by the caller is not large enough to store the result.

       The gmtime(), gmtime_r(), localtime(), and localtime_r() functions will fail if:

       EOVERFLOW       The result cannot be represented.

USAGE

       These functions do not support localized date and time formats. The strftime(3C) function can be used when localization is required.

       The localtime(), localtime_r(), gmtime(), gmtime_r(), ctime(), and ctime_r() functions assume Gregorian dates. Times before the adoption of
       the Gregorian calendar will not match historial records.

       Example 1: Examples of the tzset() function.

       The  tzset() function scans the contents of the environment variable and assigns the different fields to the respective variable. For exam-
       ple, the most complete setting for New Jersey in 1986 could be:

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

       or simply

       EST5EDT

       An example of a southern hemisphere setting such as the Cook Islands could be

       KDT9:30KST10:00,63/5:00,302/20:00

       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 (using zero-based Julian days), and daylight is set positive. Starting and ending times are relative  to  the  current  local  time
       zone.  If  the alternate time zone start and end dates and the time are not provided, the days for the United States that year will be used
       and the time will be 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. The ctime(), localtime(),
       mktime(), and strftime() functions also update these external variables as if they had called tzset() at the time specified by  the  time_t
       or struct tm value that they are converting.

BUGS

       The  zoneinfo  timezone	data  files do not transition past Tue Jan 19 03:14:07 2038 UTC.  Therefore for 64-bit applications using zoneinfo
       timezones, calculations beyond this date might not use the correct offset from standard time, and  could  return  incorrect  values.   This
       affects the 64-bit version of localtime(), localtime_r(), ctime(), and ctime_r().

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

       The asctime(), ctime(), gmtime(), and localtime() functions are safe to use in multithread applications because they employ thread-specific
       data. However, their use is discouraged because standards do not require them to be thread-safe. The asctime_r() and  gmtime_r()  functions
       are  MT-Safe. The ctime_r(), localtime_r(), and tzset() functions are MT-Safe in multithread applications, as long as no user-defined func-
       tion directly modifies one of the following variables: timezone, altzone, daylight, and tzname. These four variables  are  not  MT-Safe	to
       access. They are modified by the tzset() function in an MT-Safe manner.	The mktime(), localtime_r(), and ctime_r() functions call tzset().

       time(2),  Intro(3),  getenv(3C),  mktime(3C),  printf(3C), putenv(3C), setlocale(3C), strftime(3C), TIMEZONE(4), attributes(5), environ(5),
       standards(5)

       When compiling multithreaded programs, see Intro(3).

       The return values for asctime(), ctime(), gmtime(), and localtime() point to thread-specific data whose content is overwritten by each call
       by the same thread.

       Setting	the time during the interval of change from timezone to altzone or vice versa can produce unpredictable results. The system admin-
       istrator must change the Julian start and end days annually.

       If tzset() has previously evaluated the timezone identified by the value of the TZ  environment variable, tzset() can  reuse  the  previous
       settings of the external variables altzone, daylight, timezone, and tzname[] associated with that timezone.

       Solaris	2.4  and earlier releases provided definitions of the ctime_r(), localtime_r(), gmtime_r(), and asctime_r() functions as specified
       in POSIX.1c Draft 6. The final POSIX.1c standard changed the interface for ctime_r() and asctime_r(). Support for the Draft 6 interface	is
       provided  for compatibility only and might not be supported in future releases. New applications and libraries should use the standard-con-
       forming interface.

       For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and _REENTRANT  flags  are  automatically  turned  on  by  defining  the
       _POSIX_C_SOURCE flag with a value >= 199506L.

       In  Solaris  10,  gmtime(),  gmtime_r(), localtime(), and localtime_r() were updated to return a null pointer if an error is detected. This
       change was based on the SUSv3 specification. See standards(5).

								    27 May 2005 							 ctime(3C)