digitalmars.com                      
Last update Sun Mar 4 12:00:59 2018

time.h / utime.h

_daylight

Header
time.h
Prototype
extern int _daylight;
Description
This variable is used in the time functions. It is set to non-zero by _tzset if a daylight savings time zone is specified in the TZ environment variable, otherwise it is set to zero. The default is 1.
Synonym
Variable: daylight
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_tzset

difftime

Header
time.h
Prototype
double difftime(time_t time2, time_t time1);
Description
difftime subtracts time1 from time2 to calculate the time elapsed between time1 and time2. The value is calculated in seconds elapsed. The arguments are normally obtained by two calls to the time function.
Return Value
Returns the difference between time1 and time2 in seconds.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime clock ctime gmtime localtime mktime time
Example
/* Eample for difftime, time */
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 int count;
 time_t start, finish;

 time(&start);

 for (count = 1; count <= 5000; count++)
 {
   printf("%d\r", count);
 }

 time(&finish);

 printf("\nCounting to 5000 took %.2f seconds",
        difftime(finish, start));
}
Output
5000
Counting to 5000 took 3.00 seconds

_ftime

Header
sys\timeb.h
Prototype
void _ftime(struct _timeb *timeptr);
Description

The _ftime function gets the current time and copies it to the structure pointed to by the timeptr argument. Fields of the _timeb structure are:

Fields of _timeb
time The current time in seconds in time_t format.
millitm The current fraction of a second in milliseconds.
timezone The difference in minutes between local time and Greenwich Mean Time.
dstflag Nonzero if daylight savings time is currently in effect for this time zone.
Synonym
Function: ftime Structure: timeb
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime ctime time _tzset
Example
/* Example program for _ftime */

#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <sys\timeb.h>

void main()
{
 struct timeb t;

 putenv("TZ=PST8PDT");
 tzset();
 ftime(&t);
 printf("The difference between local time and GMT is %d minutes\n",
         t.timezone);
}
Output
The difference between local time and GMT is 480 minutes

_strdate

Header
time.h
Prototype
char *_strdate(char *datestr);
Description
The _strdate function converts the current date to a null-terminated string and stores it in the buffer pointed to by the datestr argument. The date string has the following format:

mm/dd/yy

where mm represents the month (01 for January), dd represents the day (01 for the first), and yy indicates the year (93 for 1993).

Return Value
A pointer to the date string.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_strtime time
Example
/* Example of _strdate, _strtime */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 char datestr[9], timestr[9];

 _strdate(datestr);
 _strtime(timestr);

 printf("The current date and time is %s on %s\n",
        timestr, datestr);
}
Output
The current date and time is 11:07:58 on 06/23/94

_timezone

Header
time.h
Prototype
extern long _timezone;
Description
This variable provides the difference in seconds between local time and Coordinated Universal Time. The default is 28, 000 seconds.
Synonym
Variable: timezone
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32

_tzname

Header
time.h
Prototype
extern char *_tzname[2];
Description
This variable is an array of two strings containing the following time zone names, whose string values are derived from the TZ environment variable:
tzname[0] Three-letter time zone name.
tzname[1] Three-letter daylight savings time zone name, or empty string if TZ omits daylight savings time zone.
Synonym
Variable: tzname
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32

_tzset

Header
time.h
Prototype
void _tzset(void);
Description
The _tzset function uses the current setting of the TZ environment variable to set global variables: _daylight, _timezone, and _tzname. These variables are used by the _ftime, localtime, and time functions.

To set the TZ environment variable from DOS, use the command:

set TZ=tzn[+|-]hh[:mm[:ss]]][dzn]
tzn represents a time zone, such as PST (Pacific Standard Time) or EST (Easter Standard Time).hh represents an offset, in hours, from the UTC (Coordinated Universal Time). The hours can be followed by minutes and seconds (mm and ss). The dzn represents daylight savings time zone, such as PDT (Pacific Daylight Time).

When _tzset is called, the following values are assigned to _daylight, _timezone, and _tzname:

_daylight receives a non-zero value if a daylight saving time zone is specified in the TZ variable; otherwise receives zero.
_timezone receives the difference, in seconds, between UTC and local time
_tzname receives the string value of the daylight-saving-time zone or an empty string if this zone is omitted.
Synonym
Function: tzset
Variables: timezone, daylight, tzname
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime _ftime localtime time
Example
/* Example program for _tzset */

