6.22.13 time Function

Calculates the current calendar time.

Attention: Although implemented by MPLAB XC8 for PIC, this function will always return -1 to indicate that the calendar time is not available for 8-bit PIC devices.

Include

<time.h>

Prototype

time_t time(time_t * tod);

Argument

tod: pointer to storage location for time

Return Value

Returns the calendar time encoded as a value of time_t.

Remarks

If the pointer argument is not NULL, the time value is written to the address held by this pointer.

If the target environment cannot determine the time, the function returns -1 cast as a time_t. By default, the compiler returns the time as instruction cycles.

When using MPLAB XC16 or XC-DSC, this function uses the device Timer2 and Timer3 to compute the current time.

When using MPLAB XC8 for AVR devices, this function returns 0 by default. User code can call set_system_time() at program startup to initialize the system clock, can call system_tick() to increment the clock (typically performed using a timer interrupt), and then call time() to obtain the time value. See the avr/avr/include/sys/time.h source file for further information.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

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

volatile int i;

int main(void)
{
  time_t ticks;

  time(0); /* start time */
  for (i = 0; i < 10; i++) /* waste time */
    continue;
  time(&ticks); /* get time */
  printf("Time = %ld\n", ticks);
}

Example Output

Time = 256