* [PATCH] [man-pages] adjtimex.2: document clock_adjtime @ 2017-11-20 22:53 Arnd Bergmann 2017-11-21 3:05 ` Richard Cochran 0 siblings, 1 reply; 11+ messages in thread From: Arnd Bergmann @ 2017-11-20 22:53 UTC (permalink / raw) To: Michael Kerrisk Cc: linux-kernel-u79uwXL29TY76Z2rM5mHXA, linux-api-u79uwXL29TY76Z2rM5mHXA, John Stultz, Thomas Gleixner, Stephen Boyd, Richard Cochran, Arnd Bergmann I was experimenting with some possible changes to adjtimex(2) and clock_adjtime(2) and tried to look up the man page to see what the documented behavior is when I noticed that clock_adjtime() appears to be the only system call that is currently undocumented. Before I do any changes to it, this tries to document what I understand it currently does. Signed-off-by: Arnd Bergmann <arnd-r2nGTMty4D4@public.gmane.org> --- This is my first patch to man-pages, I'm just guessing about what should be in there and how to format it, please reword or reformat as necessary. --- man2/adjtimex.2 | 25 +++++++++++++++++++++++-- man2/clock_adjtime.2 | 1 + 2 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 man2/clock_adjtime.2 diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index fc6892d..b7c0a5f 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -35,6 +35,8 @@ adjtimex, ntp_adjtime \- tune kernel clock .PP .BI "int adjtimex(struct timex *" "buf" ); .PP +.BI "int clock_adjtimex(clockid_t " clk_id, " struct timex *" "buf" ); +.PP .BI "int ntp_adjtime(struct timex *" buf ); .fi .SH DESCRIPTION @@ -344,6 +346,12 @@ Attempts to set read-only .I status bits are silently ignored. .\" +.SS clock_adjtime () +The +.BR clock_adjtime () +system call (added in Linux 2.6.39) behaves like adjtimex() but takes an additional +.IR clk_id +argument to specify the particular clock on which to act. .SS ntp_adjtime () The .BR ntp_adjtime () @@ -472,6 +480,11 @@ An attempt was made to set to a value other than those listed above. .TP .B EINVAL +The +.I clk_id +specified is not supported on this system. +.TP +.B EINVAL An attempt was made to set .I buf.tick to a value outside the range @@ -482,6 +495,10 @@ where .B HZ is the system timer interrupt frequency. .TP +.B EOPNOTSUPP +.I clk_id +does not support adjustment +.TP .B EPERM .I buf.modes is neither 0 nor @@ -503,10 +520,12 @@ T{ T} Thread safety MT-Safe .TE .SH CONFORMING TO -Neither of these interfaces is described in POSIX.1 +None of these interfaces is described in POSIX.1 .PP .BR adjtimex () -is Linux-specific and should not be used in programs +and +.BR clock_adjtimex () +are Linux-specific and should not be used in programs intended to be portable. .PP The preferred API for the NTP daemon is @@ -533,6 +552,8 @@ is done by the kernel in timer context Thus, it will take one tick into the second for the leap second to be inserted or deleted. .SH SEE ALSO +.BR clock_gettime (2) +.BR clock_settime (2) .BR settimeofday (2), .BR adjtime (3), .BR ntp_gettime (3), diff --git a/man2/clock_adjtime.2 b/man2/clock_adjtime.2 new file mode 100644 index 0000000..b08b9c8 --- /dev/null +++ b/man2/clock_adjtime.2 @@ -0,0 +1 @@ +.so man2/adjtimex.2 -- 2.9.0 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime 2017-11-20 22:53 [PATCH] [man-pages] adjtimex.2: document clock_adjtime Arnd Bergmann @ 2017-11-21 3:05 ` Richard Cochran 2017-11-21 8:06 ` Arnd Bergmann 0 siblings, 1 reply; 11+ messages in thread From: Richard Cochran @ 2017-11-21 3:05 UTC (permalink / raw) To: Arnd Bergmann Cc: Michael Kerrisk, linux-kernel, linux-api, John Stultz, Thomas Gleixner, Stephen Boyd On Mon, Nov 20, 2017 at 11:53:02PM +0100, Arnd Bergmann wrote: > .B EINVAL > +The > +.I clk_id > +specified is not supported on this system. We return EINVAL when the clockid is not valid. That can mean two things. Either the SYS-V style hard coded positive clockid is out of range, or the dynamic negative clockid does not refer to a valid instance of a clock object. Dynamic clocks might also return ENODEV in case a hot-plugable device (like USB) has disappeared after its character device was opened. Thanks, Richard ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime 2017-11-21 3:05 ` Richard Cochran @ 2017-11-21 8:06 ` Arnd Bergmann 2017-11-21 16:06 ` Richard Cochran 0 siblings, 1 reply; 11+ messages in thread From: Arnd Bergmann @ 2017-11-21 8:06 UTC (permalink / raw) To: Richard Cochran Cc: Michael Kerrisk, Linux Kernel Mailing List, Linux API, John Stultz, Thomas Gleixner, Stephen Boyd On Tue, Nov 21, 2017 at 4:05 AM, Richard Cochran <richardcochran@gmail.com> wrote: > On Mon, Nov 20, 2017 at 11:53:02PM +0100, Arnd Bergmann wrote: >> .B EINVAL >> +The >> +.I clk_id >> +specified is not supported on this system. > > We return EINVAL when the clockid is not valid. That can mean two > things. Either the SYS-V style hard coded positive clockid is out of > range, or the dynamic negative clockid does not refer to a valid > instance of a clock object. > > Dynamic clocks might also return ENODEV in case a hot-plugable device > (like USB) has disappeared after its character device was opened. I copied that line from clock_gettime() man page. I suppose we want to fix change this in both pages, right? Any suggestions for a good way to express your explanation in the man page? I suppose we don't want to go into details of the implementation there but still capture the possible corner cases. Arnd ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime 2017-11-21 8:06 ` Arnd Bergmann @ 2017-11-21 16:06 ` Richard Cochran 2017-11-21 22:09 ` Arnd Bergmann 2017-12-18 19:19 ` Michael Kerrisk (man-pages) 0 siblings, 2 replies; 11+ messages in thread From: Richard Cochran @ 2017-11-21 16:06 UTC (permalink / raw) To: Arnd Bergmann Cc: Michael Kerrisk, Linux Kernel Mailing List, Linux API, John Stultz, Thomas Gleixner, Stephen Boyd On Tue, Nov 21, 2017 at 09:06:37AM +0100, Arnd Bergmann wrote: > > I copied that line from clock_gettime() man page. I suppose we want to > fix change this in both pages, right? Any suggestions for a good way to > express your explanation in the man page? I suppose we don't want to > go into details of the implementation there but still capture the possible > corner cases. Dynamic clockids are a Linux specific extension. This should be explained with a paragraph or two on the gettime man page, along with an example using the macros. #define CLOCKFD 3 #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) Then, the adjtimex page can say, see gettime. Let me try to come up with a text over the (USA) holiday weekend. Thanks, Richard ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime 2017-11-21 16:06 ` Richard Cochran @ 2017-11-21 22:09 ` Arnd Bergmann 2017-12-18 19:19 ` Michael Kerrisk (man-pages) 1 sibling, 0 replies; 11+ messages in thread From: Arnd Bergmann @ 2017-11-21 22:09 UTC (permalink / raw) To: Richard Cochran Cc: Michael Kerrisk, Linux Kernel Mailing List, Linux API, John Stultz, Thomas Gleixner, Stephen Boyd On Tue, Nov 21, 2017 at 5:06 PM, Richard Cochran <richardcochran-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote: > On Tue, Nov 21, 2017 at 09:06:37AM +0100, Arnd Bergmann wrote: >> >> I copied that line from clock_gettime() man page. I suppose we want to >> fix change this in both pages, right? Any suggestions for a good way to >> express your explanation in the man page? I suppose we don't want to >> go into details of the implementation there but still capture the possible >> corner cases. > > Dynamic clockids are a Linux specific extension. This should be > explained with a paragraph or two on the gettime man page, along with > an example using the macros. > > #define CLOCKFD 3 > #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) > #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) > > Then, the adjtimex page can say, see gettime. > > Let me try to come up with a text over the (USA) holiday weekend. Thanks! There is no rush here, take your time. One more question: I see that ptp_clock_adjtime doesn't call timekeeping_validate_timex(), so a number of the error conditions are not caught there. Should we document that as intended, or change it to behave the same way as do_adjtimex()? I also see that ptp_clock_adjtime() ignores all other flags whenever ADJ_SETOFFSET is set, while __do_adjtimex() can do ADJ_SETOFFSET and ADJ_FREQUENCY (or any other combination) in a single syscall, which matches what is documented in the man page. Arnd ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime 2017-11-21 16:06 ` Richard Cochran 2017-11-21 22:09 ` Arnd Bergmann @ 2017-12-18 19:19 ` Michael Kerrisk (man-pages) [not found] ` <436eb61b-0fe2-41c8-0992-e21614fd3657-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 1 sibling, 1 reply; 11+ messages in thread From: Michael Kerrisk (man-pages) @ 2017-12-18 19:19 UTC (permalink / raw) To: Richard Cochran, Arnd Bergmann Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, Linux Kernel Mailing List, Linux API, John Stultz, Thomas Gleixner, Stephen Boyd Hi Richard, On 11/21/2017 05:06 PM, Richard Cochran wrote: > On Tue, Nov 21, 2017 at 09:06:37AM +0100, Arnd Bergmann wrote: >> >> I copied that line from clock_gettime() man page. I suppose we want to >> fix change this in both pages, right? Any suggestions for a good way to >> express your explanation in the man page? I suppose we don't want to >> go into details of the implementation there but still capture the possible >> corner cases. > > Dynamic clockids are a Linux specific extension. This should be > explained with a paragraph or two on the gettime man page, along with > an example using the macros. > > #define CLOCKFD 3 > #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) > #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) > > Then, the adjtimex page can say, see gettime. > > Let me try to come up with a text over the (USA) holiday weekend. Might you have a chance to look at this still? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 11+ messages in thread
[parent not found: <436eb61b-0fe2-41c8-0992-e21614fd3657-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]
* Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime [not found] ` <436eb61b-0fe2-41c8-0992-e21614fd3657-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> @ 2017-12-19 16:58 ` Richard Cochran 2018-01-01 6:28 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Richard Cochran 0 siblings, 1 reply; 11+ messages in thread From: Richard Cochran @ 2017-12-19 16:58 UTC (permalink / raw) To: Michael Kerrisk (man-pages) Cc: Arnd Bergmann, Linux Kernel Mailing List, Linux API, John Stultz, Thomas Gleixner, Stephen Boyd On Mon, Dec 18, 2017 at 08:19:42PM +0100, Michael Kerrisk (man-pages) wrote: > > Let me try to come up with a text over the (USA) holiday weekend. > > Might you have a chance to look at this still? Sorry for forgetting this. I will have another chance over the upcoming international holiday... Thanks, Richard ^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks. 2017-12-19 16:58 ` Richard Cochran @ 2018-01-01 6:28 ` Richard Cochran 2018-01-01 6:28 ` [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime Richard Cochran 2020-04-20 11:13 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Michael Kerrisk (man-pages) 0 siblings, 2 replies; 11+ messages in thread From: Richard Cochran @ 2018-01-01 6:28 UTC (permalink / raw) To: Michael Kerrisk Cc: Arnd Bergmann, John Stultz, Stephen Boyd, Thomas Gleixner, linux-api-u79uwXL29TY76Z2rM5mHXA, linux-kernel-u79uwXL29TY76Z2rM5mHXA Linux has allowed passing open file descriptors to clock_gettime() and friends since v2.6.39. This patch documents these "dynamic" clocks and adds a brief example of how to use them. Signed-off-by: Richard Cochran <richardcochran-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> --- man2/clock_getres.2 | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index 0812d159a..30cbfe46a 100644 --- a/man2/clock_getres.2 +++ b/man2/clock_getres.2 @@ -183,6 +183,35 @@ Per-process CPU-time clock .TP .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" Thread-specific CPU-time clock. +.PP +Linux also implements dynamic clock instances as described below. +.SH DYNAMIC CLOCKS " (since Linux 2.6.39)" +In addition to hard coded SYS-V style clock ids, Linux also supports +POSIX clock operations on certain character devices. Such devices are +called "dynamic" clocks. Using the appropriate macros, open file +descriptors may be converted into clock ids and passed to +.BR clock_gettime (), +.BR clock_settime (), +and +.BR clock_adj (2). +The follow example shows how to convert a file descriptor into a +dynamic clock id. +.PP +.in +4n +.EX +#define CLOCKFD 3 +#define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) +#define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) + +struct timeval tv; +clockid_t clkid; +int fd; + +fd = open("/dev/ptp0", O_RDWR); +clkid = FD_TO_CLOCKID(fd); +clock_gettime(clkid, &tv); +.EE +.in .SH RETURN VALUE .BR clock_gettime (), .BR clock_settime (), @@ -200,11 +229,19 @@ points outside the accessible address space. .B EINVAL The .I clk_id -specified is not supported on this system. +specified is invalid for one of two reasons. Either the SYS-V style +hard coded positive value is out of range, or the dynamic clock id +does not refer to a valid instance of a clock object. .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be .\" EPERM. .TP +.B ENODEV +The hot-plugable device (like USB for example) represented by a +dynamic +.I clk_id +has disappeared after its character device was opened. +.TP .B EPERM .BR clock_settime () does not have permission to set the clock indicated. -- 2.11.0 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime 2018-01-01 6:28 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Richard Cochran @ 2018-01-01 6:28 ` Richard Cochran 2020-04-20 11:14 ` Michael Kerrisk (man-pages) 2020-04-20 11:13 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Michael Kerrisk (man-pages) 1 sibling, 1 reply; 11+ messages in thread From: Richard Cochran @ 2018-01-01 6:28 UTC (permalink / raw) To: Michael Kerrisk Cc: Arnd Bergmann, John Stultz, Stephen Boyd, Thomas Gleixner, linux-api, linux-kernel From: Arnd Bergmann <arnd@arndb.de> I was experimenting with some possible changes to adjtimex(2) and clock_adjtime(2) and tried to look up the man page to see what the documented behavior is when I noticed that clock_adjtime() appears to be the only system call that is currently undocumented. Before I do any changes to it, this tries to document what I understand it currently does. [ RC: Add better explanations of the usage and error codes and correct some typographical mistakes. ] Signed-off-by: Arnd Bergmann <arnd@arndb.de> Signed-off-by: Richard Cochran <richardcochran@gmail.com> --- man2/adjtimex.2 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++--- man2/clock_adjtime.2 | 1 + 2 files changed, 61 insertions(+), 3 deletions(-) create mode 100644 man2/clock_adjtime.2 diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index fc6892d7e..71b5c4a5a 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -35,6 +35,8 @@ adjtimex, ntp_adjtime \- tune kernel clock .PP .BI "int adjtimex(struct timex *" "buf" ); .PP +.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); +.PP .BI "int ntp_adjtime(struct timex *" buf ); .fi .SH DESCRIPTION @@ -158,8 +160,26 @@ includes the .B ADJ_NANO flag, then .I buf.time.tv_usec -is interpreted as a nanosecond value; +is interpreted as a nanosecond value, otherwise it is interpreted as microseconds. +.IP +The value of +.I buf.time +is the sum of its two fields, but the +field +.I buf.time.tv_usec +must always be non-negative. The following example shows how to +normalize a timeval with nanosecond resolution. +.PP +.in +12n +.EX +while (buf.time.tv_usec < 0) { + buf.time.tv_sec -= 1; + buf.time.tv_usec += 1000000000; +} +.EE +.in +.PP .TP .BR ADJ_MICRO " (since Linux 2.6.26)" .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db @@ -344,6 +364,12 @@ Attempts to set read-only .I status bits are silently ignored. .\" +.SS clock_adjtime () +The +.BR clock_adjtime () +system call (added in Linux 2.6.39) behaves like adjtimex() but takes an additional +.IR clk_id +argument to specify the particular clock on which to act. .SS ntp_adjtime () The .BR ntp_adjtime () @@ -472,6 +498,19 @@ An attempt was made to set to a value other than those listed above. .TP .B EINVAL +The +.I clk_id +given to +.BR clock_adjtime () +is invalid for one of two reasons. Either the SYS-V style hard coded +positive value is out of range, or the dynamic +.I clk_id +does not refer to a valid instance of a clock object. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EINVAL An attempt was made to set .I buf.tick to a value outside the range @@ -482,6 +521,20 @@ where .B HZ is the system timer interrupt frequency. .TP +.B ENODEV +The hot-plugable device (like USB for example) represented by a +dynamic +.I clk_id +has disappeared after its character device was opened. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EOPNOTSUPP +The given +.I clk_id +does not support adjustment. +.TP .B EPERM .I buf.modes is neither 0 nor @@ -503,10 +556,12 @@ T{ T} Thread safety MT-Safe .TE .SH CONFORMING TO -Neither of these interfaces is described in POSIX.1 +None of these interfaces is described in POSIX.1 .PP .BR adjtimex () -is Linux-specific and should not be used in programs +and +.BR clock_adjtime () +are Linux-specific and should not be used in programs intended to be portable. .PP The preferred API for the NTP daemon is @@ -533,6 +588,8 @@ is done by the kernel in timer context Thus, it will take one tick into the second for the leap second to be inserted or deleted. .SH SEE ALSO +.BR clock_gettime (2) +.BR clock_settime (2) .BR settimeofday (2), .BR adjtime (3), .BR ntp_gettime (3), diff --git a/man2/clock_adjtime.2 b/man2/clock_adjtime.2 new file mode 100644 index 000000000..b08b9c801 --- /dev/null +++ b/man2/clock_adjtime.2 @@ -0,0 +1 @@ +.so man2/adjtimex.2 -- 2.11.0 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime 2018-01-01 6:28 ` [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime Richard Cochran @ 2020-04-20 11:14 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 11+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-04-20 11:14 UTC (permalink / raw) To: Richard Cochran Cc: mtk.manpages, Arnd Bergmann, John Stultz, Stephen Boyd, Thomas Gleixner, linux-api, linux-kernel Hello Richard, Arnd, On 1/1/18 7:28 AM, Richard Cochran wrote: > From: Arnd Bergmann <arnd@arndb.de> > > I was experimenting with some possible changes to adjtimex(2) and > clock_adjtime(2) and tried to look up the man page to see what the > documented behavior is when I noticed that clock_adjtime() appears > to be the only system call that is currently undocumented. > > Before I do any changes to it, this tries to document what I > understand it currently does. > > [ RC: Add better explanations of the usage and error codes > and correct some typographical mistakes. ] And this patch too is now applied. Thank you! Cheers, Michael > Signed-off-by: Arnd Bergmann <arnd@arndb.de> > Signed-off-by: Richard Cochran <richardcochran@gmail.com> > --- > man2/adjtimex.2 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++--- > man2/clock_adjtime.2 | 1 + > 2 files changed, 61 insertions(+), 3 deletions(-) > create mode 100644 man2/clock_adjtime.2 > > diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 > index fc6892d7e..71b5c4a5a 100644 > --- a/man2/adjtimex.2 > +++ b/man2/adjtimex.2 > @@ -35,6 +35,8 @@ adjtimex, ntp_adjtime \- tune kernel clock > .PP > .BI "int adjtimex(struct timex *" "buf" ); > .PP > +.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); > +.PP > .BI "int ntp_adjtime(struct timex *" buf ); > .fi > .SH DESCRIPTION > @@ -158,8 +160,26 @@ includes the > .B ADJ_NANO > flag, then > .I buf.time.tv_usec > -is interpreted as a nanosecond value; > +is interpreted as a nanosecond value, > otherwise it is interpreted as microseconds. > +.IP > +The value of > +.I buf.time > +is the sum of its two fields, but the > +field > +.I buf.time.tv_usec > +must always be non-negative. The following example shows how to > +normalize a timeval with nanosecond resolution. > +.PP > +.in +12n > +.EX > +while (buf.time.tv_usec < 0) { > + buf.time.tv_sec -= 1; > + buf.time.tv_usec += 1000000000; > +} > +.EE > +.in > +.PP > .TP > .BR ADJ_MICRO " (since Linux 2.6.26)" > .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db > @@ -344,6 +364,12 @@ Attempts to set read-only > .I status > bits are silently ignored. > .\" > +.SS clock_adjtime () > +The > +.BR clock_adjtime () > +system call (added in Linux 2.6.39) behaves like adjtimex() but takes an additional > +.IR clk_id > +argument to specify the particular clock on which to act. > .SS ntp_adjtime () > The > .BR ntp_adjtime () > @@ -472,6 +498,19 @@ An attempt was made to set > to a value other than those listed above. > .TP > .B EINVAL > +The > +.I clk_id > +given to > +.BR clock_adjtime () > +is invalid for one of two reasons. Either the SYS-V style hard coded > +positive value is out of range, or the dynamic > +.I clk_id > +does not refer to a valid instance of a clock object. > +See > +.BR clock_gettime (2) > +for a discussion of dynamic clocks. > +.TP > +.B EINVAL > An attempt was made to set > .I buf.tick > to a value outside the range > @@ -482,6 +521,20 @@ where > .B HZ > is the system timer interrupt frequency. > .TP > +.B ENODEV > +The hot-plugable device (like USB for example) represented by a > +dynamic > +.I clk_id > +has disappeared after its character device was opened. > +See > +.BR clock_gettime (2) > +for a discussion of dynamic clocks. > +.TP > +.B EOPNOTSUPP > +The given > +.I clk_id > +does not support adjustment. > +.TP > .B EPERM > .I buf.modes > is neither 0 nor > @@ -503,10 +556,12 @@ T{ > T} Thread safety MT-Safe > .TE > .SH CONFORMING TO > -Neither of these interfaces is described in POSIX.1 > +None of these interfaces is described in POSIX.1 > .PP > .BR adjtimex () > -is Linux-specific and should not be used in programs > +and > +.BR clock_adjtime () > +are Linux-specific and should not be used in programs > intended to be portable. > .PP > The preferred API for the NTP daemon is > @@ -533,6 +588,8 @@ is done by the kernel in timer context > Thus, it will take one tick into the second > for the leap second to be inserted or deleted. > .SH SEE ALSO > +.BR clock_gettime (2) > +.BR clock_settime (2) > .BR settimeofday (2), > .BR adjtime (3), > .BR ntp_gettime (3), > diff --git a/man2/clock_adjtime.2 b/man2/clock_adjtime.2 > new file mode 100644 > index 000000000..b08b9c801 > --- /dev/null > +++ b/man2/clock_adjtime.2 > @@ -0,0 +1 @@ > +.so man2/adjtimex.2 > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks. 2018-01-01 6:28 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Richard Cochran 2018-01-01 6:28 ` [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime Richard Cochran @ 2020-04-20 11:13 ` Michael Kerrisk (man-pages) 1 sibling, 0 replies; 11+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-04-20 11:13 UTC (permalink / raw) To: Richard Cochran Cc: mtk.manpages, Arnd Bergmann, John Stultz, Stephen Boyd, Thomas Gleixner, linux-api, linux-kernel Hello Richard, On 1/1/18 7:28 AM, Richard Cochran wrote: > Linux has allowed passing open file descriptors to clock_gettime() and > friends since v2.6.39. This patch documents these "dynamic" clocks > and adds a brief example of how to use them. This fell on the floor, I'm sorry. It's applied now. Thanks you! Michael > Signed-off-by: Richard Cochran <richardcochran@gmail.com> > --- > man2/clock_getres.2 | 39 ++++++++++++++++++++++++++++++++++++++- > 1 file changed, 38 insertions(+), 1 deletion(-) > > diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 > index 0812d159a..30cbfe46a 100644 > --- a/man2/clock_getres.2 > +++ b/man2/clock_getres.2 > @@ -183,6 +183,35 @@ Per-process CPU-time clock > .TP > .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" > Thread-specific CPU-time clock. > +.PP > +Linux also implements dynamic clock instances as described below. > +.SH DYNAMIC CLOCKS " (since Linux 2.6.39)" > +In addition to hard coded SYS-V style clock ids, Linux also supports > +POSIX clock operations on certain character devices. Such devices are > +called "dynamic" clocks. Using the appropriate macros, open file > +descriptors may be converted into clock ids and passed to > +.BR clock_gettime (), > +.BR clock_settime (), > +and > +.BR clock_adj (2). > +The follow example shows how to convert a file descriptor into a > +dynamic clock id. > +.PP > +.in +4n > +.EX > +#define CLOCKFD 3 > +#define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) > +#define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) > + > +struct timeval tv; > +clockid_t clkid; > +int fd; > + > +fd = open("/dev/ptp0", O_RDWR); > +clkid = FD_TO_CLOCKID(fd); > +clock_gettime(clkid, &tv); > +.EE > +.in > .SH RETURN VALUE > .BR clock_gettime (), > .BR clock_settime (), > @@ -200,11 +229,19 @@ points outside the accessible address space. > .B EINVAL > The > .I clk_id > -specified is not supported on this system. > +specified is invalid for one of two reasons. Either the SYS-V style > +hard coded positive value is out of range, or the dynamic clock id > +does not refer to a valid instance of a clock object. > .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID > .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be > .\" EPERM. > .TP > +.B ENODEV > +The hot-plugable device (like USB for example) represented by a > +dynamic > +.I clk_id > +has disappeared after its character device was opened. > +.TP > .B EPERM > .BR clock_settime () > does not have permission to set the clock indicated. > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2020-04-20 11:14 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-11-20 22:53 [PATCH] [man-pages] adjtimex.2: document clock_adjtime Arnd Bergmann 2017-11-21 3:05 ` Richard Cochran 2017-11-21 8:06 ` Arnd Bergmann 2017-11-21 16:06 ` Richard Cochran 2017-11-21 22:09 ` Arnd Bergmann 2017-12-18 19:19 ` Michael Kerrisk (man-pages) [not found] ` <436eb61b-0fe2-41c8-0992-e21614fd3657-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 2017-12-19 16:58 ` Richard Cochran 2018-01-01 6:28 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Richard Cochran 2018-01-01 6:28 ` [PATCH man-pages 2/2] adjtimex.2: document clock_adjtime Richard Cochran 2020-04-20 11:14 ` Michael Kerrisk (man-pages) 2020-04-20 11:13 ` [PATCH man-pages 1/2] clock_getres.2: Explain dynamic clocks Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).