docs/73618: [PATCH] Several improvements to man 1 ps

[Jilles Tjoelker]

>Number:         73618
>Category:       docs
>Synopsis:       [PATCH] Several improvements to man 1 ps
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Nov 06 16:00:47 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator:     Jilles Tjoelker
>Release:        FreeBSD 6.0-CURRENT amd64
>Organization:
MCGV Stack
>Environment:
System: FreeBSD hammer.stack.nl 6.0-CURRENT FreeBSD 6.0-CURRENT #3: Mon Nov 1 18:36:46 CET 2004 marcolz at hammer.stack.nl:/usr/obj/usr/src/sys/HAMMER amd64
>Description:
* Document the fact that empty heading text suppresses the heading line (e.g.
  'ps -o pid='), as this is very useful in scripts.
* Describe logname keyword more completely.
* Describe the printing of arguments more completely.
* Put lockname in the correct alphabetical order in the list of all keywords.
* Correct sentence in standards section.
>How-To-Repeat:
man ps
>Fix:

	

--- ps.1.patch begins here ---
--- src/bin/ps/ps.1.orig	Sat Nov  6 16:05:11 2004
+++ src/bin/ps/ps.1	Sat Nov  6 16:39:13 2004
@@ -187,6 +187,7 @@
 sign and a string.
 This causes the printed header to use the specified string instead of
 the standard header.
+If all keywords have empty header texts, no header line is written.
 .It Fl p
 Display information about processes which match the specified process IDs.
 .It Fl r
@@ -310,6 +311,9 @@
 If the name is invalid or unknown, then
 .Dq ???\&
 is displayed.
+.It Cm logname
+The login name associated with the session the process is in (see
+.Xr getlogin 2 ) .
 .It Cm mwchan
 The event name if the process is blocked normally, or the lock name if
 the process is blocked on a lock.
@@ -414,18 +418,26 @@
 and a process which is blocked while trying
 to exit is listed as
 .Dq Li <exiting> .
-If the command vector cannot be located (usually because it has not
-been set, as is the case of system processes and/or kernel threads)
-the command name is printed within square brackets.
+If the arguments cannot be located (usually because it has not been set, as is
+the case of system processes and/or kernel threads) the command name is printed
+within square brackets.
 The
 .Nm
-utility
+utility first tries to obtain the arguments cached by the kernel (if they were
+shorter than the value of the
+.Va kern.ps_arg_cache_limit
+sysctl).
+The process can change the arguments shown with
+.Xr setproctitle 3 .
+Otherwise,
+.Nm
 makes an educated guess as to the file name and arguments given when the
 process was created by examining memory or the swap area.
 The method is inherently somewhat unreliable and in any event a process
-is entitled to destroy this information, so the names cannot be depended
-on too much.
+is entitled to destroy this information.
 The ucomm (accounting) keyword can, however, be depended on.
+If the arguments are unavailable or do not agree with the ucomm keyword,
+the value for the ucomm keyword is appended to the arguments in parentheses.
 .Sh KEYWORDS
 The following is a complete list of the available keywords and their
 meanings.
@@ -465,8 +477,10 @@
 MAC label
 .It Cm lim
 memoryuse limit
+.It Cm lockname
+lock currently blocked on (as a symbolic name)
 .It Cm logname
-login name of user who started the process
+login name of user who started the session
 .It Cm lstart
 time started
 .It Cm majflt
@@ -477,8 +491,6 @@
 total messages received (reads from pipes/sockets)
 .It Cm msgsnd
 total messages sent (writes on pipes/sockets)
-.It Cm lockname
-lock currently blocked on (as a symbolic name)
 .It Cm mwchan
 wait channel or lock currently blocked on
 .It Cm nice
@@ -624,7 +636,7 @@
 .Xr sysctl 8 ,
 .Xr mutex 9
 .Sh STANDARDS
-For historical reasons,
+For historical reasons, the
 .Nm
 utility under
 .Fx
--- ps.1.patch ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: