Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 180 insertions, 0 deletions

diff --git a/man/man3/pthread_getcpuclockid.3 b/man/man3/pthread_getcpuclockid.3
new file mode 100644
index 0000000..7ad000d
--- /dev/null
+++ b/man/man3/pthread_getcpuclockid.3
@@ -0,0 +1,180 @@
+'\" t
+.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_getcpuclockid 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.B #include <time.h>
+.P
+.BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_getcpuclockid ()
+function obtains the ID of the CPU-time clock of the thread whose ID is
+given in
+.IR thread ,
+and returns it in the location pointed to by
+.IR clockid .
+.\" The clockid is constructed as follows:
+.\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
+.\" where CLOCK_IDFIELD_SIZE is 3.
+.SH RETURN VALUE
+On success, this function returns 0;
+on error, it returns a nonzero error number.
+.SH ERRORS
+.TP
+.B ENOENT
+.\" CLOCK_THREAD_CPUTIME_ID not defined
+Per-thread CPU time clocks are not supported by the system.
+.\"
+.\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
+.\" be possible if kernel thread IDs took more than 29 bits (which
+.\" they currently cannot).
+.TP
+.B ESRCH
+No thread with the ID
+.I thread
+could be found.
+.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 pthread_getcpuclockid ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.2.
+POSIX.1-2001.
+.SH NOTES
+When
+.I thread
+refers to the calling thread,
+this function returns an identifier that refers to the same clock
+manipulated by
+.BR clock_gettime (2)
+and
+.BR clock_settime (2)
+when given the clock ID
+.BR CLOCK_THREAD_CPUTIME_ID .
+.SH EXAMPLES
+The program below creates a thread and then uses
+.BR clock_gettime (2)
+to retrieve the total process CPU time,
+and the per-thread CPU time consumed by the two threads.
+The following shell session shows an example run:
+.P
+.in +4n
+.EX
+$ \fB./a.out\fP
+Main thread sleeping
+Subthread starting infinite loop
+Main thread consuming some CPU time...
+Process total CPU time:    1.368
+Main thread CPU time:      0.376
+Subthread CPU time:        0.992
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (pthread_getcpuclockid.c)
+.EX
+/* Link with "\-lrt" */
+\&
+#include <errno.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+\&
+#define handle_error(msg) \e
+        do { perror(msg); exit(EXIT_FAILURE); } while (0)
+\&
+#define handle_error_en(en, msg) \e
+        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
+\&
+static void *
+thread_start(void *arg)
+{
+    printf("Subthread starting infinite loop\en");
+    for (;;)
+        continue;
+}
+\&
+static void
+pclock(char *msg, clockid_t cid)
+{
+    struct timespec ts;
+\&
+    printf("%s", msg);
+    if (clock_gettime(cid, &ts) == \-1)
+        handle_error("clock_gettime");
+    printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+}
+\&
+int
+main(void)
+{
+    pthread_t thread;
+    clockid_t cid;
+    int s;
+\&
+    s = pthread_create(&thread, NULL, thread_start, NULL);
+    if (s != 0)
+        handle_error_en(s, "pthread_create");
+\&
+    printf("Main thread sleeping\en");
+    sleep(1);
+\&
+    printf("Main thread consuming some CPU time...\en");
+    for (unsigned int j = 0; j < 2000000; j++)
+        getppid();
+\&
+    pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
+\&
+    s = pthread_getcpuclockid(pthread_self(), &cid);
+    if (s != 0)
+        handle_error_en(s, "pthread_getcpuclockid");
+    pclock("Main thread CPU time:   ", cid);
+\&
+    /* The preceding 4 lines of code could have been replaced by:
+       pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */
+\&
+    s = pthread_getcpuclockid(thread, &cid);
+    if (s != 0)
+        handle_error_en(s, "pthread_getcpuclockid");
+    pclock("Subthread CPU time: 1    ", cid);
+\&
+    exit(EXIT_SUCCESS);         /* Terminates both threads */
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR clock_gettime (2),
+.BR clock_settime (2),
+.BR timer_create (2),
+.BR clock_getcpuclockid (3),
+.BR pthread_self (3),
+.BR pthreads (7),
+.BR time (7)