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 tm *	gmtime (const time_t *tod)
struct tm *	localtime (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

tptr	time/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

tod	pointer 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

t1	ending time
t0	beginning 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

tod	pointer 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

tod	pointer 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

tptr	a 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