Bug 118332 - man page for top(1) does not describe STATE column wait events
Summary: man page for top(1) does not describe STATE column wait events
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-bugs (Nobody)
URL:
Keywords:
: 130364 (view as bug list)
Depends on:
Blocks:
 
Reported: 2007-11-29 18:30 UTC by Andrew Hammond
Modified: 2018-06-10 06:28 UTC (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Andrew Hammond 2007-11-29 18:30:02 UTC
The manual page for top does not describe or provide a pointer to descriptions of STATEs such as swread, nanslp, select, piperd, etc.
Comment 1 Giorgos Keramidas freebsd_committer 2008-02-10 19:51:17 UTC
On 2007-11-29 18:27, Andrew Hammond <andrew.george.hammond@gmail.com> wrote:
> >Number:         118332
> >Category:       docs
> >Synopsis:       man page for top does not describe STATE column wait events

> The manual page for top does not describe or provide a pointer to
> descriptions of STATEs such as swread, nanslp, select, piperd, etc.

The manpage describes `STATE' with the somewhat cryptic text:

    STATE is the current state (one of "START", "RUN" (shown as "CPUn"
    on SMP systems), "SLEEP", "STOP", "ZOMB", "WAIT", "LOCK" or the
    event on which the process waits),

Any lowercase string is the name of a kernel-related event, and it would
be a very daunting task to list them *all* in the manpage.  Do you think
we can phrase this particular part of the manpage in a way that is more
helpful?  If yes, we are open to suggestions.
Comment 2 Giorgos Keramidas freebsd_committer 2008-02-10 19:51:33 UTC
State Changed
From-To: open->feedback

Set the state to `feedback', and add myself to the `notify' list.
Comment 3 Andrew Hammond 2008-02-10 20:38:02 UTC
On Feb 10, 2008 11:51 AM, Giorgos Keramidas <keramida@freebsd.org> wrote:

> On 2007-11-29 18:27, Andrew Hammond <andrew.george.hammond@gmail.com>
> wrote:
> > >Number:         118332
> > >Category:       docs
> > >Synopsis:       man page for top does not describe STATE column wait
> events
>
> > The manual page for top does not describe or provide a pointer to
> > descriptions of STATEs such as swread, nanslp, select, piperd, etc.
>
> The manpage describes `STATE' with the somewhat cryptic text:
>
>    STATE is the current state (one of "START", "RUN" (shown as "CPUn"
>    on SMP systems), "SLEEP", "STOP", "ZOMB", "WAIT", "LOCK" or the
>    event on which the process waits),
>
> Any lowercase string is the name of a kernel-related event, and it would
> be a very daunting task to list them *all* in the manpage.  Do you think
> we can phrase this particular part of the manpage in a way that is more
> helpful?  If yes, we are open to suggestions.


How about continuing on with something like the following.

"Here are some common events which can cause a process to wait and what they
mean."

Then list the ones that a user is most likely to see while dealing with a
performance problem along with brief descriptions and finally provide a
reference to the canonical documentation.

A
Comment 4 Volker Werth freebsd_committer 2008-05-02 11:37:44 UTC
State Changed
From-To: feedback->open


Feedback has been provided. 
If I got this right, the states are listed but manpage does not describe them. 
Do we need to explain process states in detail?
Comment 5 Andrew Hammond 2008-05-02 18:08:50 UTC
From an operations stance, when I'm trying to diagnose an issue, and I see
from top that a process is in some state that I don't recognize or
understand, I want to know what it means. I naturally go to the man page for
top to find out. If it's not directly in there then I want a pointer of
where I should look next. So, to clarify my prior email, it'd be nice if the
man page listed some of the more common states and what they mean and then
provided a pointer to the canonical documentation.

Andrew
Comment 6 Chris St Denis 2009-06-19 06:51:33 UTC
Not all states are listed. For example I have some processes spending a 
lot of time in state "*vm ob" but I can't find any info on what exactly 
this means.

The man page should identify this, or point us somewhere that does.

I suspect there is not currently anywhere that these states are 
comprehensively documented. There should be.
Comment 7 Alexander Best freebsd_committer 2011-08-06 10:08:14 UTC
Responsible Changed
From-To: freebsd-doc->arundel

Over to me, since I'm working on this issue atm.
Comment 8 Alexander Best freebsd_committer 2014-06-02 11:09:46 UTC
Reset assignee -- not working on these PRs atm.
Comment 9 Allan Jude freebsd_committer 2018-05-20 18:18:18 UTC
This doesn't really have anything to do with top(1), and applies to ps(1), procstat(1), etc as well.

The issue is, whenever some code tells the kernel to sleep or wait, it must provide a short text string to identify that 'wait channel'. There is no master list, or even a nomenclature for these short strings.

It might be worth trying to make one, but in a separate man page 'waitchan' or something
Comment 10 Eitan Adler freebsd_committer freebsd_triage 2018-06-10 06:28:18 UTC
*** Bug 130364 has been marked as a duplicate of this bug. ***