ctime_r(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 *clock, struct tm *res);

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

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

  POSIX
     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);


DESCRIPTION

     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\n\0

     The ctime() function is equivalent to:

          asctime(localtime(clock))

     The ctime(), asctime(), gmtime(), and localtime()  functions
     return  values  in  one of two static 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.

     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  POSIX ctime_r() function does not take a buflen parame-
     ter.

     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  asc-
     time()  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 POSIX 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, 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 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  differ-
     ence, 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 conver-
     sion  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.  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, daylight, 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)).


ERRORS

     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.


USAGE

     These functions do not support localized date and time  for-
     mats.  The  strftime(3C) function can be used when localiza-
     tion 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.


EXAMPLES

     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 example, 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 posi-
     tive. 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 ver-
     sion of localtime(), localtime_r(), ctime(), and ctime_r().


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|


SEE ALSO

     time(2),  Intro(3),  getenv(3C),   mktime(3C),   printf(3C),
     putenv(3C), setlocale(3C), strftime(3C), TIMEZONE(4), attri-
     butes(5), environ(5)


NOTES

     When compiling multithreaded programs, see  Intro(3),  Notes
     On Multithreaded Applications.

     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.

     The asctime(), ctime(), gmtime(), and localtime()  functions
     are unsafe in multithread applications.  The asctime_r() and
     gmtime_r()   functions   are   MT-Safe.    The    ctime_r(),
     localtime_r(),  and  tzset()  functions  are MT-Safe in mul-
     tithread applications, as long as no  user-defined  function
     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().

     Solaris 2.4 and earlier releases provided definitions of the
     ctime_r(),  localtime_r(), gmtime_r(), and asctime_r() func-
     tions 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
     POSIX standard interface.

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


Man(1) output converted with man2html