ps — Return the status of a process

Format

ps [–Aacdefjlm] [–G idlist] [–g grouplist] [–n name] [–o format] … [–p proclist] [–s idlist] [–t termlist] [–U|u uidlist]

Description

ps displays status information about processes, and optionally, the threads running under each process.

By default, for each process that is associated with the user's terminal, ps displays the process ID (PID), TTY, processor time used (TIME), and name of the command (COMM).

The –a, –A, and –e options can be used to show information that is associated with all available or accessible processes on the system. However, these options can only show information for those processes the user has appropriate privileges to access. The –g, –G, –p, –s, –t, –u, and –U options can be used to select specific processes by process id, terminal id, and user name.

The –f, –j, and –l options can be used to display additional status fields using predefined formats. The –o format option allows the user to select specific status fields and to define the format in which these fields are displayed.

ps displays information for each thread that is associated with a process when the –m and –o THREAD options are used. Output lines for thread information immediately follow the output line for the parent process. Because the default behavior of ps displays process status fields only, to provide meaningful thread output, the –o option is used to specify thread-specific status fields. There are some conditions, such as when the process is in a terminating or zombie state, where thread data cannot be captured. In these cases, a single thread output line is displayed showing a ? in the thread output fields.

Restriction: The ps command has a limitation of 80 chars for the column args before z/OS V2R1. On V2R1 and after, the column args are updated to support 1024 chars.

Options

ps accepts several options. When a description says that ps lists “all processes”, it means all the processes on the system, if you have appropriate privileges.

The fields pcpu, nice, pri, addr, and wchan are unsupported and will always display a dash.

–A

Displays information about all available processes. You can specify –A, –a, and –e in any combination; however, –a overrides both –A and –e.

–a

Displays information about all processes that are associated with terminals. You can specify –A, –a, and –e in any combination; however, –a overrides both –A and –e.

–c

Displays more detailed information about processes for the –f and –l options. –c is accepted but not currently implemented.

–d

Displays information for all processes except group leaders.

–e

Displays information about all accessible processes. You can specify –A, –a, and –e in any combination; however, –a overrides both –A and –e.

–f

Displays information as if the user specified:

–oruser=UID –opid,ppid,pcpu=C –ostime,tty=TTY –oatime,args=CMD

–G grouplist

Displays information about processes with real group ID numbers in grouplist. Separate numbers in grouplist with either blanks or commas.

–g idlist

Displays information about processes with process ID numbers in idlist. Separate the numbers in idlist with either blanks or commas.

–j

Displays information as if the user specified:

-o pid,sid,pgid=PGRP -o tty=TTY -o atime,args

–l

Displays information as if the user had specified:

–oflags,state,ruid=UID –opid,ppid,pcpu=C –opri,nice,addr,vsz=SZ
–owchan,tty=TTY –oatime,comm=CMD

–m

Displays thread status information. Output lines for thread status immediately follow the output line for the parent process. Process-only status fields will contain dashes for thread output lines. Since the default behavior of ps is to display process-only status fields, to provide meaningful thread output, the –o option should be used to specify thread supported status fields. If –o THREAD is used, –m is assumed.

–n name

Specifies the name of the executable file containing the kernel symbol table. This option is not supported and is ignored.

–o format

Displays information according to the given format specifications. If –o is not used, the default format is the same as specifying:

–o pid,tty=TTY –o atime,comm

See Format specifications.

–p proclist

Displays information for processes with process ID numbers in proclist. Separate numbers in proclist with either blanks or commas.

–s idlist

Displays information for processes with session ID numbers in idlist. Separate the numbers in idlist with commas.

–t termlist

Displays information for processes with terminals in termlist. You denote terminals in termlist with either the file name of the device (for example, tty04). Or, if the file name begins with tty, you can specify the characters following tty. For example, tty04 and 04 both denote the same terminal. Terminals in termlist are separated by either blanks or commas.

–U userlist

Displays information for processes with user IDs in userlist. Items in userlist can be user ID numbers or login names, and are separated by commas.

–u userlist

Displays information for processes with user IDs in userlist. Items in userlist can be user ID numbers or login names, and are separated by commas.

Format specifications

Using the –o option, the user can define the status fields that are displayed and their column headings. If you do not specify the –o option, ps displays the information as though you specified:

-o pid,tty=TTY -o atime,comm

The format specification is a list of status field names that are separated with blanks or commas. However, if the list of names is separated by blanks, the list must be contained in single quotation marks. The following list shows the status field names that are recognized by ps.

Multiple –o format specifications can be provided and, in the case where user-specified column headings are defined, these specifications might be necessary.

The first line of ps output contains column headings for each status field. Each status field has a default heading which can be overridden by the user by specifying =newheading after the status field. When a new heading is specified, it must be the last field given on the –o option. To specify additional fields, it is necessary to use additional –o statements.

For example, if you want to display the process ID (pid), real user name (ruser), and command name (comm), but change the heading for the real user name from the default of (RUSER) to WHO, use:

