A. Introduction

This document proposes the addition of several interfaces to DTrace
(PSARC 2001/466) to be made as an addendum to the Zones Project (PSARC
2002/174); these interfaces help to provide the kind of cross-project
integration that our customers will appreciate.  Additionally, an edit
is made to the dtrace(1M) API in order to plan for future expansion.

This case seeks minor release binding, and is to be delivered
concurrently with the Zones project.  Existing interfaces are modified,
but none of these interfaces have yet reached customer exposure, except
via Software Express.  Please refer to Section D for a full discussion.

B. "zonename" variable

Section 3.5 of PSARC/2001/466 (DTrace) describes the "execname" variable
which is the name of the process provided to exec(2).  "execname"
provides a convenient method for tracing selected processes; to trace
every system call by every httpd process:

	# dtrace -n syscall:::'/execname=="httpd"/{}'

This case seeks to add a similar "zonename" variable, which maps to the
name of the Zone of the current process context; to trace every
system call made by a particular zone:

	# dtrace -n syscall:::'/zonename=="my-zone"/{}'

The significant advantage of having a "zonename" variable is that it is
consistent across reboot of the zone, while the zone's ZoneID will change.
The "zonename" string variable is declared to have DTrace interface
attributes of Stable/Stable/Common (See PSARC/2001/466 Sect. 24 for
more details).

C. curpsinfo->pr_zoneid variable

Sections 3.5 and 7.2 of PSARC/2001/466 (DTrace) describe the "curpsinfo"
variable which is exported by DTrace.  This variable is a representation
of the psinfo_t structure described in proc(4).  Because the zones
project is adding a new member to the psinfo_t structure (pr_zoneid),
this case seeks to include that new variable for use via
"curpsinfo->pr_zoneid".  The pr_zoneid field is equal to the zoneid of the
process in question.  The "curpsinfo->pr_zoneid" variable is declared to
have DTrace interface attributes of Stable/Stable/Common (See
PSARC/2001/466 Sect. 24 for more details).

D. 'dtrace -z' redefinition

The zones project has added the -z <zonename> option to a number of
utilities concerned with system observability, including
prstat(1M), pgrep(1), ipcs(1), ptree(1) and ps(1); in these commands,
-z allows the user to filter the information presented to include only
the zone or zones specified.

After consultation with the DTrace I-team, this case seeks to rename
the current dtrace '-z' option to make room for filtering by zones in
a future enhancement.  The current -z option is documented as follows:

    -z	Permit probe descriptions that match zero probes. If the -z
	option is not specified, dtrace will report an error and exit if
	any probe descriptions specified in D program files (-s option)
	or on the command-line (-P, -m, -f, -n, or -i options) contain
	descriptions that do not match any known probes.

This case proposes to rename the '-z' option to '-Z' and leave '-z' for
future expansion.  Despite the exposure of '-z' in Software Express, the
Zones and DTrace I-teams feel that this change will be the right thing
for our customers in the long term for overall consistency.

The DTrace manual page, answerbook, and usage message will be updated
accordingly.