Bug 61171

Summary:	adjtimex(2): incomplete description of the struct timex
Product:	Documentation	Reporter:	Matwey V. Kornilov (matwey.kornilov)
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages, tinajohnson.1234
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:
Attachments:	Added information about variables of timeval structure and different units of time used by them

Description Matwey V. Kornilov 2013-09-11 17:56:57 UTC

Hi,

I am using 3.46 release of man-pages under openSUSE 12.3.

man adjtimex(2) says that struct timex has a member:

struct timeval time; /* current time (read-only) */

implying that timeval has two fields: seconds and microseconds (as it described in many places, for instance GLIBC documentation). This misinforms people, and explicit behavior must be reported.

Inspection of kernel/time/ntp.c (as for linux 3.7) demonstrates that the second field timex.time.tv_usec may contain nanoseconds instead of microseconds. When timex.status STA_NANO flag is not set, this field contains microseconds, as one expects.

The previous is still also true for timex.offset which is stated to be in units of usec. Units of offset also depend on STA_NANO flag.

Comment 1 Tina Johnson 2014-06-17 08:48:21 UTC

Do you suggest that we edit the man page of adjtimex?

Comment 2 Matwey V. Kornilov 2014-06-17 08:55:40 UTC

I hope so

2014-06-17 12:48 GMT+04:00  <bugzilla-daemon@bugzilla.kernel.org>:
> https://bugzilla.kernel.org/show_bug.cgi?id=61171
>
> Tina Johnson <tinajohnson.1234@gmail.com> changed:
>
>            What    |Removed                     |Added
> ----------------------------------------------------------------------------
>                  CC|                            |tinajohnson.1234@gmail.com
>
> --- Comment #1 from Tina Johnson <tinajohnson.1234@gmail.com> ---
> Do you suggest that we edit the man page of adjtimex?
>
> --
> You are receiving this mail because:
> You reported the bug.

Comment 3 Tina Johnson 2014-06-17 11:54:17 UTC

Created attachment 140071 [details]
Added information about variables of timeval structure and different units of time used by them

Hope this is the required patch.

Comment 4 Michael Kerrisk 2014-06-18 13:34:48 UTC

Matwey, thanks for the report. Tina, thanks for the patch.

The bigger problem is that the adjtimex(2) is hugely out of date, and in any case very thin on the details. The nanosecond aspect is rather more complex than is captured in the patch, as far as I can see. I will work on some updates to the page.

Comment 5 Michael Kerrisk 2015-05-05 09:50:37 UTC

Some months ago, I made same changes to the man page which I think should cover the concerns in this report. So, closing now.