os.times document points to wrong section of non-Linux manual

[Wooble]

BPO	20806
Nosy	@bitdancer, @Wooble, @serhiy-storchaka, @eryksun, @miss-islington, @nanjekyejoannah
PRs	bpo-20806: os.times document points to wrong section of non-Linux manual #15479 [3.8] bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479) #15722 [3.7] bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479) #15723

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-09-07.08:08:31.943>
created_at = <Date 2014-02-28.12:33:25.061>
labels = ['3.7', '3.8', '3.9', 'docs']
title = 'os.times document points to wrong section of non-Linux manual'
updated_at = <Date 2019-09-07.08:08:31.933>
user = 'https://github.com/Wooble'

bugs.python.org fields:

activity = <Date 2019-09-07.08:08:31.933>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-07.08:08:31.943>
closer = 'serhiy.storchaka'
components = ['Documentation']
creation = <Date 2014-02-28.12:33:25.061>
creator = 'geoffreyspear'
dependencies = []
files = []
hgrepos = []
issue_num = 20806
keywords = ['patch']
message_count = 10.0
messages = ['212424', '212436', '350418', '350442', '350450', '350475', '350677', '351287', '351291', '351292']
nosy_count = 7.0
nosy_names = ['r.david.murray', 'docs@python', 'geoffreyspear', 'serhiy.storchaka', 'eryksun', 'miss-islington', 'nanjekyejoannah']
pr_nums = ['15479', '15722', '15723']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue20806'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[Wooble]

The documentation for os.times directs the reader: "See the Unix manual page times(2) or the corresponding Windows Platform API documentation."

However, the POSIX manual page in question is times(3P), and on OS X and BSD systems it's times(3). Falling back to "man times" without specifying a manual section also doesn't work, since this finds the bash builtin rather than the library function.

[bitdancer]

section 2 is the linux man page (system calls). On the other hand, on a freebsd 6.4 system I have access to, 'man times' does show the man 3 page.

Since linux normally ships with the posix man pages as well, we should probably change the the section reference to 3p.

I also notice that os/2 is mentioned in the python3 entry for os.times, but os/2 is no longer supported.

[nanjekyejoannah]

I opened a PR for this. @david please review.

[serhiy-storchaka]

Section 3p is OS specific (Debian and derivatives). man 3 times works as well.

But the manpages-posix-dev is not installed by default, so changing this will add a regression on Linux.

I thank that it would be better to add both references, times(2) and times(3). And we can also add a link to MSDN.

[nanjekyejoannah]

Serhiy,

This sounds good.

I will update the PR.

[eryksun]

The function's doc string also needs to be updated to use the correct field names: "user", "system", "children_user", "children_system", and "elapsed".

And we can also add a link to MSDN.

os.times calls GetProcessTimes [1]. The user and kernel process times are incremented in clock ticks, i.e. in integer multiples of the system clock interrupt time. QueryUnbiasedInterruptTime [2] could thus be used for the value of elapsed.

(Windows doesn't implement a process tree for the children_user and children_system values. It has jobs, which are similar to Linux control groups, but jobs aren't applicable here. POSIX doesn't have anything like Windows jobs or Linux cgroups.)

[1] https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes
[2] https://docs.microsoft.com/en-us/windows/win32/api/realtimeapiset/nf-realtimeapiset-queryunbiasedinterrupttime

[nanjekyejoannah]

I updated the PR to reference times(2) and times(3) along with an MSDN link.

[serhiy-storchaka]

New changeset 3ccdbc3 by Serhiy Storchaka (Joannah Nanjekye) in branch 'master':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
3ccdbc3

[miss-islington]

New changeset cc51a6d by Miss Islington (bot) in branch '3.8':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
cc51a6d

[miss-islington]

New changeset a6eac83 by Miss Islington (bot) in branch '3.7':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
a6eac83