[apple/system_cmds.git] / lsmp.tproj / lsmp.1

.\" Copyright (c) 2012, Apple Inc.  All rights reserved.
.\"
.Dd Jul 24, 2012
.Dt LSMP 1
.Os "Mac OS X"
.Sh NAME
.Nm lsmp
.Nd Display mach port information for processes on the system
.Sh SYNOPSIS
.Nm lsmp
.Fl h
.Pp
.Nm lsmp
.Ar -p <pid>
Show mach port usage for <pid>. Run with root privileges to see detailed info about port destinations etc.
.Pp
.Nm lsmp
.Ar -v
Show information in detail for Kernel object based ports. Including thread ports and special ports attached to it.
.Pp
.Nm lsmp
.Ar -a
Show mach port usage for all tasks in the system
.Pp
.Nm lsmp
.Ar -j <path>
Save output as JSON to <path>.
.Sh DESCRIPTION
The
.Nm lsmp
 command prints information about every active right in a task's port space, giving a view into the inter-process communication behavior of that task.
.P
.nf
Following is an explanation of each symbol and values from the output.
name        : Task unique name for a port. A "-" signifies that this is a member of a port-set
ipc-object  : A unique identifier for a kernel object. A "+" sign implies that this entry is expanded from above ipc-object.
rights      : Rights corresponding to this name. Possible values are recv, send, send-once and port-set.
flags       : Flags indicating port status.
                T : Port has tempowner set
                G : Port is guarded
                S : Port has strict guarding restrictions
                I : Port has importance donation flag set
                R : Port is marked reviving
                P : Port has task pointer set
boost       : Importance boost count
reqs        : Notifications armed on this port.
                D : Dead name notification
                N : No sender notification
                P : Port Destroy requests
recv        : Number of recv rights for this name.
send        : Number of send rights stored at this name. This does NOT reflect the total number of send rights for this recv right.
sonce       : Number of outstanding send-once rights for this receive right.
oref        : Do send rights exist somewhere for this receive right?
qlimit      : Queue limit for this port. If orefs column shows -> then it indicates the queue limit on the destination port. And a <- indicates this port right is destined to receive messages from process referred in identifier column.
msgcount    : Number of messages enqueued on this port. See qlimit for -> and <- explanations.
context     : Mach port context value.
identifier  : A unique identifier for a kernel object or task's name for this right. This field is described by the type column.
.fi
.Sh SEE ALSO
.Xr ddt 1
.Xr top 1
Commit	Line	Data
fc6d9e4b A	1	.\" Copyright (c) 2012, Apple Inc. All rights reserved.
	2	.\"
	3	.Dd Jul 24, 2012
	4	.Dt LSMP 1
	5	.Os "Mac OS X"
	6	.Sh NAME
	7	.Nm lsmp
	8	.Nd Display mach port information for processes on the system
	9	.Sh SYNOPSIS
	10	.Nm lsmp
	11	.Fl h
	12	.Pp
	13	.Nm lsmp
1a7e3f61 A	14	.Ar -p <pid>
1a7e3f61 A	15	Show mach port usage for <pid>. Run with root privileges to see detailed info about port destinations etc.
fc6d9e4b A	16	.Pp
fc6d9e4b A	17	.Nm lsmp
1a7e3f61 A	18	.Ar -v
	19	Show information in detail for Kernel object based ports. Including thread ports and special ports attached to it.
	20	.Pp
	21	.Nm lsmp
	22	.Ar -a
fc6d9e4b	23	Show mach port usage for all tasks in the system
887d5eed A	24	.Pp
	25	.Nm lsmp
	26	.Ar -j <path>
	27	Save output as JSON to <path>.
fc6d9e4b A	28	.Sh DESCRIPTION
	29	The
	30	.Nm lsmp
	31	command prints information about every active right in a task's port space, giving a view into the inter-process communication behavior of that task.
	32	.P
	33	.nf
	34	Following is an explanation of each symbol and values from the output.
	35	name : Task unique name for a port. A "-" signifies that this is a member of a port-set
	36	ipc-object : A unique identifier for a kernel object. A "+" sign implies that this entry is expanded from above ipc-object.
	37	rights : Rights corresponding to this name. Possible values are recv, send, send-once and port-set.
	38	flags : Flags indicating port status.
	39	T : Port has tempowner set
	40	G : Port is guarded
	41	S : Port has strict guarding restrictions
	42	I : Port has importance donation flag set
	43	R : Port is marked reviving
	44	P : Port has task pointer set
	45	boost : Importance boost count
	46	reqs : Notifications armed on this port.
	47	D : Dead name notification
	48	N : No sender notification
	49	P : Port Destroy requests
	50	recv : Number of recv rights for this name.
	51	send : Number of send rights stored at this name. This does NOT reflect the total number of send rights for this recv right.
	52	sonce : Number of outstanding send-once rights for this receive right.
	53	oref : Do send rights exist somewhere for this receive right?
	54	qlimit : Queue limit for this port. If orefs column shows -> then it indicates the queue limit on the destination port. And a <- indicates this port right is destined to receive messages from process referred in identifier column.
	55	msgcount : Number of messages enqueued on this port. See qlimit for -> and <- explanations.
	56	context : Mach port context value.
	57	identifier : A unique identifier for a kernel object or task's name for this right. This field is described by the type column.
	58	.fi
	59	.Sh SEE ALSO
	60	.Xr ddt 1
	61	.Xr top 1