function
<ctime>

time

time_t time (time_t* timer);
Get current time
Get the current calendar time as a value of type time_t.

The function returns this value, and if the argument is not a null pointer, it also sets this value to the object pointed by timer.

The value returned generally represents the number of seconds since 00:00 hours, Jan 1, 1970 UTC (i.e., the current unix timestamp). Although libraries may use a different representation of time: Portable programs should not use the value returned by this function directly, but always rely on calls to other elements of the standard library to translate them to portable types (such as localtime, gmtime or difftime).

Parameters

timer
Pointer to an object of type time_t, where the time value is stored.
Alternatively, this parameter can be a null pointer, in which case the parameter is not used (the function still returns a value of type time_t with the result).

Return Value

The current calendar time as a time_t object.

If the argument is not a null pointer, the return value is the same as the one stored in the location pointed by argument timer.

If the function could not retrieve the calendar time, it returns a value of -1.

time_t is an alias of a fundamental arithmetic type capable of representing times.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/* time example */
#include <stdio.h>      /* printf */
#include <time.h>       /* time_t, struct tm, difftime, time, mktime */

int main ()
{
  time_t timer;
  struct tm y2k = {0};
  double seconds;

  y2k.tm_hour = 0;   y2k.tm_min = 0; y2k.tm_sec = 0;
  y2k.tm_year = 100; y2k.tm_mon = 0; y2k.tm_mday = 1;

  time(&timer);  /* get current time; same as: timer = time(NULL)  */

  seconds = difftime(timer,mktime(&y2k));

  printf ("%.f seconds since January 1, 2000 in the current timezone", seconds);

  return 0;
}

Possible output:
414086872 seconds since January 1, 2000 in the current timezone


Data races

The object pointed by timer is modified (if not null).

Exceptions (C++)

No-throw guarantee: this function never throws exceptions.

See also