ctime(3)						     Library Functions Manual							  ctime(3)

Name
       ctime, localtime, gmtime, asctime, difftime, mktime, timezone, tzset - date and time functions

Syntax
       As shown, the and calls are common to both the non-System V environment and the System V environment.

   Common to Both Environments
       #include <time.h>

       void tzset()

       char *ctime(clock)
       time_t *clock;

       char *asctime(tm)
       struct tm *tm;

       struct tm *localtime(clock)
       time_t *clock;

       struct tm *gmtime(clock)
       time_t *clock;

       double difftime(time1, time0)
       time_t time1, time0;

       time_t mktime(timeptr)
       struct tm *timeptr;

       extern char *tzname[2];

   BSD Environment Only
       char *timezone(zone, dst)

   System V and POSIX Environments Only
       extern long timezone;

       extern int daylight;

Description
       The call uses the value of the environment variable TZ to set up the time conversion information used by

       If  TZ  does  not appear in the environment, the file is used by If this file fails for any reason, the Greenwich Mean Time (GMT) offset as
       provided by the kernel is used.	In this case, Daylight Savings Time (DST) is ignored, resulting in the time being incorrect by some amount
       if DST is currently in effect.  If this fails for any reason, GMT is used.

       If  TZ  appears in the environment but its value is a null string, GMT is used; if TZ appears and its value is not a null string, its value
       is interpreted using rules specific to the System V and non-System V environments.

       Programs that always wish to use local wall clock time should explicitly remove the environmental variable TZ with

       The call converts a long integer, pointed to by clock, representing the time in seconds since 00:00:00 GMT, January 1, 1970, and returns  a
       pointer to a 26-character string in the following form.	All the fields have constant width.
       Sun Sep 16 01:03:52 1985


       The  and  calls return pointers to tm structures, described below.  The call corrects for the time zone and possible DST; converts directly
       to GMT, which is the time the ULTRIX system uses.

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

       Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file.	The structure declaration is:
       struct tm {
	       int tm_sec;     /* seconds (0 - 59) */
	       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;   /* flag: daylight savings time in
				     effect */
	       long tm_gmtoff; /* offset from GMT in seconds */
	       char *tm_zone;  /* abbreviation of timezone name */

       };
       tm_isdst is nonzero if DST is in effect.

       tm_gmtoff is the offset (in seconds) of the time represented from GMT, with positive values indicating East of Greenwich.

       The call computes the difference between two calendar times: time1 - time0 and returns the difference expressed in seconds.

       The call converts the broken-down local time in the tm structure pointed to by timeptr into a calendar time value with the same encoding as
       that  of  the values returned by The values of tm_wday and tm_yday in the structure are ignored, and the other values are not restricted to
       the ranges indicated above for the tm structure. A positive or zero value for tm_isdst causes to presume that DST, respectively, is  or	is
       not  in	effect for the specified time. A negative value causes to attempt to determine whether DST is in effect for the specified time. On
       successful completion, the values of tm_wday and tm_yday are set appropriately, and the other components are set to represent the specified
       calendar time, but with their values forced to the ranges indicated above. If the calendar time cannot be represented, the function returns
       the value (time_t)-1.

       The external variable tzname, contains the current time zone names. The function sets this variable.

   BSD and POSIX Environment Only
       If TZ appears in the environment and its value is not a null string, its value has one of three formats:

	   :

       or

	   :pathname

       or

	   stdoffset[dst[offset][,start[/time],end[/time]]]

       If TZ is the single colon format (first format), GMT is used.

       If TZ is the colon followed by a pathname format (second), the characters following the colon specify a pathname  of  a	format	file  from
       which to read the time conversion information. If the pathname begins with a slash, it represents an absolute pathname; otherwise the path-
       name is relative to the system time conversion information directory If this file fails for any reason, the GMT offset as provided  by  the
       kernel is used.

       If the first character in TZ is not a colon (third format), the components of the string have the following meaning:

       std and dst    Three or more characters that are the designation for the standard (std) or summer (dst) time zone. Only std is required; if
		      dst is missing, then summer time does not apply in this locale. Upper- and lowercase letters  are  explicitly  allowed.  Any
		      characters except a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL are allowed.

       offset	      Indicates the value to be added to the local time to arrive at Coordinated Universal Time. The offset has the form:

			  hh[:mm[:ss]]

		      The  minutes  (mm)  and seconds (ss) are optional. The hour (hh) is required and may be a single digit. The offset following
		      std is required. If no offset follows dst, summer time is assumed to be one hour ahead of standard time. One or more  digits
		      may  be  used;  the  value is always interpreted as a decimal number.  The hour must be between zero and 24, and the minutes
		      (and seconds) - if present - between zero and 59. If preceded by a "-", the time zone is east of the Prime Meridian;  other-
		      wise it is west (which may be indicated by an optional preceding "+").

       start and end  Indicates when to change to and back from summer time. Start describes the date when the change from standard to summer time
		      occurs and end describes the date when the change back happens. The format of start and end must be one of the following:

		      Jn      The Julian day n (1 <= n <= 365). Leap days are not counted.  That is, in all years, including leap years,  February
			      28 is day 59 and March 1 is day 60. It is impossible to explicitly refer to the occasional February 29.

		      n       The zero-based Julian day (0 <= n <= 365). Leap days are counted, and it is possible to refer to February 29.

		      Mm.n.d  The  nth d day of month m (1 <= n <= 5, 0 <= d <= 6, 1 <= m <= 12). When n is 5 it refers to the last d day of month
			      m. Day 0 is Sunday.

       time	      The time field describes the time when, in current time, the change to or from summer time occurs. Time has the same  format
		      as  offset  except that no leading sign (a minus sign (-) or a plus sign (+)) is allowed. The default, if time is not given,
		      is 02:00:00.

       As an example of the previous format, if the TZ environment variable had the value EST5EDT4,M4.1.0,M10.5.0  it  would  describe	the  rule,
       which  went  into effect in 1987, for the Eastern time zone in the USA. Specifically, EST would be the designation for standard time, which
       is 5 hours behind GMT. EDT would be the designation for DST, which is 4 hours behind GMT. DST starts on the first Sunday in April and  ends
       on the last Sunday in October.  In both cases, since the time was not specified, the change to and from DST would occur at the default time
       of 2:00 AM.

       The call remains for compatibility reasons only; it is impossible to reliably map timezone's arguments (zone, a `minutes west of GMT' value
       and dst, a `daylight saving time in effect' flag) to a time zone abbreviation.

       If  the	environmental string TZNAME exists, returns its value, unless it consists of two comma separated strings, in which case the second
       string is returned if dst is non-zero, else the first string.  If TZNAME does not exist, zone is checked for equality with a built-in table
       of  values,  in which case returns the time zone or daylight time zone abbreviation associated with that value.	If the requested zone does
       not appear in the table, the difference from GMT is returned; that is, in Afghanistan, is appropriate because it is 4:30 ahead of GMT,  and
       the  string  `GMT+4:30'	is returned.  Programs that in the past used the function should return the zone name as set by to assure correct-
       ness.

   System V Environment Only
       If TZ appears in the environment its value specifies a pathname of a format file from which to read the time conversion information. If the
       pathname begins with a slash, it represents an absolute pathname; otherwise the pathname is relative to the system time conversion informa-
       tion directory

       If TZ appears in the environment and using the value as a pathname of a format file fails for any reason, the value  is	assumed  to  be  a
       three-letter  time  zone name followed by a number representing the difference between local time and GMT in hours, followed by an optional
       three-letter name for a time zone on DST.  For example, the setting for New Jersey would be EST5EDT.

   System V and POSIX Environment Only
       The external long variable contains the difference, in seconds, between GMT and local standard time (in EST,  is  5*60*60).   The  external
       variable  daylight  is nonzero if any daylight time rules are to be applied (that is, if the specified timezone includes rules for daylight
       time).  These variables are set whenever or are called.

Restrictions
       The return values point to static data whose content is overwritten by each call.  The tm_zone field of a returned struct tm  points  to  a
       static array of characters, which will also be overwritten at the next call (and by calls to

Files
       /etc/zoneinfo		time zone information directory
       /etc/zoneinfo/localtime	local time zone file

See Also
       gettimeofday(2), getenv(3), strftime(3), time(3), tzfile(5), environ(7)

																	  ctime(3)