classification
Title: os.times document points to wrong section of non-Linux manual
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eryksun, geoffreyspear, miss-islington, nanjekyejoannah, r.david.murray, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2014-02-28 12:33 by geoffreyspear, last changed 2019-09-07 08:08 by serhiy.storchaka. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 15479 merged nanjekyejoannah, 2019-08-25 01:53
PR 15722 merged miss-islington, 2019-09-07 07:05
PR 15723 merged miss-islington, 2019-09-07 07:06
Messages (10)
msg212424 - (view) Author: Geoffrey Spear (geoffreyspear) * Date: 2014-02-28 12:33
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.
msg212436 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-28 14:44
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.
msg350418 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-08-25 01:57
I opened a PR for this. @david please review.
msg350442 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-08-25 09:31
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.
msg350450 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-08-25 11:17
Serhiy,

This sounds good.

I will update the PR.
msg350475 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2019-08-25 23:53
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
msg350677 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-08-28 17:13
I updated the PR to reference times(2) and times(3) along with an MSDN link.
msg351287 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-09-07 07:05
New changeset 3ccdbc33385a849c60a268def578cb06b8d41be6 by Serhiy Storchaka (Joannah Nanjekye) in branch 'master':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
https://github.com/python/cpython/commit/3ccdbc33385a849c60a268def578cb06b8d41be6
msg351291 - (view) Author: miss-islington (miss-islington) Date: 2019-09-07 07:12
New changeset cc51a6d7c7b6b06fb537860428347d88776d802b by Miss Islington (bot) in branch '3.8':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
https://github.com/python/cpython/commit/cc51a6d7c7b6b06fb537860428347d88776d802b
msg351292 - (view) Author: miss-islington (miss-islington) Date: 2019-09-07 07:16
New changeset a6eac83c1804fd14ed076b1776ffeea8dcb9478a by Miss Islington (bot) in branch '3.7':
bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479)
https://github.com/python/cpython/commit/a6eac83c1804fd14ed076b1776ffeea8dcb9478a
History
Date User Action Args
2019-09-07 08:08:31serhiy.storchakasetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.7, Python 3.8, Python 3.9, - Python 3.1, Python 2.7, Python 3.2, Python 3.3, Python 3.4
2019-09-07 07:16:30miss-islingtonsetmessages: + msg351292
2019-09-07 07:12:37miss-islingtonsetnosy: + miss-islington
messages: + msg351291
2019-09-07 07:06:05miss-islingtonsetpull_requests: + pull_request15377
2019-09-07 07:05:59miss-islingtonsetstage: patch review
pull_requests: + pull_request15376
2019-09-07 07:05:32serhiy.storchakasetmessages: + msg351287
2019-08-28 17:13:35nanjekyejoannahsetmessages: + msg350677
2019-08-25 23:53:51eryksunsetnosy: + eryksun
messages: + msg350475
2019-08-25 11:17:35nanjekyejoannahsetmessages: + msg350450
2019-08-25 09:31:37serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg350442
2019-08-25 01:57:05nanjekyejoannahsetnosy: + nanjekyejoannah

messages: + msg350418
stage: patch review -> (no value)
2019-08-25 01:53:40nanjekyejoannahsetkeywords: + patch
stage: patch review
pull_requests: + pull_request15165
2014-02-28 14:44:57r.david.murraysetnosy: + r.david.murray
messages: + msg212436
2014-02-28 12:33:25geoffreyspearcreate