From 96d951a401c65525bec0f973946b8dfb24afd670 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Thu, 2 Apr 2020 08:39:08 +0200
Subject: [PATCH] clock_nanosleep.2, timer_create.2, timerfd_create.2: Add
 various missing errors

Mostly verified by testing and reading the code.

There is unfortunately quite a bit of inconsistency across API~s:

                  clock_gettime  clock_settime  clock_nanosleep  timer_create  timerfd_create

CLOCK_BOOTTIME            y        n (EINVAL)     y                y             y
CLOCK_BOOTTIME_ALARM      y        n (EINVAL)     y [1]            y [1]         y [1]
CLOCK_MONOTONIC           y        n (EINVAL)     y                y             y
CLOCK_MONOTONIC_COARSE    y        n (EINVAL)     n (ENOTSUP)      n (ENOTSUP)   n (EINVAL)
CLOCK_MONOTONIC_RAW       y        n (EINVAL)     n (ENOTSUP)      n (ENOTSUP)   n (EINVAL)
CLOCK_REALTIME            y        y              y                y             y
CLOCK_REALTIME_ALARM      y        n (EINVAL)     y [1]            y [1]         y [1]
CLOCK_REALTIME_COARSE     y        n (EINVAL)     n (ENOTSUP)      n (ENOTSUP)   n (EINVAL)
CLOCK_TAI                 y        n (EINVAL)     y                y             n (EINVAL)
CLOCK_PROCESS_CPUTIME_ID  y        n (EINVAL)     y                y             n (EINVAL)
CLOCK_THREAD_CPUTIME_ID   y        n (EINVAL)     n (EINVAL [2])   y             n (EINVAL)
pthread_getcpuclockid()   y        n (EINVAL)     y                y             n (EINVAL)

[1] The caller must have CAP_WAKE_ALARM, or the error EPERM results.

[2] This error is generated in the glibc wrapper.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/clock_nanosleep.2 |  4 ++++
 man2/timer_create.2    | 14 ++++++++++++++
 man2/timerfd_create.2  | 10 ++++++++++
 3 files changed, 28 insertions(+)

diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
index 5070ccb41..7753db7d6 100644
--- a/man2/clock_nanosleep.2
+++ b/man2/clock_nanosleep.2
@@ -193,6 +193,10 @@ was invalid.
 .RB ( CLOCK_THREAD_CPUTIME_ID
 is not a permitted value for
 .IR clock_id .)
+.TP
+.B ENOTSUP
+The kernel does not support sleeping against this
+.IR clock_id .
 .SH VERSIONS
 The
 .BR clock_nanosleep ()
diff --git a/man2/timer_create.2 b/man2/timer_create.2
index fd366e6ea..8d9ce9c67 100644
--- a/man2/timer_create.2
+++ b/man2/timer_create.2
@@ -223,6 +223,20 @@ is invalid.
 .B ENOMEM
 .\" glibc layer: malloc()
 Could not allocate memory.
+.TP
+.B ENOTSUP
+The kernel does not support creating a timer against this
+.IR clockid .
+.TP
+.B EPERM
+.I clockid
+was
+.BR CLOCK_REALTIME_ALARM
+or
+,BR CLOCK_BOOTTIME_ALARM
+but the caller did not have the
+.BR CAP_WAKE_ALARM
+capability.
 .SH VERSIONS
 This system call is available since Linux 2.6.
 .SH CONFORMING TO
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index 4b336cff5..ec137fbfe 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -443,6 +443,16 @@ Could not mount (internal) anonymous inode device.
 .TP
 .B ENOMEM
 There was insufficient kernel memory to create the timer.
+.TP
+.B EPERM
+.I clockid
+was
+.BR CLOCK_REALTIME_ALARM
+or
+,BR CLOCK_BOOTTIME_ALARM
+but the caller did not have the
+.BR CAP_WAKE_ALARM
+capability.
 .PP
 .BR timerfd_settime ()
 and