'\" te
.\" Copyright (c) 2016, Oracle and/or its       affiliates. All rights reserved.
.TH get_hrusec 3C "19 May 2016" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
get_hrusec, get_sec_fromepoch, get_nsec_fromepoch \- timestamp for interval measurements
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/system_stats.h>

void get_hrusec(hrtime_t *usec);

void get_sec_fromepoch(memtime_sec_t *sec);

void get_nsec_fromepoch(hrtime_t *nsec);
.fi

.SH DESCRIPTION
.sp
.LP
These functions are provided for performance reasons. The overhead of reading time using these functions is minimum as they return time read from memory. No system calls are involved in \fBget_*\fR functions.
.sp
.LP
The \fBget_hrusec()\fR function returns high-resolution real time which is expressed as microseconds since some arbitrary time in the past. It is not correlated in any way to the time of day, and thus is not subject to resetting or drifting by way of \fBadjtime\fR(2) or \fBsettimeofday\fR(3C). This high-resolution time is suited for performance measurement. Although the best time accuracy it gives is 1 millisecond unlike \fBgethrtime\fR(3C).
.sp
.LP
The \fBget_sec_fromepoch()\fR and \fBget_nsec_fromepoch()\fR functions return time expressed in elapsed seconds from \fBepoch\fR(January 1, 1970) and elapsed nanoseconds from \fBepoch\fR respectively. Time returned by both these functions are subject to setting or drifting by \fBadjtime\fR(2) or \fBsettimeofday\fR(3C) calls. Note that the accuracy of \fBnsecs\fR returned by \fBget_nsec_fromepoch()\fR is 1 millisecond.
.SH EXAMPLES
.LP
\fBExample 1 \fRTimestamping using \fBget_hrusec()\fR, \fBget_sec_fromepoch()\fR, and \fBget_nsec_fromepoch()\fR:
.sp
.in +2
.nf
#include <stdio.h>
#include <unistd.h>
#include <sys/system_stats.h>
#include <time.h>

void main() {
        hrtime_t hres1, hres2;
        memtime_sec_t   sec;

        get_hrusec(&hres1);
        sleep(1);
        get_hrusec(&hres2);

        printf("Slept for %lld microseconds\n",
            (hres2 - hres1));

        get_sec_fromepoch(&sec);
        printf("Current time in seconds : %lld\n",
            sec);

        get_nsec_fromepoch(&hres1);
        printf("Current time in nanoseconds: %lld\n",
            hres1);
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Architecture SPARC and x86
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE