summaryrefslogtreecommitdiffstats
path: root/man/man3/clock_getcpuclockid.3
blob: 24884d06e3f36e54fa9dfbcf42572817d71b688e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
'\" 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 (unreleased)"
.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)