-rw-r--r-- 2187 libcpucycles-20240114/doc/man/cpucycles.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "cpucycles" "3" "" "" ""
.hy
.SS NAME
.PP
cpucycles - count CPU cycles
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <cpucycles.h>

long long count = cpucycles();
long long persecond = cpucycles_persecond();
const char *implementation = cpucycles_implementation();
const char *version = cpucycles_version();
\f[R]
.fi
.PP
Link with \f[V]-lcpucycles\f[R].
Old systems may also need \f[V]-lrt\f[R].
.SS DESCRIPTION
.PP
\f[V]cpucycles()\f[R] returns an estimate for the number of CPU cycles
that have occurred since an unspecified time in the past (perhaps system
boot, perhaps program startup).
.PP
Accessing true cycle counters can be difficult on some CPUs and
operating systems.
\f[V]cpucycles()\f[R] does its best to produce accurate results, but
selects a low-precision counter if the only other option is failure.
.PP
\f[V]cpucycles_persecond()\f[R] returns an estimate for the number of
CPU cycles per second.
This estimate comes from \f[V]/etc/cpucyclespersecond\f[R] if that file
exists, otherwise from various OS mechanisms, otherwise from the
\f[V]cpucyclespersecond\f[R] environment variable if that is set,
otherwise 2399987654.
.PP
\f[V]cpucycles_implementation()\f[R] returns the name of the counter in
use: e.g., \f[V]\[dq]amd64-pmc\[dq]\f[R].
.PP
\f[V]cpucycles_version()\f[R] returns the \f[V]libcpucycles\f[R] version
number as a string: e.g., \f[V]\[dq]20240114\[dq]\f[R].
Results of \f[V]cpucycles_implementation()\f[R] should be interpreted
relative to \f[V]cpucycles_version()\f[R].
.PP
\f[V]cpucycles\f[R] is actually a function pointer.
The first call to \f[V]cpucycles()\f[R] or
\f[V]cpucycles_persecond()\f[R] or \f[V]cpucycles_implementation()\f[R]
selects one of the available counters and updates the
\f[V]cpucycles\f[R] pointer accordingly.
Subsequent calls to \f[V]cpucycles()\f[R] are thread-safe.
.SS SEE ALSO
.PP
\f[B]gettimeofday\f[R](2), \f[B]clock_gettime\f[R](2)