Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ctime(3C)		 Standard C Library Functions		     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 *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,  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 be-
       low.  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 static objects: a broken-down time structure	and an
       array of	char. Execution	of any of the functions	can overwrite the  in-
       formation returned in either of these objects by	any of the other func-
       tions.

       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 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 re-
       sult  to	 be  stored.   The buf argument	must be	at least 26 bytes. The
       POSIX asctime_r() function does not take	a buflen parameter.  The  asc-
       time_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 ef-
       fect, 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, be-
       tween  UTC and local standard time.  The	external variable daylight in-
       dicates 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.	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 de-
       fault 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	 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 af-
       fects 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	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+

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)

NOTES
       When compiling multithreaded programs, see Intro(3),  Notes  On	Multi-
       threaded	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 administra-
       tor 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  multithread	applications, as long as no user-defined func-
       tion directly modifies one of the following variables:  timezone,  alt-
       zone,  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() 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 re-
       leases. New applications	and libraries should use  the  POSIX  standard
       interface.

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

SunOS 5.9			  23 Dec 1999			     ctime(3C)

NAME | SYNOPSIS | DESCRIPTION | ERRORS | USAGE | EXAMPLES | BUGS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ctime&sektion=3c&manpath=SunOS+5.9>

home | help