ctime man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

CTIME(3C)							     CTIME(3C)

NAME
       ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asc‐
       time_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);

DESCRIPTION
       The ctime() function converts the time pointed to by clock,  represent‐
       ing  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 val‐
       ues  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 parame‐
       ter.   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  sec‐
       onds,  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 time‐
       zone  and altzone default to 0 (UTC). The external variable daylight is
       non-zero if an alternate time zone exists. The time zone names are con‐
       tained 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, 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)).

RETURN VALUES
       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.

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.

       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.

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 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, day‐
       light, 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 off‐
       set from standard time, and could return incorrect values. This affects
       the   64-bit   version  of  localtime(),	 localtime_r(),	 ctime(),  and
       ctime_r().

ATTRIBUTES
       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() func‐
       tions are MT-Safe. The ctime_r(), localtime_r(), and tzset()  functions
       are  MT-Safe  in	 multithread  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().

SEE ALSO
       time(2), Intro(3), getenv(3C), mktime(3C), printf(3C), putenv(3C), set‐
       locale(3C), strftime(3C), TIMEZONE(4), attributes(5), environ(5), stan‐
       dards(5)

NOTES
       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 administra‐
       tor 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 pro‐
       vided 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).

				 May 27, 2005			     CTIME(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net