[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2

read_real_time or time_base_to_time Subroutine


Read the processor real time clock or time base registers to obtain high-resolution elapsed time.


Standard C Library (libc.a)


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

int read_real_time(timebasestruct_t *t,
                 size_t size_of_timebasestruct_t);

int time_base_to_time(timebasestruct_t *t,
                 size_t size_of_timebasestruct_t);


These subroutines are designed to be used for making high-resolution measurement of elapsed time, using the processor real time clock or time base registers. The read_real_time subroutine reads the value of the appropriate registers and stores them in a structure. The time_base_to_time subroutine converts time base data to real time, if necessary. This process is divided into two steps because the process of reading the time is usually part of the timed code, and so the conversion from time base to real time can be moved out of the timed code.

The read_real_time subroutine reads either the processor real time clock (for the POWER family or PowerPC 601 RISC Microprocessor) or the time base register (in the case of the POWER-based processors other than the PowerPC 601 RISC Microprocessor). The t argument is a pointer to a timebasestruct_t, where the time values are recorded.

After calling read_real_time, if running on a processor with a real time clock, t->tb_high and t->tb_low contain the current clock values (seconds and nanoseconds), and t->flag contains the RTC_POWER.

If running on a processor with a time base register, t->tb_high and t-tb_low contain the current values of the time base register, and t->flag contains RTC_POWER_PC.

The time_base_to_time subroutine converts time base information to real time, if necessary. It is recommended that applications unconditionally call the time_base_to_time subroutine rather than performing a check to see if it is necessary.

If t->flag is RTC_POWER, the subroutine simply returns (the data is already in real time format).

If t->flag is RTC_POWER_PC, the time base information in t->tb_high and t->tb_low is converted to seconds and nanoseconds; t->tb_high is replaced by the seconds; t->tb_low is replaced by the nanoseconds; and t->flag is changed to RTC_POWER.


t Points to a timebasestruct_t.

Return Values

The read_real_time subroutine returns RTC_POWER if the contents of the real time clock has been recorded in the timebasestruct, or returns RTC_POWER_PC if the content of the time base registers has been recorded in the timebasestruct.

The time_base_to_time subroutine returns 0 if the conversion to real time is successful (or not necessary), otherwise -1 is returned.


This example shows the time it takes for print_f to print the comment between the begin and end time codes:

#include <stdio.h>
#include <sys/time.h>
   timebasestruct_t start, finish;
   int val = 3;
   int secs, n_secs;
   /* get the time before the operation begins */
   read_real_time(&start, TIMEBASE_SZ);
   /* begin code to be timed */
   (void) printf("This is a sample line %d \n", val);
   /* end code to be timed   */
   /* get the time after the operation is complete */
   read_real_time(&finish, TIMEBASE_SZ);
    * Call the conversion routines unconditionally, to ensure
    * that both values are in seconds and nanoseconds regardless
    * of the hardware platform. 
   time_base_to_time(&start, TIMEBASE_SZ);
   time_base_to_time(&finish, TIMEBASE_SZ);
   /* subtract the starting time from the ending time */
   secs = finish.tb_high - start.tb_high;
   n_secs = finish.tb_low - start.tb_low;
   * If there was a carry from low-order to high-order during 
   * the measurement, we may have to undo it. 
   if (n_secs < 0)  {
      n_secs += 1000000000;
   (void) printf("Sample time was %d seconds %d nanoseconds\n",
                secs, n_secs);

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The gettimer, settimer, restimer, stime, or time subroutines, getrusage, times, or vtimes subroutines.

High-Resolution Time Measurements Using POWER-based Time Base or POWER family Real-Time Clock in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]