POSIX CLOCKS and TIMERS

SO -- cra

Clock Functions The supported time-of-day clock is the CLOCK_REALTIME clock. § systemwide clock, visible to all processes. § measures the amount of time that has elapsed since 00:00:00 January 1, 1970 Greenwich Mean Time (GMT). § measures time in nanoseconds;

SO -- cra

1

Clock Functions Function

Description

clock_getres

Returns the resolution of the specified clock

clock_gettime

Returns the current value for the specified clock

clock_settime

Sets the specified clock to the specified value

Use the name CLOCK_REALTIME as the clock_id argument in all P1003.1b clock functions.

SO -- cra

The following example calls the clock_getres function to determine clock resolution: #include #include main() { struct timespec clock_resolution; int stat; stat = clock_getres(CLOCK_REALTIME, &clock_resolution); printf("Clock resolution is %d seconds, %ld nanoseconds\n", clock_resolution.tv_sec, clock_resolution.tv_nsec); } SO -- cra

2

Retrieving System Time time and clock_gettime functions return the value of the systemwide clock.

time returns a long integer containing the number of seconds that have elapsed since the Epoch.

clock_gettime receives a pointer to a timespec structure and returns both the number of seconds and the value of the number of elapsed nanoseconds not comprising a full second (tv_sec and tv_nsec members).

SO -- cra

Example: Returning Time #include #include main() { struct timespec ts;

printf("time returns %d seconds\n", time(NULL);) /* Call time */ clock_gettime(CLOCK_REALTIME, &ts); /* Call clock_gettime */ printf("clock_gettime returns:\n"); printf("%d seconds and %ld nanoseconds\n", ts.tv_sec, ts.tv_nsec); } SO -- cra

3

Setting the Clock The clock_settime function lets you set the time for the specified clock. If you have an application that monitors time over the network use the clock_settime function to synchronize with other systems. However, under normal circumstances you would not need to call the clock_settime function.

SO -- cra

Converting Time Values Realtime clock and timer functions use the number of seconds and nanoseconds since the Epoch. Although this method is precise and suitable for the machine, it is not meaningful for application users.

The C language provides a number of functions to convert and store time in both a tm structure and an ASCII format. Note that although these C routines use seconds as the smallest unit of time, they provide users with a readable format.

SO -- cra

4

Date and Time Conversion Functions C Function

Description

asctime Converts time units (hours, minutes, and seconds) into a 26-character string ctime

Converts a time in seconds since the Epoch to an ASCII string in the form generated by asctime

difftime Computes the difference between two calendar times (time1–time0) and returns the difference expressed in seconds

gmtime Converts a calendar time into time units, expressed as GMT localtime Converts a time in seconds since the Epoch into time units mktime Converts the time units in the tm structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by time

tzset

Sets the external variable tzname, which contains current time zone names

SO -- cra

The converted time values are placed in a time structure (tm) defined in the time.h header file, as follows: struct tm { int tm_sec, /* Time in seconds (0-59) */ tm_min, /* Time in minutes (0-59) */ tm_hour, /* Time in hours (0-23) */ tm_mday, /* Day of the month (1 to 31) */ tm_mon, /* Month (0 to 11) */ tm_year, /* Year (last 2 digits) */ tm_wday, /* Day of the week (Sunday=0) */ tm_yday, /* Day of the year (0 to 365) */ tm_isdst; /* Daylight savings time (always 0) */ long tm_gmtoff; /* Offset from GMT in seconds */ char *tm_zone /* Time zone */ }; SO -- cra

5

Types of Timers Two types of timers are provided to support realtime timing facilities: § one-shot timers § periodic timers

A one-shot timer is armed with an initial expiration time, expires only once, and then is disarmed.

A timer becomes a periodic timer with the addition of a repetition value. The timer expires, then loads the repetition interval, rearming the timer to expire after the repetition interval has elapsed.

SO -- cra

Timers and Signals You create a timer with the timer_create function, which is associated with a sigevent structure. When using timers, you specify an initial expiration value and an interval value. When the timer expires, the system sends the specified signal to the process that created the timer. Therefore, you should set up a signal handler to catch the signal after it is sent to the calling process.

To use signals with timers, include the following steps in your application: 1. Create and declare a signal handler. 2. Set the sigevent structure to specify the signal you want sent on timer expiration. 3. Establish a signal handler with the sigaction function. 4. Create the timer.

SO -- cra

6

The timespec data structure typedef struct timespec { time_t tv_sec; /* Seconds */ long tv_nsec; /* Nanoseconds */ } timespec_t;

The itimerspec data structure consists of two timespec structures and takes the following form: struct itimerspec { struct timespec it_interval; /* Timer interval */ struct timespec it_value; /* Initial expiration */ };

SO -- cra

Values Used in Setting Timers

Member

Zero

Non-Zero

it_value

No expiration value

Expiration value

Disarm the timer

Arm the timer

No reload value

Interval reload value

One-shot timer

Periodic timer

it_interval

SO -- cra

7

The sigevent data structure The evp argument of the timer_create function points to a sigevent structure, which contains the signal to be sent upon expiration of each timer. The sigevent structure is defined in the signal.h header file and contains the following members: union sigval sigev_value;

/* Application-defined value */

int sigev_signo;

/* Signal to raise */

int sigev_notify;

/* Notification type */

The sigval union contains at least the following members: int sival_int;

/* Used when sigev_value is of type int */

void *sival_ptr;

/* Used when sigev_value is of type ptr */

The sigev_value member is an application-defined value to be passed to the signal-catching function at the time of signal delivery. SO -- cra

Timer Functions Function

Definition

timer_create

Returns a unique timer ID used in subsequent calls to identify a timer based on the systemwide clock

timer_delete

Removes a previously allocated, specified timer

timer_getoverrun Returns the timer expiration overrun count for the specified timer timer_gettime

Returns the amount of time before the specified timer is due to expire and the repetition value

timer_settime

Sets the value of the specified timer either to an offset from the current clock setting or to an absolute value

SO -- cra

8