-o pid,ruser=WHO -o comm

An additional –o is required when comm is specified because the last argument must be user-specified headings (in this case ruser=WHO).

If you specify = with no heading, ps displays that column without a heading. If none of the columns have a heading, ps displays no heading line.

In a double-byte locale, user-defined headings might contain multibyte (double-byte) characters.

The following list shows the names that ps recognizes. The list is separated into three groups:

process only: These are fields that only display meaningful data for process output lines. For thread output lines, a dash is shown in these fields.
thread only: These are fields that only display meaningful data for thread output lines. For process output lines, a dash is shown in these fields.
processes and threads: These are fields that apply to both processes and threads. For example, state is meaningful because both processes and threads have a state that can be determined for them.

At the end of each description, the default column heading is inside square brackets.

The Process Only group:

addr

Displays the address of the process. This field is not supported and will display a dash. [ADDR]

args

Displays the command that is running, with all its arguments. [COMMAND]

atime

Displays the amount of processor time that the process has used since it began running. Time is displayed in one of the following abbreviated formats:

days d hours
hours h minutes
minutes : seconds

depending on the amount of processor time used. [TIME]

attr

Displays the process attributes. [ATTR]

The following values might be displayed:

B: Shutdown blocking process; will prevent the shutdown from proceeding until it either de-registers as a blocking process or ends.
For more information about the B attribute, see z/OS UNIX System Services Planning.
P: Permanent process; will survive across a shutdown.
For more information about the P attribute, see z/OS UNIX System Services Planning.
R: Respawnable process; will be restarted when it ends.
For more information about the R attribute, see z/OS UNIX System Services Planning.
T: Tracing is active.
For more information about tracing, see bpxtrace — Activate or deactivate traces for processes.

comm

Displays the name of the command that is running without its arguments. This string is padded on the right if necessary. [COMMAND]

etime

Displays the amount of real time that has elapsed since the process began running. ps shows the time in the form:

[dd-]hh:mm:ss

where dd is the number of days, hh is the number of hours, mm is the number of minutes, and ss is the number of seconds. [ELAPSED]

gid

Displays the effective group ID of the process. [EGID]

group

Displays the effective group ID of the process, as a group name if possible and as a decimal group ID if not. [GROUP]

jobname

Displays the job name. [JOBNAME]

nice

Displays the nice value (urgency) of the process as a decimal value. This field is not supported and will display a dash. [NI]

pcpu

Displays a percentage value giving the ratio of processor time used to processor time available. This field is not supported and will display a dash. [%CPU]

pgid

Displays the process group ID as a decimal value. [PGID]

pid

Displays the process ID as a decimal value. Decimal pids are reported with default actions. [XPID]

ppid

Displays the parent process ID as a decimal value. [PPID]

pri

Displays the process priority. This field is not supported and will display a dash. [PRI]

rgid

Displays the real group ID of the process. [GID]

rgroup

Displays the real group ID of the process, as a group name if possible and as a decimal group ID if not. [RGROUP]

ruid

Displays the real user ID of the process. [UID]

ruser

Displays the real user ID of the process, as a user name if possible and as a decimal user ID otherwise. [RUSER]

sid

Displays the session ID of the process. [SID]

stime

Displays the start time of the process. [STIME]

thdcnt

Displays the total number of threads. [THCNT]

time

Displays the amount of processor time that the process has used since it began running. ps displays this time in form similar to that used by etime. [TIME]

tty

Displays the name of the controlling terminal (if any). [TT]

uid

Displays the effective user ID of the process. [EUID]

user

Displays the effective user ID of the process, as a user name if possible and as a decimal user ID otherwise. [USER]

vsz

Displays the amount of (virtual) memory that the process is using, as a decimal number of kilobytes. [VSZ]

vszlmt64

Displays the maximum amount of virtual storage above the 2–gigabyte bar allowed for the current process[VSZLMT64].

When displayed, each value will be followed by a multiplier indicating the units represented:

     (space)	No multiplier
     K			Kilo
     M			Mega
     G			Giga
     T			Tera
     P			Peta

For example:

> ps -o comm,vsz64,vszlmt64

COMMAND      VSZ64   VSZLMT64
/bin/sh          0          0 
/loop_64       100     16383P

vsz64

Displays the virtual storage used above the 2–gigabyte bar[VSZ64].

When displayed, each value will be followed by a multiplier indicating the units represented:

     (space)	No multiplier
     K			Kilo
     M			Mega
     G			Giga
     T			Tera
     P			Peta

For example:

> ps -o comm,vsz64,vszlmt64

COMMAND      VSZ64   VSZLMT64
/bin/sh          0          0 
/loop_64       100     16383P

wchan

Displays the channel upon which the process is waiting. This field is currently not supported and will display a dash. [WCHAN]

xasid

Displays the address space ID as a hexadecimal value (Note: a non-hexadecimal ASID is not supported). [ASID]

