'\" t
.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH clock_getcpuclockid 3 2024-05-02 "Linux man-pages 6.8"
.SH NAME
clock_getcpuclockid \- obtain ID of a process CPU-time clock
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc ),
since glibc 2.17
.P
Before glibc 2.17,
Real-time library
.RI ( librt ", " \-lrt )
.SH SYNOPSIS
.B #include <time.h>
.nf
.P
.BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clockid );
.fi
.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR clock_getcpuclockid ():
.nf
    _POSIX_C_SOURCE >= 200112L
.fi
.SH DESCRIPTION
The
.BR clock_getcpuclockid ()
function obtains the ID of the CPU-time clock of the process whose ID is
.IR pid ,
and returns it in the location pointed to by
.IR clockid .
If
.I pid
is zero, then the clock ID of the CPU-time clock
of the calling process is returned.
.SH RETURN VALUE
On success,
.BR clock_getcpuclockid ()
returns 0;
on error, it returns one of the positive error numbers listed in ERRORS.
.SH ERRORS
.TP
.B ENOSYS
The kernel does not support obtaining the per-process
CPU-time clock of another process, and
.I pid
does not specify the calling process.
.TP
.B EPERM
The caller does not have permission to access
the CPU-time clock of the process specified by
.IR pid .
(Specified in POSIX.1-2001;
does not occur on Linux unless the kernel does not support
obtaining the per-process CPU-time clock of another process.)
.TP
.B ESRCH
There is no process with the ID
.IR pid .
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR clock_getcpuclockid ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
glibc 2.2.
POSIX.1-2001.
.SH NOTES
Calling
.BR clock_gettime (2)
with the clock ID obtained by a call to
.BR clock_getcpuclockid ()
with a
.I pid
of 0,
is the same as using the clock ID
.BR CLOCK_PROCESS_CPUTIME_ID .
.SH EXAMPLES
The example program below obtains the
CPU-time clock ID of the process whose ID is given on the command line,
and then uses
.BR clock_gettime (2)
to obtain the time on that clock.
An example run is the following:
.P
.in +4n
.EX
.RB "$" " ./a.out 1" "                 # Show CPU clock of init process"
CPU\-time clock for PID 1 is 2.213466748 seconds
.EE
.in
.SS Program source
\&
.\" SRC BEGIN (clock_getcpuclockid.c)
.EX
#define _XOPEN_SOURCE 600
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
\&
int
main(int argc, char *argv[])
{
    clockid_t clockid;
    struct timespec ts;
\&
    if (argc != 2) {
        fprintf(stderr, "%s <process\-ID>\en", argv[0]);
        exit(EXIT_FAILURE);
    }
\&
    if (clock_getcpuclockid(atoi(argv[1]), &clockid) != 0) {
        perror("clock_getcpuclockid");
        exit(EXIT_FAILURE);
    }
\&
    if (clock_gettime(clockid, &ts) == \-1) {
        perror("clock_gettime");
        exit(EXIT_FAILURE);
    }
\&
    printf("CPU\-time clock for PID %s is %jd.%09ld seconds\en",
           argv[1], (intmax_t) ts.tv_sec, ts.tv_nsec);
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.BR clock_getres (2),
.BR timer_create (2),
.BR pthread_getcpuclockid (3),
.BR time (7)