Netcruzer  V2.02
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
time.h File Reference

Standard C Libraries -. More...

Go to the source code of this file.

Data Structures

struct  tm
 

Macros

#define size_t
 
#define CLOCKS_PER_SEC
 

Functions

struct tm asctime (const struct tm *tptr)
 
clock_t clock (void)
 
char * ctime (const time_t *tod)
 
double difftime (time_t t1, time_t t0)
 
struct tmgmtime (const time_t *tod)
 
struct tmlocaltime (const time_t *tod)
 
time_t mktime (struct tm *tptr)
 

Variables

int tm_sec
 
int tm_min
 
int tm_hour
 
int tm_mday
 
int tm_mon
 
int tm_year
 
int tm_wday
 
int tm_yday
 
int tm_isdst
 

Detailed Description

Standard C Libraries -.

Compiler:
MPLAB XC16 compiler

Description

The header file, time.h, consists of types, macros and functions that manipulate time.

Software License Agreement

The documentation in this header file has been copied from the documentation provided with the Microchip MPLAB XC16 compiler. The original lincense agreement included with the XC16 compiler applies!

Macro Definition Documentation

#define size_t

Description: Stores processor time values.

Include: <time.h> Description: The type of the result of the sizeof operator.

Include: <time.h>

Function Documentation

struct tm asctime ( const struct tm tptr)

Description: Represents calendar time values.

Include: <time.h> Description: Number of processor clocks per second.

Include: <time.h>

Value: 1

Remarks:
The compiler returns clock ticks (instruction cycles) not actual time. Description: The value of a null pointer constant.

Include: <time.h> Description: Converts the time structure to a character string.

Include: <time.h>

Parameters
tptrtime/date structure
Returns
Returns a pointer to a character string of the following format: DDD MMM dd hh:mm:ss YYYY DDD is day of the week MMM is month of the year dd is day of the month hh is hour mm is minute ss is second YYYY is year

Example:

#include <time.h> // for asctime, tm
#include <stdio.h> // for printf
volatile int i;
int main(void) {
struct tm when;
time_t whattime;
when.tm_sec = 30;
when.tm_min = 30;
when.tm_hour = 2;
when.tm_mday = 1;
when.tm_mon = 1;
when.tm_year = 103;
whattime = mktime(&when);
printf("Day and time is %s\n", asctime(&when));
}

Output:
Day and time is Sat Feb 1 02:30:30 2003

clock_t clock ( void  )

Description: Calculates the processor time.

Include: <time.h>

Returns
Returns the number of clock ticks of elapsed processor time.

Remarks:
If the target environment cannot measure elapsed processor time, the function returns -1, cast as a clock_t. (i.e. (clock_t) -1).

By default, the 16-bit compiler returns the time as instruction cycles.

Example:

#include <time.h> // for clock
#include <stdio.h> // for printf
volatile int i;
int main(void) {
clock_t start, stop;
int ct;
start = clock();
for (i = 0; i < 10; i++)
stop = clock();
printf("start = %ld\n", start);
printf("stop = %ld\n", stop);
}

Output:
start = 0
stop = 317

char* ctime ( const time_t *  tod)

Description: Converts calendar time to a string representation of local time.

Include: <time.h>

Parameters
todpointer to stored time
Returns
Returns the address of a string that represents the local time of the parameter passed.

Remarks:
This function is equivalent to asctime(localtime(tod)).

Example:

#include <time.h> // for mktime, tm, ctime
#include <stdio.h> // for printf
int main(void) {
time_t whattime;
struct tm nowtime;
nowtime.tm_sec = 30;
nowtime.tm_min = 30;
nowtime.tm_hour = 2;
nowtime.tm_mday = 1;
nowtime.tm_mon = 1;
nowtime.tm_year = 103;
whattime = mktime(&nowtime);
printf("Day and time %s\n", ctime(&whattime));
}

Output:
Day and time Sat Feb 1 02:30:30 2003

double difftime ( time_t  t1,
time_t  t0 
)

Description: Find the difference between two times.

Include: <time.h>

Parameters
t1ending time
t0beginning time
Returns
Returns the number of seconds between t1 and t0.

Remarks:
By default, the 16-bit compiler returns the time as instruction cycles so difftime returns the number of ticks between t1 and t0.

Example:

#include <time.h> // for clock, difftime
#include <stdio.h> // for printf
volatile int i;
int main(void) {
clock_t start, stop;
double elapsed;
start = clock();
for (i = 0; i < 10; i++)
stop = clock();
printf("start = %ld\n", start);
printf("stop = %ld\n", stop);
elapsed = difftime(stop, start);
printf("Elapsed time = %.0f\n", elapsed);
}

Output:
start = 0
stop = 317
Elapsed time = 317

struct tm* gmtime ( const time_t *  tod)

Description: Converts calendar time to time structure expressed as Universal Time Coordinated (UTC) also known as Greenwich Mean Time (GMT).

Include: <time.h>

Parameters
todpointer to stored time
Returns
Returns the address of the time structure.

Remarks:
This function breaks down the tod value into the time structure of type tm. By default, the 16-bit compiler returns the time as instruction cycles. With this default, gmtime and localtime will be equivalent, except gmtime will return tm_isdst (Daylight Savings Time flag) as zero to indicate that Daylight Savings Time is not in effect.

Example:

#include <time.h> // for gmtime, asctime,
// time_t, tm
#include <stdio.h> // for printf
int main(void) {
time_t timer;
struct tm *newtime;
timer = 1066668182; // Mon Oct 20 16:43:02 2003
newtime = gmtime(&timer);
printf("UTC time = %s\n", asctime(newtime));
}

Output:
UTC time = Mon Oct 20 16:43:02 2003

struct tm* localtime ( const time_t *  tod)

Description: Converts a value to the local time.

Include: <time.h>

Parameters
todpointer to stored time
Returns
Returns the address of the time structure.

Remarks:
By default, the 16-bit compiler returns the time as instruction cycles. With this default, localtime and gmtime will be equivalent, except localtime will return tm_isdst (Daylight Savings Time flag) as -1 to indicate that the status of Daylight Savings Time is not known.

Example:

#include <time.h> // for localtime,
// asctime, time_t, tm
#include <stdio.h> // for printf
int main(void) {
time_t timer;
struct tm *newtime;
timer = 1066668182; // Mon Oct 20 16:43:02 2003
newtime = localtime(&timer);
printf("Local time = %s\n", asctime(newtime));
}

Output:
Local time = Mon Oct 20 16:43:02 2003

time_t mktime ( struct tm tptr)

Description: Converts local time to a calendar value.

Include: <time.h>

Parameters
tptra pointer to the time structure
Returns
Returns the calendar time encoded as a value of time_t.

Remarks:
If the calendar time cannot be represented, the function returns -1, cast as a time_t (i.e. (time_t) -1).

Example:

#include <time.h> // for localtime,
// asctime, mktime,
// time_t, tm
#include <stdio.h> // for printf
int main(void) {
time_t timer, whattime;
struct tm *newtime;
timer = 1066668182; // Mon Oct 20 16:43:02 2003
// localtime allocates space for struct tm
newtime = localtime(&timer);
printf("Local time = %s", asctime(newtime));
whattime = mktime(newtime);
printf("Calendar time as time_t = %ld\n",
whattime);
}

Output:
Local time = Mon Oct 20 16:43:02 2003
Calendar time as time_t = 1066668182