xpgid

Displays the process group ID as a hexadecimal value. [XPGID]

xpid

Displays the process ID as a hexadecimal value. [XPID]

xppid

Displays the parent process ID as a hexadecimal value. [XPPID]

xsid

Displays the session ID as a hexadecimal value. [XSID]

The Thread Only group:

lpid

Displays the latch pid waited for. [lpid]

lsyscall

Displays the last five syscalls. This is a 20 character string consisting of five four character syscalls with no delimiting characters between them. From left-to-right the syscalls are ordered from most recent to oldest. In the following example of lsyscall output, 1WAT is the most recent syscall: 1WAT1SPM1SPM1SPM1TSP. [LASTSYSC]

semnum

Displays the semaphore number of the semaphore the thread is in a wait state for. (Note: a semaphore number is only available when the thread is in a semaphore wait state (state field value equals d), otherwise, a dash will be displayed). [SNUM]

semval

Displays the semaphore value of the semaphore the thread is in a wait state for. (Note: a semaphore value is only available when the thread is in a semaphore wait state (state field value equals D), otherwise, a dash will be displayed). [SVAL]

sigmask

Displays the signal pending mask as a hexadecimal value. [SIGMASK]

syscall

Displays the current syscall (for example, 1frk for fork). [SYSC]

tagdata

Displays the tag assigned to the thread using pthread_tag_np(). If a tag was not assigned, a dash is displayed. [TAGDATA]

wtime

Displays waiting time in one of the following abbreviated formats:

days d hours
hours h minutes
minutes : seconds

depending on the amount of waiting time to display. [TIME]

xtcbaddr

Displays the tcb address as a hexadecimal value. A non-hexadecimal tcb address is not supported. [TCBADDR]

xstid

Displays the short thread ID as a hexadecimal value. This is the low order word (the sequential value) of the thread ID. A non-hexadecimal short thread ID is not supported. [STID]

xtid

Displays thread ID as a hexadecimal value. A non-hexadecimal thread ID is not supported. [TID]

The Processes and Threads group:

flags

Displays the state field values using a hexadecimal representation. flags is the four-byte value determined when a bit is set to one for each corresponding state that is active. Below is the state-to-state bit mapping for the currently defined state values:

 Byte    0        1        2        3
 Bits 11111111 11111111 11111111 11010000
      -------- -------- -------- --------
state ABCDEFG   JK  NO   RS UVWX YZ 1

For example, if a thread or process had a state field value of 1W, then the following bits would be set:

 Byte    0        1        2        3
 Bits 00000000 00000000 00000010 00010000
      -------- -------- -------- --------
state

Which when represented as a hexadecimal value would be 210.[F]

state

Displays the process state. [STATE] Various values can be printed in this field:

1: A single task using assembler callable services.
A: Message queue receive wait.
B: Message queue send wait.
C: Communication system kernel wait.
D: Semaphore operation wait.
E: Quiesce frozen.
F: File system kernel wait.
G: MVS™ Pause wait.
H: One or more pthread created tasks (implies M as well).
I: Swapped out.
J: Pthread created.
K: Other kernel wait (for example, pause or sigsuspend).
L: Canceled, parent has performed wait, and still session or process group leader.
M: Multithread.
N: Medium weight thread.
O: Asynchronous thread.
P: Ptrace kernel wait.
R: Running (not kernel wait).
S: Sleeping.
T: Stopped.
U: Initial process thread.
V: Thread is detached.
W: Waiting for a child (wait or waitpid function is running).
X: Creating a new process (fork function is running).
Y: MVS wait.
Z: Canceled and parent has not performed wait (Z for zombie).

THREAD

THREAD [THREAD] is a synonym for specifying the following fields:

-m -o ruser=UID -o pid,ppid,xstid,state=STATE -o atime,syscall,args=CMD

The following is an example of how this output will appear:

    UID        PID       PPID      STID   STATE  TIME   SYSC   CMD
WELLIE8    67108867  15099496         -   1W     0:25   -      sh -L
      -           -         -  00000002   W      0:17   1WAT   -
WELLIE8  1073741830   67108867        -   1Y     0:00   -      ./ps -o THREAD
      -           -         -  00000000   Y      0:00   1GTH   -

Environment variables

ps uses the following environment variable:

COLUMNS: Contains the maximum number of columns to display on one line.

Localization

ps uses the following localization environment variables:

LANG
LC_ALL
LC_CTYPE
LC_MESSAGES
LC_TIME
NLSPATH

See Localization for more information.

Exit values

0

Successful completion

1

Failure due to the inability to open the process table

2

Failure due to any of the following reasons:

Unknown command-line option
Missing format string after –o
Missing lists after other options
Too many arguments on the command line

Portability

POSIX.2 User Portability Extension, X/Open Portability Guide.

The –c, –d, –e, –f, –g, –j, –l, –m, –n, –s, and –u options are extensions of the POSIX standard.

Related information

jobs, kill