#include <stdlib.h>
#include <stdio.h>
#include <time.h>

void main()
{
 time_t curtime;

 putenv("TZ=PST8PDT");
 tzset();
 time(&curtime);
 printf("Current time is %s\n",
         asctime(localtime(&curtime)));
}
Output
Current time is Fri Jun 24 15:04:49 1994

_utime

Header
sys\types.h
sys\utime.h
Prototype
int _utime(char *filename, struct _utimbuf *times);
Description
The _utime function changes the modified time associated with the file specified by the filename argument. The times argument contains the new time to be applied to the file.

The times argument is a pointer to a _utimbuf structure, defined in sys\utime.h as:

time_t actime;
time_t modtime;

Although the structure contains a field for access time, only the modification time is set with DOS.

If the times argument is NULL, the current time will be used.

Return Value
_utime returns a 0 on success. If an error occurrs, -1 is returned and errno is set to EACCES (path name specifies directory or read-only file), EINVAL (invalid argument), EMFILE (too many open files), or ENOENT (file or path name not found).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
time
Example
/* Example for _utime */

#include <stdio.h>
#include <stdlib.h>
#include <sys\utime.h>

void main(int argc, char *argv[])
{
 if (argc != 2)
 {
    printf("Usage: _utime [filename.ext]\n");
    exit(EXIT_FAILURE);
 }
 if (_utime(argv[1], NULL) == -1)
 {
    perror("Unable to update file");
    exit(EXIT_FAILURE);
 }
}
Output
C:\DM\EXAMPLES> dir _utime.exe

Volume in drive C is DIGIMARS
Volume Serial Number is 1CD4-5ECB
Directory of C:\DM\EXAMPLES

_UTIME EXE              14,084  06-27-94 11:02a

        1 file(s)               14,084 bytes
                           100,917,248 bytes free

C:\DM\EXAMPLES> _utime _utime.exe

C:\DM\EXAMPLES> dir _utime.exe

Volume in drive C is DIGIMARS
Volume Serial Number is 1CD4-5ECB
Directory of C:\DM\EXAMPLES

_UTIME EXE              14,084  06-27-94 11:10a

        1 file(s)               14,084 bytes
                           100,917,248 bytes free

asctime

Header
time.h
Prototype
char *asctime(const struct tm *ntime);
Description
asctime converts a time structure into an ASCII string of 26
characters including the null having the form of:

DDD MMM dd hh:mm:ss YYYY\n\0

Where... represents...
DDD day of the week
MMM month
dd day of the month
hh:mm:ss hour:minutes:seconds
YYYY year

The method of obtaining the time is to first call the time function to get the number of seconds elapsed since 00:00:00 GMT on January 1, 1968. This is passed as an argument to the localtime function which returns a pointer to the structure tm as defined in time.h. This is then used as the ntime argument to asctime.

Return Value
Returns a pointer to a character string containing the date and time. The string is static and is overwritten with each call to asctime.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
clock ctime difftime localtime
Example
/* Example of asctime, localtime */
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 time_t encoded_time;
 struct tm *decoded_time;
 char* time_string;

 encoded_time = time(NULL);
 decoded_time = localtime(&encoded_time);
 time_string = asctime(decoded_time);

 printf ("Current date and time: %s\n",
          time_string);
}
Output
The output will be similar to: 
Current date and time: Mon Jun 20 14:26:25 1994

clock

Header
time.h
Prototype
clock_t clock(void)
Description
The clock function determines the time elapsed since the calling program started, in hundreths of a second. clock estimates the time elapsed using the system clock; it is only as accurate as the system clock. For example, the IBM PC timer granularity is 1/18th of a second, so the value returned by clock is accurate to 1/18th of a second despite a return value adjusted to hundreths of a second.
Return Value
A clock_t value representing the time, in 1/100ths of a second, used thus far by the calling program, where clock_t is a long integer. Divide the return value by the constant CLOCKS_PER_SEC to estimate the time elapsed in seconds. If the processor time used is unavailable or unrepresentable, -1 is returned.
See Also
asctime ctime difftime localtime
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for clock */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 clock_t time_elapsed;
 float time_in_seconds;
 int count;

 for (count = 1; count <= 5000; count++)
 {
    printf("%d\r", count);
 }
 time_elapsed = clock();
 time_in_seconds = (float)time_elapsed /
                    CLOCKS_PER_SEC;
 printf("\nclock() returned %ld after
         counting to 5000\n", time_elapsed);
 printf("which is %. 2f seconds\n",
         time_in_seconds);
}
Output
5000
clock() returned 2530 after counting to 5000
which is 2.53 seconds

