| CTIME(3) | Library Functions Manual | CTIME(3) | 
asctime, asctime_r,
  ctime, ctime_r,
  ctime_rz, difftime,
  gmtime, gmtime_r,
  localtime, localtime_r,
  localtime_rz, mktime,
  mktime_z —
#include <time.h>
extern char *tzname[2];
char *
  
  asctime(const
    struct tm *tm);
char *
  
  asctime_r(const
    struct tm *restrict tm,
    char * restrict buf);
char *
  
  ctime(const
    time_t *clock);
char *
  
  ctime_r(const
    time_t *clock, char
    *buf);
char *
  
  ctime_rz(timezone_t
    restrict tz, const time_t
    *clock, char
  *buf);
double
  
  difftime(time_t
    time1, time_t
    time0);
struct tm *
  
  gmtime(const
    time_t *clock);
struct tm *
  
  gmtime_r(const
    time_t * restrict clock,
    struct tm * restrict
    result);
struct tm *
  
  localtime(const
    time_t *clock);
struct tm *
  
  localtime_r(const
    time_t * restrict clock,
    struct tm * restrict
    result);
struct tm *
  
  localtime_rz(timezone_t
    restrict tz, const time_t
    * restrict clock, struct
    tm * restrict result);
time_t
  
  mktime(struct
    tm *tm);
time_t
  
  mktime_z(timezone_t
    restrict tz, struct tm
    *restrict tm);
asctime family of functions provide various standard
  library routines to operate with time and conversions related to time.
asctime(tm)asctime() function converts a time value
      contained in the tm structure to a string with the
      following general format:
    
Thu Nov 24 18:22:48 1986\n\0
    
    The tm structure is described in tm(3).
asctime_r(tm,
    buf)asctime_r() has the same behavior as
      asctime(), but the result is stored in
      buf, which should have a size of at least 26
    bytes.ctime(clock)ctime() function converts a
      time_t, pointed to by clock,
      and returns a pointer to a string with the format described above. Years
      requiring fewer than four characters are padded with leading zeroes. For
      years longer than four characters, the string is of the form
    
Thu Nov 24 18:22:48     81986\n\0
    
    with five spaces before the year. These unusual formats are designed to make it less likely that older software that expects exactly 26 bytes of output will mistakenly output misleading values for out-of-range years.
The clock time stamp represents the time in seconds since 1970-01-01 00:00:00 Coordinated Universal Time (UTC). The POSIX standard says that time stamps must be nonnegative and must ignore leap seconds. Many implementations extend POSIX by allowing negative time stamps, and can therefore represent time stamps that predate the introduction of UTC and are some other flavor of Universal Time (UT). Some implementations support leap seconds, in contradiction to POSIX.
ctime_r(clock,
    buf)ctime_r() is similar to
      ctime(), except it places the result of the
      conversion in the buf argument, which should be 26
      or more bytes long, instead of using a global static buffer.ctime_rz(tz,
    clock, buf)ctime_rz() function is similar to
      ctime_r(), but it also takes a
      timezone_t argument, as returned by a previous call
      to tzalloc(), or a NULL
      pointer denoting Coordinated Universal Time (UTC).difftime(time1,
    time2)difftime() function returns the difference
      between two calendar times, (time1
      - time0), expressed in
      seconds.
    The ctime_r(),
        localtime_r(),
        gmtime_r(), and
        asctime_r() functions are like their unsuffixed
        counterparts, except that they accept an additional argument specifying
        where to store the result if successful.
The ctime_rz(),
        localtime_rz(), and
        mktime_z() functions are like their unsuffixed
        counterparts, except that they accept an extra initial
        zone argument specifying the timezone to be used
        for conversion. If zone is
        NULL, UT is used; otherwise,
        zone should have been allocated by
        tzalloc() and should not be freed until after
        all uses (e.g., by calls to strftime()) of the
        filled-in tm_zone() fields.
gmtime(clock)gmtime() function converts to Coordinated
      Universal Time (UTC) and returns a pointer to the tm
      structure described in
    tm(3).gmtime_r(clock,
    result)gmtime_r() function provides the same
      functionality as gmtime(), differing in that the
      caller must supply a buffer area result in which the
      result is stored.localtime(clock)localtime() is comparable to
      gmtime(). However,
      localtime() corrects for the timezone and any
      timezone adjustments (such as Daylight Saving Time in the U.S.A.). After
      filling in the tm structure, the function sets the
      tm_isdst'th element of tzname
      to a pointer to an ASCII string that is the timezone abbreviation to be
      used with localtime()'s return value.localtime_r(clock,
    result)gmtime_r(), the
      localtime_r() takes an additional buffer
      result as a parameter and stores the result in it.
      Note however that localtime_r() does not imply
      initialization of the local time conversion information; the application
      may need to do so by calling
      tzset(3).localtime_rz(tz,
    clock, result)localtime_rz() function is similar to
      localtime_r(), but it also takes a
      timezone_t argument, returned by a previous call to
      tzalloc(), or a NULL
      pointer denoting Coordinated Universal Time (UTC).mktime(tm)mktime() function converts the broken-down
      time, expressed as local time in the
      tm(3) structure, into a calendar
      time value with the same encoding as that of the values returned by the
      time(3) function. The
      following remarks should be taken into account.
    For example, consider a struct tm
            initialized with tm_year = 122,
            tm_mon = 10, tm_mday =
            30, tm_hour = 22, tm_min
            = 57, and tm_sec = 0. Incrementing
            tm_min by 13 and calling
            mktime() would lead to
            tm_hour = 23 and tm_min
            = 10.
