time.h / utime.h

• _daylight
• difftime
• _ftime
• _strdate
• _timezone
• _tzname
• _tzset
• _utime
• asctime
• clock
• ctime
• gmtime
• localtime
• mktime
• msleep
• sleep
• strftime
• time
• usleep

_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

/* 	Example for difftime 
	Also demonstrates 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:

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 
	Also demonstrates _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:\DMC\EXAMPLES> dir _utime.exe 

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

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

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

C:\DMC\EXAMPLES> _utime _utime.exe 

C:\DMC\EXAMPLES> dir _utime.exe 

Volume in drive C is DIGIMARS 
Volume Serial Number is 1CD4-5ECB 
Directory of C:\DMC\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 
	Also demonstrates 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 
	Also demonstrates 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:

struct tm { 
    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.

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