ctime

Header
time.h
Prototype
char *ctime(const time_t *ntime);
Description
Converts the calendar time (type time_t) pointed to by ntime to local time in the form of an ASCII string. It is equivalent to the function call asctime(localtime(ntime)). The time_t value ntime is normally obtained by a call to the time function, which returns the time elapsed since 00:00:00 on January 1, 1968.
Return Value
Returns pointer to a static ASCII string of 26 characters. The string will be overwritten by each call to ctime. The string's form is: 
DDD MMM dd hh:mm:ss YYYY\n\0
Where:
DDD day of the week
MMM month
dd day of the month
hh:mm:ss hour:minutes:seconds
YYYY year
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime clock difftime localtime
Example
/* Example for ctime */
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
  time_t encoded_time;
  char *time_string;

  time(&encoded_time);
  time_string = ctime(&encoded_time);
  printf("The current date and time: %s\n",
         time_string);
}
Output
The current date and time: Tue Jun 21 15:27:23 1994

gmtime

Header
time.h
Prototype
struct tm *gmtime(const time_t *timer);
Description
The gmtime function converts the value pointed to by argument timer to a structure, tm. The timer value is the time in seconds elapsed since midnight, January 1, 1968 (UTC).

The tm structure stores the timer value in the following int fields:

Field Value
tm_sec Seconds
tm_min Minutes
tm_hour Hours (0-23)
tm_mday Day of month (1-31)
tm_mon Month (0-11; January = 0)
tm_year Year (current year minus 1900)
tm_wday Day of week (0-6; Sunday = 0)
tm_yday Day of year (0-365; January 1 = 0)
tm_isdst Always 0 for gmtime
Return Value
A pointer to the structure. Returns NULL if timer is before midnight, January 1, 1968 UTC.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime ctime _ftime localtime mktime time
Example
/* Example for gmtime, localtime */

#include <time.h>
#include <stdio.h>

void main()
{
  time_t the_time;

  time(&the_time);
  printf("Coordinated Universal Time is %s\n",
          asctime(gmtime(&the_time)));
  printf("Local Time is %s\n",
          asctime(localtime(&the_time)));
}
Output
Coordinated Universal Time is Thu Jun 23 23:40:07 1994
Local Time is Thu Jun 23 16:40:07 1994

localtime

Header
time.h
Prototype
struct tm *localtime(time_t *stime);
Description
localtime converts a time stored as a time_t value to the structure tm. The time_t value stime is the seconds elapsed since 00:00:00 on January 1, 1968. This value can be obtained from the function time. localtime makes corrections for time zones and possible daylight savings time. The fields of the structure tm are:
int tm_sec seconds 0.. 59
int tm_min minutes 0.. 59
int tm_hour hour of day 0.. 23
int tm_mday day of month 1.. 31
int tm_mon month 0.. 11
int tm_year years since 1900
int tm_wday day of week, 0.. 6 (Sun.. Sat)
int tm_yday day of year, 0.. 365
int tm_isdst > 0 if daylight savings time, == 0 if not DST, < 0 don't know
Return Value
localtime returns a pointer to a static structure tm which is overwritten by each call to localtime.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
time asctime ctime mktime

mktime

Header
time.h
Prototype
time_t mktime(struct tm *ntime);
Description
Converts from struct tm to time_t, then converts the time_t value back to struct tm form in ntime. This has the effect of filling in any missing fields in ntime.
Return Value
Time in seconds since 00:00:00 GMT on January 1, 1968 based on struct tm.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime ctime localtime time
Example
/* Example for mktime */

#include <time.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 struct tm ntime;
 time_t set;

 time(&set);
 ntime = *localtime(&set);
 printf("Seconds since 1 Jan 1968 is %ld\n",
        mktime(&ntime));
 printf("The time is %s\n",
        asctime(&ntime));
}
Output
Seconds since 1 Jan 1968 is 772236942
The time is Tue Jun 21 15:15:42 1994