This normalizing can lead to cascading changes: Again using a struct tm initialized as in the above example but with tm_hour = 23, the same change would lead to tm_mon = 11, tm_mday = 1, tm_hour = 0, and tm_min = 10.
Negative values may also be normalized with similar cascading effect such that e.g., a tm_hour of -1 means 1 hour before midnight on the previous day and so on.
mktime() to presume initially that daylight
          saving time respectively, is or is not in effect for the specified
          time.mktime() function to attempt to divine whether
          daylight saving time is in effect for the specified time; in this case
          it does not use a consistent rule and may give a different answer when
          later presented with the same argument.The function returns the specified calendar time; if the
        calendar time cannot be represented, it returns
        (time_t)-1. This can happen either because the
        resulting conversion would not fit in a time_t
        variable, or because the time specified happens to be in the daylight
        savings gap and tm_isdst was set to
        -1. Other mktime()
        implementations do not return an error in the second case and return the
        appropriate time offset after the daylight savings gap. There is code to
        mimick this behavior, but it is not enabled by default.
mktime_z(tz,
    tm)mktime_z() function is similar to
      mktime() but it also takes a const
      timezone_t argument, returned by a previous call to
      tzalloc(), or a null pointer denoting Coordinated
      Universal Time (UTC).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 (0 - 60) */
       int tm_min;      /* minutes (0 - 59) */
       int tm_hour;     /* hours (0 - 23) */
       int tm_mday;     /* day of month (1 - 31) */
       int tm_mon;      /* month of year (0 - 11) */
       int tm_year;     /* year - 1900 */
       int tm_wday;     /* day of week (Sunday = 0) */
       int tm_yday;     /* day of year (0 - 365) */
       int tm_isdst;    /* is daylight saving time in effect? */
       char *tm_zone;   /* abbreviation of timezone name (optional) */
       long tm_gmtoff;  /* offset from UT in seconds (optional) */
tzname will continue
  to exist in this form in future releases of this code.
asctime() and
      ctime() functions return a pointer to a static
      character buffer, and the asctime_r(),
      ctime_r(), and ctime_rz()
      function return a pointer to the user-supplied buffer. On failure they all
      return NULL and no errors are defined for
    them.gmtime(), and
      localtime() functions return a pointer to a
      statically allocated struct tm whereas the
      gmtime_r(), localtime_r(),
      and localtime_rz(), functions return a pointer to
      the user-supplied struct tm. On failure they all
      return NULL and the global variable
      errno is set to indicate the error.mktime() and
      mktime_z() function returns the specified time
      since the Epoch as a time_t type value. If the time
      cannot be represented, then mktime() and
      mktime_z() return (time_t)-1
      setting the global variable errno to indicate the
      error.tzalloc() function returns a pointer to a
      timezone_t object or NULL on
      failure, setting errno to indicate the error. It may
      also return NULL when the
      name argument is NULL, and
      this is not an error, but a way of referring to Coordinated Universal Time
      (UTC).tzgetzone() function returns string containing the
      name of the timezone given in tz.If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from /usr/share/zoneinfo/posixrules.
EINVAL]EOVERFLOW]All functions that return values, except their “z” variants, can also return the same errors as open(2) and malloc(3).
ctime(), difftime(),
  asctime(), localtime(),
  gmtime() and mktime()
  functions conform to ANSI X3.159-1989
  (“ANSI C89”). Rest of the functions conform to
  IEEE Std 1003.1-2008 (“POSIX.1”).
ctime() function appeared in
  Version 1 AT&T UNIX.
tzname variable
  (once set) and the tm_zone field of a returned
  struct tm point to an array of characters that can be
  freed or overwritten by later calls to the functions
  localtime(), tzfree(), and
  tzset(), if these functions affect the timezone
  information that specifies the abbreviation in question. The remaining
  functions and data are thread-safe. The functions that do take an explicit
  timezone_t argument and set the fields of a supplied
  struct tm should not call
  tzfree() since the tm_zone field
  of the struct tm points to data allocated by
  tzalloc().
The asctime(),
    asctime_r(), ctime(),
    ctime_r(), and ctime_rz(),
    functions behave strangely for years before 1000 or after 9999. The 1989 and
    1999 editions of the C Standard say that years from -99 through 999 are
    converted without extra spaces, but this conflicts with longstanding
    tradition and with this implementation. The 2011 edition says that the
    behavior is undefined if the year is before 1000 or after 9999. Traditional
    implementations of these two functions are restricted to years in the range
    1900 through 2099. To avoid this portability mess, new programs should use
    strftime() instead.
| October 22, 2022 | NetBSD 10.0 |