| Message ID | 20171120225302.3379657-1-arnd@arndb.de |
|---|---|
| State | New |
| Headers | show |
| Series | [man-pages] adjtimex.2: document clock_adjtime | expand |
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
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
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
On Tue, Nov 21, 2017 at 5:06 PM, Richard Cochran <richardcochran@gmail.com> 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
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/
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
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
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@arndb.de> --- 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 -- 2.9.0