diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/ps.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/ps.1p | 603 |
1 files changed, 603 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/ps.1p b/man-pages-posix-2003/man1p/ps.1p new file mode 100644 index 0000000..7525292 --- /dev/null +++ b/man-pages-posix-2003/man1p/ps.1p @@ -0,0 +1,603 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PS" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ps +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +ps \- report process status +.SH SYNOPSIS +.LP +\fBps\fP \fB[\fP\fB-aA\fP\fB][\fP\fB-defl\fP\fB][\fP\fB-G\fP +\fIgrouplist\fP\fB][\fP\fB-o\fP \fIformat\fP\fB]\fP\fB...\fP\fB[\fP\fB-p\fP +\fIproclist\fP\fB][\fP\fB-t\fP +\fItermlist\fP\fB] +.br +.sp +[\fP\fB-U\fP \fIuserlist\fP\fB][\fP\fB-g\fP \fIgrouplist\fP\fB][\fP\fB-n\fP +\fInamelist\fP\fB][\fP\fB-u\fP +\fIuserlist\fP\fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIps\fP utility shall write information about processes, subject +to having the appropriate privileges to obtain +information about those processes. +.LP +By default, \fIps\fP shall select all processes with the same effective +user ID as the current user and the same controlling +terminal as the invoker. +.SH OPTIONS +.LP +The \fIps\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-a\fP +Write information for all processes associated with terminals. Implementations +may omit session leaders from this list. +.TP 7 +\fB-A\fP +Write information for all processes. +.TP 7 +\fB-d\fP +Write information for all processes, except session leaders. +.TP 7 +\fB-e\fP +Write information for all processes. (Equivalent to +\fB-A\fP.) +.TP 7 +\fB-f\fP +Generate a \fBfull\fP listing. (See the STDOUT section for the contents +of a \fBfull\fP listing.) +.TP 7 +\fB-g\ \fP \fIgrouplist\fP +Write information for processes whose session leaders are given in +\fIgrouplist\fP. The application shall ensure that the +\fIgrouplist\fP is a single argument in the form of a <blank> or comma-separated +list. +.TP 7 +\fB-G\ \fP \fIgrouplist\fP +Write information for processes whose real group ID numbers are given +in \fIgrouplist\fP. The application shall ensure that +the \fIgrouplist\fP is a single argument in the form of a <blank> +or comma-separated list. +.TP 7 +\fB-l\fP +Generate a \fBlong\fP listing. (See STDOUT for the contents of a \fBlong\fP +listing.) +.TP 7 +\fB-n\ \fP \fInamelist\fP +Specify the name of an alternative system \fInamelist\fP file in place +of the default. The name of the default file and the format +of a \fInamelist\fP file are unspecified. +.TP 7 +\fB-o\ \fP \fIformat\fP +Write information according to the format specification given in \fIformat\fP. +This is fully described in the STDOUT section. +Multiple \fB-o\fP options can be specified; the format specification +shall be interpreted as the <space>-separated +concatenation of all the \fIformat\fP option-arguments. +.TP 7 +\fB-p\ \fP \fIproclist\fP +Write information for processes whose process ID numbers are given +in \fIproclist\fP. The application shall ensure that the +\fIproclist\fP is a single argument in the form of a <blank> or comma-separated +list. +.TP 7 +\fB-t\ \fP \fItermlist\fP +Write information for processes associated with terminals given in +\fItermlist\fP. The application shall ensure that the +\fItermlist\fP is a single argument in the form of a <blank> or comma-separated +list. Terminal identifiers shall be given in +an implementation-defined format. On XSI-conformant systems, they +shall be given in one of two forms: the device's filename +(for example, \fBtty04\fP) or, if the device's filename starts with +\fBtty\fP, just the identifier following the characters +\fBtty\fP (for example, \fB"04"\fP ). +.TP 7 +\fB-u\ \fP \fIuserlist\fP +Write information for processes whose user ID numbers or login names +are given in \fIuserlist\fP. The application shall ensure +that the \fIuserlist\fP is a single argument in the form of a <blank> +or comma-separated list. In the listing, the numerical +user ID shall be written unless the \fB-f\fP option is used, in which +case the login name shall be written. +.TP 7 +\fB-U\ \fP \fIuserlist\fP +Write information for processes whose real user ID numbers or login +names are given in \fIuserlist\fP. The application shall +ensure that the \fIuserlist\fP is a single argument in the form of +a <blank> or comma-separated list. +.sp +.LP +With the exception of \fB-o\fP \fIformat\fP, all of the options shown +are used to select processes. If any are specified, the +default list shall be ignored and \fIps\fP shall select the processes +represented by the inclusive OR of all the +selection-criteria options. +.SH OPERANDS +.LP +None. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIps\fP: +.TP 7 +\fICOLUMNS\fP +Override the system-selected horizontal display line size, used to +determine the number of text columns to display. See the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment +Variables for valid values and results when it is unset or null. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.TP 7 +\fILC_TIME\fP +Determine the format and contents of the date and time strings displayed. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone used to calculate date and time strings displayed. +If \fITZ\fP is unset or null, an unspecified default +timezone shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +When the \fB-o\fP option is not specified, the standard output format +is unspecified. +.LP +On XSI-conformant systems, the output format shall be as follows. +The column headings and descriptions of the columns in a +\fIps\fP listing are given below. The precise meanings of these fields +are implementation-defined. The letters \fB'f'\fP and +\fB'l'\fP (below) indicate the option ( \fBfull\fP or \fBlong\fP) +that shall cause the corresponding heading to appear; +\fBall\fP means that the heading always appears. Note that these two +options determine only what information is provided for a +process; they do not determine which processes are listed. +.TS C +center; l l lw(40). +\fBF\fP (l) T{ +.na +Flags (octal and additive) associated with the process. +.ad +T} +\fBS\fP (l) T{ +.na +The state of the process. +.ad +T} +\fBUID\fP (f,l) T{ +.na +The user ID number of the process owner; the login name is printed under the \fB-f\fP option. +.ad +T} +\fBPID\fP (all) T{ +.na +The process ID of the process; it is possible to kill a process if this datum is known. +.ad +T} +\fBPPID\fP (f,l) T{ +.na +The process ID of the parent process. +.ad +T} +\fBC\fP (f,l) T{ +.na +Processor utilization for scheduling. +.ad +T} +\fBPRI\fP (l) T{ +.na +The priority of the process; higher numbers mean lower priority. +.ad +T} +\fBNI\fP (l) T{ +.na +Nice value; used in priority computation. +.ad +T} +\fBADDR\fP (l) T{ +.na +The address of the process. +.ad +T} +\fBSZ\fP (l) T{ +.na +The size in blocks of the core image of the process. +.ad +T} +\fBWCHAN\fP (l) T{ +.na +The event for which the process is waiting or sleeping; if blank, the process is running. +.ad +T} +\fBSTIME\fP (f) T{ +.na +Starting time of the process. +.ad +T} +\fBTTY\fP (all) T{ +.na +The controlling terminal for the process. +.ad +T} +\fBTIME\fP (all) T{ +.na +The cumulative execution time for the process. +.ad +T} +\fBCMD\fP (all) T{ +.na +The command name; the full command name and its arguments are written under the \fB-f\fP option. +.ad +T} +.TE +.LP +A process that has exited and has a parent, but has not yet been waited +for by the parent, shall be marked \fBdefunct\fP. +.LP +Under the option \fB-f\fP, \fIps\fP tries to determine the command +name and arguments given when the process was created by +examining memory or the swap area. Failing this, the command name, +as it would appear without the option \fB-f\fP, is written in +square brackets. +.LP +The \fB-o\fP option allows the output format to be specified under +user control. +.LP +The application shall ensure that the format specification is a list +of names presented as a single argument, <blank> or +comma-separated. Each variable has a default header. The default header +can be overridden by appending an equals sign and the new +text of the header. The rest of the characters in the argument shall +be used as the header text. The fields specified shall be +written in the order specified on the command line, and should be +arranged in columns in the output. The field widths shall be +selected by the system to be at least as wide as the header text (default +or overridden value). If the header text is null, such as +\fB-o\fP \fIuser\fP=, the field width shall be at least as wide as +the default header text. If all header text fields are null, +no header line shall be written. +.LP +The following names are recognized in the POSIX locale: +.TP 7 +\fBruser\fP +The real user ID of the process. This shall be the textual user ID, +if it can be obtained and the field width permits, or a +decimal representation otherwise. +.TP 7 +\fBuser\fP +The effective user ID of the process. This shall be the textual user +ID, if it can be obtained and the field width permits, or +a decimal representation otherwise. +.TP 7 +\fBrgroup\fP +The real group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, or a +decimal representation otherwise. +.TP 7 +\fBgroup\fP +The effective group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, +or a decimal representation otherwise. +.TP 7 +\fBpid\fP +The decimal value of the process ID. +.TP 7 +\fBppid\fP +The decimal value of the parent process ID. +.TP 7 +\fBpgid\fP +The decimal value of the process group ID. +.TP 7 +\fBpcpu\fP +The ratio of CPU time used recently to CPU time available in the same +period, expressed as a percentage. The meaning of +"recently" in this context is unspecified. The CPU time available +is determined in an unspecified manner. +.TP 7 +\fBvsz\fP +The size of the process in (virtual) memory in 1024 byte units as +a decimal integer. +.TP 7 +\fBnice\fP +The decimal value of the nice value of the process; see \fInice\fP() +\&. +.TP 7 +\fBetime\fP +In the POSIX locale, the elapsed time since the process was started, +in the form: +.sp +.RS +.nf + +\fB[[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fB]\fP\fImm\fP\fB:\fP\fIss\fP +.fi +.RE +.LP +where \fIdd\fP shall represent the number of days, \fIhh\fP the number +of hours, \fImm\fP the number of minutes, and +\fIss\fP the number of seconds. The \fIdd\fP field shall be a decimal +integer. The \fIhh\fP, \fImm\fP, and \fIss\fP fields +shall be two-digit decimal integers padded on the left with zeros. +.TP 7 +\fBtime\fP +In the POSIX locale, the cumulative CPU time of the process in the +form: +.sp +.RS +.nf + +\fB[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP +.fi +.RE +.LP +The \fIdd\fP, \fIhh\fP, \fImm\fP, and \fIss\fP fields shall be as +described in the \fBetime\fP specifier. +.TP 7 +\fBtty\fP +The name of the controlling terminal of the process (if any) in the +same format used by the \fIwho\fP utility. +.TP 7 +\fBcomm\fP +The name of the command being executed ( \fIargv\fP[0] value) as a +string. +.TP 7 +\fBargs\fP +The command with all its arguments as a string. The implementation +may truncate this value to the field width; it is +implementation-defined whether any further truncation occurs. It is +unspecified whether the string represented is a version of the +argument list as it was passed to the command when it started, or +is a version of the arguments as they may have been modified by +the application. Applications cannot depend on being able to modify +their argument list and having that modification be reflected +in the output of \fIps\fP. +.sp +.LP +Any field need not be meaningful in all implementations. In such a +case a hyphen ( \fB'-'\fP ) should be output in place of +the field value. +.LP +Only \fBcomm\fP and \fBargs\fP shall be allowed to contain <blank>s; +all others shall not. Any implementation-defined +variables shall be specified in the system documentation along with +the default header and indicating whether the field may contain +<blank>s. +.LP +The following table specifies the default header to be used in the +POSIX locale corresponding to each format specifier. +.br +.sp +.ce 1 +\fBTable: Variable Names and Default Headers in \fIps\fP\fP +.TS C +center; l1 l1 l1 l. +\fBFormat Specifier\fP \fBDefault Header\fP \fBFormat Specifier\fP \fBDefault Header\fP +\fBargs\fP \fBCOMMAND\fP \fBppid\fP \fBPPID\fP +\fBcomm\fP \fBCOMMAND\fP \fBrgroup\fP \fBRGROUP\fP +\fBetime\fP \fBELAPSED\fP \fBruser\fP \fBRUSER\fP +\fBgroup\fP \fBGROUP\fP \fBtime\fP \fBTIME\fP +\fBnice\fP \fBNI\fP \fBtty\fP \fBTT\fP +\fBpcpu\fP \fB%CPU\fP \fBuser\fP \fBUSER\fP +\fBpgid\fP \fBPGID\fP \fBvsz\fP \fBVSZ\fP +\fBpid\fP \fBPID\fP \fB\ \fP \fB\ \fP +.TE +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Things can change while \fIps\fP is running; the snapshot it gives +is only true for an instant, and might not be accurate by +the time it is displayed. +.LP +The \fBargs\fP format specifier is allowed to produce a truncated +version of the command arguments. In some implementations, +this information is no longer available when the \fIps\fP utility +is executed. +.LP +If the field width is too narrow to display a textual ID, the system +may use a numeric version. Normally, the system would be +expected to choose large enough field widths, but if a large number +of fields were selected to write, it might squeeze fields to +their minimum sizes to fit on one line. One way to ensure adequate +width for the textual IDs is to override the default header for +a field to make it larger than most or all user or group names. +.LP +There is no special quoting mechanism for header text. The header +text is the rest of the argument. If multiple header changes +are needed, multiple \fB-o\fP options can be used, such as: +.sp +.RS +.nf + +\fBps -o "user=User Name" -o pid=Process\\ ID +\fP +.fi +.RE +.LP +On some implementations, especially multi-level secure systems, \fIps\fP +may be severely restricted and produce information +only about child processes owned by the user. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBps -o user,pid,ppid=MOM -o args +\fP +.fi +.RE +.LP +writes at least the following in the POSIX locale: +.sp +.RS +.nf + +\fB USER PID MOM COMMAND +helene 34 12 ps -o uid,pid,ppid=MOM -o args +\fP +.fi +.RE +.LP +The contents of the \fBCOMMAND\fP field need not be the same in all +implementations, due to possible truncation. +.SH RATIONALE +.LP +There is very little commonality between BSD and System V implementations +of \fIps\fP. Many options conflict or have subtly +different usages. The standard developers attempted to select a set +of options for the base standard that were useful on a wide +range of systems and selected options that either can be implemented +on both BSD and System V-based systems without breaking the +current implementations or where the options are sufficiently similar +that any changes would not be unduly problematic for users or +implementors. +.LP +It is recognized that on some implementations, especially multi-level +secure systems, \fIps\fP may be nearly useless. The +default output has therefore been chosen such that it does not break +historical implementations and also is likely to provide at +least some useful information on most systems. +.LP +The major change is the addition of the format specification capability. +The motivation for this invention is to provide a +mechanism for users to access a wider range of system information, +if the system permits it, in a portable manner. The fields +chosen to appear in this volume of IEEE\ Std\ 1003.1-2001 were arrived +at after considering what concepts were likely to be +both reasonably useful to the "average" user and had a reasonable +chance of being implemented on a wide range of systems. Again +it is recognized that not all systems are able to provide all the +information and, conversely, some may wish to provide more. It is +hoped that the approach adopted will be sufficiently flexible and +extensible to accommodate most systems. Implementations may be +expected to introduce new format specifiers. +.LP +The default output should consist of a short listing containing the +process ID, terminal name, cumulative execution time, and +command name of each process. +.LP +The preference of the standard developers would have been to make +the format specification an operand of the \fIps\fP command. +Unfortunately, BSD usage precluded this. +.LP +At one time a format was included to display the environment array +of the process. This was deleted because there is no portable +way to display it. +.LP +The \fB-A\fP option is equivalent to the BSD \fB-g\fP and the SVID +\fB-e\fP. Because the two systems differed, a mnemonic +compromise was selected. +.LP +The \fB-a\fP option is described with some optional behavior because +the SVID omits session leaders, but BSD does not. +.LP +In an early proposal, format specifiers appeared for priority and +start time. The former was not defined adequately in this +volume of IEEE\ Std\ 1003.1-2001 and was removed in deference to the +defined nice value; the latter because elapsed time +was considered to be more useful. +.LP +In a new BSD version of \fIps\fP, a \fB-O\fP option can be used to +write all of the default information, followed by +additional format specifiers. This was not adopted because the default +output is implementation-defined. Nevertheless, this is a +useful option that should be reserved for that purpose. In the \fB-o\fP +option for the POSIX Shell and Utilities \fIps\fP, the +format is the concatenation of each \fB-o\fP. Therefore, the user +can have an alias or function that defines the beginning of +their desired format and add more fields to the end of the output +in certain cases where that would be useful. +.LP +The format of the terminal name is unspecified, but the descriptions +of \fIps\fP, \fItalk\fP, \fIwho\fP, and \fIwrite\fP require that they +all use the same format. +.LP +The \fBpcpu\fP field indicates that the CPU time available is determined +in an unspecified manner. This is because it is +difficult to express an algorithm that is useful across all possible +machine architectures. Historical counterparts to this value +have attempted to show percentage of use in the recent past, such +as the preceding minute. Frequently, these values for all +processes did not add up to 100%. Implementations are encouraged to +provide data in this field to users that will help them +identify processes currently affecting the performance of the system. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIkill\fP(), \fInice\fP(), \fIrenice\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |