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.

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.

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

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.

Serhiy,

This sounds good.

I will update the PR.

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

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

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

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

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