Calendar Time Under Linux

The system calendar time

The Linux kernel maintains a system calendar time, which is initialized from the hardware real time clock (RTC) at the boot time and is incremented with the timer interrupt. The system calendar time is the number of seconds passed since January 1, 1970 00:00:00 UTC, or, to put it differently, is the number of seconds since 1969. January 1, 1970 00:00:00 UTC is the Epoch for time keeping in Linux. After the system calendar time has been initialized from the hardware clock, it is used for all purposes and the hardware clock is not used during the system uptime.

date command

The system calendar time can be read or set using the date command,

$ date
Sun Oct 16 19:48:10 IST 2011
$ sudo date 101621012011.34
Sun Oct 16 21:01:34 IST 2011

time system call

Programs can find the system calendar time using the time system call. For example,

#include <time.h>

time_t ts;
if ((ts = time (NULL)) == -1)
    perror ("time");

After that, the variable, ts, contains the system calendar time at the instant the time system call was made.

Local time

There are many functions to convert the system calendar time, which is the number of seconds since 1969 to human readable local time string giving the day of the month, month, year, hours, minutes, seconds, day of the week and the local timezone. For instance, there is the struct tm in the include file time.h,

struct tm {
    int tm_sec;      /* Seconds. [0-60] (1 leap second) */
    int tm_min;      /* Minutes. [0-59] */
    int tm_hour;      /* Hours. [0-23] */
    int tm_mday;      /* Day. [1-31] */
    int tm_mon;      /* Month. [0-11] */
    int tm_year;      /* Year - 1900. */
    int tm_wday;      /* Day of week. [0-6] */
    int tm_yday;      /* Days in year.[0-365] */
    int tm_isdst;      /* DST. */

#ifdef __USE_BSD
     long int tm_gmtoff; /* Seconds east of UTC. */
     __const char *tm_zone; /* Timezone abbreviation. */
     long int __tm_gmtoff; /* Seconds east of UTC. */
     __const char *__tm_zone; /* Timezone abbreviation. */

One way of printing the local time is to use the above structure, tm,

struct tm *tms;
time_t ts;

if ((ts = time (NULL)) == -1)
    perror ("time");

if ((tms = localtime (&ts)) == NULL)
    perror ("localtime");

printf ("Time is %d/%02d/%d %d:%02d:%02d %s\n", tms -> tm_mday,
    tms -> tm_mon + 1, tms -> tm_year + 1900, tms -> tm_hour,
    tms -> tm_min, tms -> tm_sec, tms -> tm_zone);

The above program segment prints a string like,

Time is 17/10/2011 16:21:19 IST

There is a function ctime, which converts the system clock time stamp into a local time string.

time_t ts;
if ((ts = time (NULL)) == -1)
    perror ("time");
printf ("%s", ctime (&ts));

This prints a string like,

gettimeofday system call

The above examples give calendar time to the resolution of a second. However, it is possible to get the system time with microsecond resolution with the gettimeofday system call. There is a structure, timeval,

struct timeval {
    time_t tv_sec; /* seconds */
    suseconds_t tv_usec; /* microseconds */

which has seconds and microseconds as members. We get the system calendar time in terms of seconds and microseconds since the Epoch with the gettimeofday system call. The syntax of the call is,

#include <sys/time.h>

int gettimeofday (struct timeval *tv, NULL);

For example, we can get time since Epoch using gettimeofday and convert it into local time using localtime,

#include <time.h>
#include <sys/time.h>

struct timeval tval;
struct tm *tms;

if (gettimeofday (&tval, NULL) == -1)
perror ("gettimeofday");

printf ("%ld %ld\n", tval.tv_sec, tval.tv_usec);

if ((tms = localtime (&tval.tv_sec)) == NULL)
perror ("localtime");

printf ("Time is %d/%02d/%d %d:%02d:%02d.%03ld.%03ld %s\n",
tms -> tm_mday, tms -> tm_mon + 1, tms -> tm_year + 1900,
tms -> tm_hour, tms -> tm_min, tms -> tm_sec, tval.tv_usec / 1000,
tval.tv_usec % 1000, tms -> tm_zone);

The above code prints an output like,

Time is 17/10/2011 23:31:24.080.623 IST

See also

  1. Linux process execution time
  2. Alarm, sleep and High Resolution Timers
  3. hwclock, the hardware clock query and set program
  4. Synchronize your computer's clock using the NTP