msleep

Header
time.h
Prototype
void msleep(long milliseconds);
Description
Suspends execution of the program for the specified number of milliseconds. The granularity depends on the operating system.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
sleep usleep
Example
/* Example for msleep */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 printf("Going to sleep for 10 seconds\n");
 msleep(10000);
 printf("OK, back again now\n");
}
Output
Going to sleep for 10 seconds
OK, back again now

sleep

Header
time.h
Prototype
void sleep(time_t seconds);
Description
Suspends execution of a program for a specified number of seconds.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msleep usleep
Example
/* Example for sleep */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 printf("Going to sleep for 10 seconds\n");
 sleep(10);
 printf("OK, back again now\n");
}
Output
Going to sleep for 10 seconds
OK, back again now

strftime

Header
time.h
Prototype
size_t strftime(char *s, size_t max, const char *format, const struct tm *timeptr);
Description
strftime function inserts characters into the array pointed to by s, following instructions in the format string. The format should be a multi-byte character sequence, beginning and ending in its initial shift state.

The format string consists of zero or more conversion specifications as well as ordinary multibyte characters. A conversion specification consists of a % character followed by a character that determines the conversion to be applied. All ordinary multi-byte characters (including the terminating null character) are copied unchanged into the array. No more than max characters are placed into the array.

Each conversion specification is replaced by the appropriate characters, which are determined by the program's locale and by the values contained in the structure pointed to by timeptr. The following list shows how conversion specifications are replaced.

strftime conversion specifiers
This... is replaced by the...
%a Locale's abbreviated weekday name.
%A Locale's full weekday name.
%b Locale's abbreviated month name.
%B Locale's full month name.
%c Appropriate date and time representation.
%d Day of the month as a decimal number (01-31).
%H Hour (24-hour clock) as a decimal number (00-23).
%I Hour (12-hour clock) as a decimal number (00-12).
%j Day of the year as a decimal number (001-366).
%m Month as a decimal number (01-12).
%M Minute as a decimal number (00-59).
%p Locale's equivalent of either AM or PM.
%S Second as a decimal number (00-60).
%U Week number of the year, with Sunday taken as the first day of the week, as a decimal number (00-53).
%w Weekday as a decimal number (0(Sunday)-6).
%W Week number of the year, with Monday taken as the first day of the week, as a decimal number (00-53).
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year (without century) as a decimal number (00-99).
%Y Year (with century) as a decimal number.
%Z Time zone name or by no characters if no time zone is determinable.
%% %
Return Value
Returns the number of characters in the array pointed to by s, not including the terminating null character. If the total number of resulting characters, including the terminating null character, is greater than max, zero is returned, and the contents of the array become invalid.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
asctime ctime gmtime localtime mktime time
Example
/* Example of strftime */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 char dtstr[50];
 struct tm *tp;
 time_t curtime;

 time(&curtime);
 tp = localtime(&curtime);
 strftime(dtstr, sizeof(dtstr), "%I:%M:%S %p on %A, %B %d, %Y", tp);
 printf("The current time is: %s\n",
        dtstr);
}
Output
The current time is: 08:14:22 AM on Tuesday, June 28, 1994

time

Header
time.h
Prototype
time_t time(time_t *timeptr);
Description
time returns the current time in seconds elapsed since 00:00:00 GMT on January 1, 1968 and stores that value in *timeptr if timeptr is not NULL.
Return Value
time returns the number of seconds since 00:00:00 GMT on January 1, 1968. This is the same value stored in *timeptr, if it is not NULL.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
ctime asctime localtime mktime
Example
/* Example for time */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 time_t curtime;

 time(&curtime);
 printf("The time is: %s\n",
        ctime(&curtime));
}
Output
The time is: Fri Jun 24 11:55:55 1994

usleep

Header
time.h
Prototype
void usleep(unsigned long microseconds);
Description
usleep suspends execution of the program for the specified number of microseconds. The granularity depends on the operating system.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
sleep msleep
Example
/* Example for usleep */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

void main()
{
 printf("Going to sleep for 10 seconds\n");
 usleep(10000000);
 printf("OK, back again now\n");
}
Output
Going to sleep for 10 seconds
OK, back again now
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums