Arguments

Arguments
Prev	Chapter 25. `proc` Provider	Next

The argument types for the proc probes are listed in Table 25–2. The arguments are described in Table 25–1.

Table 25.2. proc Probe Arguments

Probe	`args[0]`	`args[1]`	`args[2]`
`create`	`psinfo_t *`	—	—
`exec`	`char *`	—	—
`exec-failure`	`int`	—	—
`exit`	`int`	—	—
`fault`	`int`	`siginfo_t *`	—
`lwp-create`	`lwpsinfo_t *`	`psinfo_t *`	—
`lwp-start`	—	—	—
`lwp-exit`	—	—	—
`signal-discard`	`lwpsinfo_t *`	`psinfo_t *`	`int`
`signal-discard`	`lwpsinfo_t *`	`psinfo_t *`	`int`
`signal-send`	`lwpsinfo_t *`	`psinfo_t *`	`int`
`signal-handle`	`int`	`siginfo_t *`	`void (*)(void)`
`signal-clear`	`int`	—	—
`start`	—	—	—

`lwpsinfo_t`

Several proc probes have arguments of type lwpsinfo_t, a structure that is documented in proc ( 4 ) . The definition of the lwpsinfo_t structure as available to DTrace consumers is as follows:

typedef struct lwpsinfo {
	int pr_flag;              /* flags; see below */
	id_t pr_lwpid;            /* LWP id */
	uintptr_t pr_addr;        /* internal address of thread */
	uintptr_t pr_wchan;       /* wait addr for sleeping thread */
	char pr_stype;            /* synchronization event type */
	char pr_state;            /* numeric thread state */
	char pr_sname;            /* printable character for pr_state */
	char pr_nice;             /* nice for cpu usage */
	short pr_syscall;         /* system call number (if in syscall) */
	int pr_pri;               /* priority, high value = high priority */
	char pr_clname[PRCLSZ];   /* scheduling class name */
	processorid_t pr_onpro;   /* processor which last ran this thread */
	processorid_t pr_bindpro; /* processor to which thread is bound */
	psetid_t pr_bindpset;     /* processor set to which thread is bound */
} lwpsinfo_t;

The pr_flag field is a bit-mask holding flags describing the process. These flags and their meanings are described in Table 25–3.

Table 25.3. pr_flag Values

`PR_ISSYS`	The process is a system process.
`PR_VFORKP`	The process is the parent of a vfork ( 2 ) 'd child.
`PR_FORK`	The process has its inherit-on-fork mode set.
`PR_RLC`	The process has its run-on-last-close mode set.
`PR_KLC`	The process has its kill-on-last-close mode set.
`PR_ASYNC`	The process has its asynchronous-stop mode set.
`PR_MSACCT`	The process has microstate accounting enabled.
`PR_MSFORK`	The process microstate accounting is inherited on fork.
`PR_BPTADJ`	The process has its breakpoint adjustment mode set.
`PR_PTRACE`	The process has its ptrace ( 3 ) -compatibility mode set.
`PR_STOPPED`	The thread is an LWP that is stopped.
`PR_ISTOP`	The thread is an LWP stopped on an event of interest.
`PR_DSTOP`	The thread is an LWP that has a stop directive in effect.
`PR_STEP`	The thread is an LWP that has a single-step directive in effect.
`PR_ASLEEP`	The thread is an LWP in an interruptible sleep within a system call.
`PR_DETACH`	The thread is a detached LWP. See pthread_create ( 3 ) and pthread_join ( 3 ) .
`PR_DAEMON`	The thread is a daemon LWP. See pthread_create ( 3 ) .
`PR_AGENT`	The thread is the agent LWP for the process.
`PR_IDLE`	The thread is the idle thread for a CPU. Idle threads only run on a CPU when the run queues for the CPU are empty.

The pr_addr field is the address of a private, in-kernel data structure representing the thread. While the data structure is private, the pr_addr field may be used as a token unique to a thread for the thread's lifetime.

The pr_wchan field is set when the thread is sleeping on a synchronization object. The meaning of the pr_wchan field is private to the kernel implementation, but the field may be used as a token unique to the synchronization object.

The pr_stype field is set when the thread is sleeping on a synchronization object. The possible values for the pr_stype field are in Table 25–4.

Table 25.4. pr_stype Values

`SOBJ_MUTEX`	Kernel mutex synchronization object. Used to serialize access to shared data regions in the kernel. See Chapter 18, `lockstat` Provider and mutex_init ( 9F ) for details on kernel mutex synchronization objects.
`SOBJ_RWLOCK`	Kernel readers/writer synchronization object. Used to synchronize access to shared objects in the kernel that can allow multiple concurrent readers or a single writer. See Chapter 18, `lockstat` Provider and rwlock ( 9F ) for details on kernel readers/writer synchronization objects.
`SOBJ_CV`	Condition variable synchronization object. A condition variable is designed to wait indefinitely until some condition becomes true. Condition variables are typically used to synchronize for reasons other than access to a shared data region, and are the mechanism generally used when a process performs a program-directed indefinite wait. For example, blocking in poll ( 2 ) , pause ( 2 ) , wait ( 3C ) , and the like.
`SOBJ_SEMA`	Semaphore synchronization object. A general-purpose synchronization object that – like condition variable objects – does not track a notion of ownership. Because ownership is required to implement priority inheritance in the Solaris kernel, the lack of ownership inherent in semaphore objects inhibits their widespread use. See semaphore ( 9F ) for details.
`SOBJ_USER`	A user-level synchronization object. All blocking on user-level synchronization objects is handled with `SOBJ_USER` synchronization objects. User-level synchronization objects include those created with mutex_init ( 3 ) , sema_init ( 3C ) , rwlock_init ( 3C ) , cond_init ( 3C ) and their POSIX equivalents.
`SOBJ_USER_PI`	A user-level synchronization object that implements priority inheritance. Some user-level synchronization objects that track ownership additionally allow for priority inheritance. For example, mutex objects created with pthread_mutex_init ( 3 ) may be made to inherit priority using pthread_mutexattr_setprotocol ( 3 ) .
`SOBJ_SHUTTLE`	A shuttle synchronization object. Shuttle objects are used to implement doors. See door_create(3DOOR) for more information.

The pr_state field is set to one of the values in Table 25–5. The pr_sname field is set to a corresponding character shown in parentheses in the same table.

Table 25.5. pr_state Values

`SSLEEP` (`S`)	The thread is sleeping. The `sched:::sleep` probe will fire immediately before a thread's state is transitioned to `SSLEEP`.
`SRUN` (`R`)	The thread is runnable, but is not currently running. The `sched:::enqueue` probe will fire immediately before a thread's state is transitioned to `SRUN`.
`SZOMB` (`Z`)	The thread is a zombie LWP.
`SSTOP` (`T`)	The thread is stopped, either due to an explicit proc ( 4 ) directive or some other stopping mechanism.
`SIDL` (`I`)	The thread is an intermediate state during process creation.
`SONPROC` (`O`)	The thread is running on a CPU. The `sched:::on-cpu` probe will fire in the context of the `SONPROC` thread a short time after the thread's state is transitioned to `SONPROC`.

`psinfo_t`

Several proc probes have an argument of type psinfo_t, a structure that is documented in proc ( 4 ) . The definition of the psinfo_t structure as available to DTrace consumers is as follows:

typedef struct psinfo {
	int     pr_nlwp;            /* number of active lwps in the process */
	pid_t   pr_pid;             /* unique process id */
	pid_t   pr_ppid;            /* process id of parent */
	pid_t   pr_pgid;            /* pid of process group leader */
	pid_t   pr_sid;             /* session id */
	uid_t   pr_uid;             /* real user id */
	uid_t   pr_euid;            /* effective user id */
	gid_t   pr_gid;             /* real group id */
	gid_t   pr_egid;            /* effective group id */
	uintptr_t pr_addr;          /* address of process */
	dev_t   pr_ttydev;          /* controlling tty device (or PRNODEV) */
	timestruc_t pr_start;       /* process start time, from the epoch */
	char    pr_fname[PRFNSZ];   /* name of execed file */
	char    pr_psargs[PRARGSZ]; /* initial characters of arg list */
	int     pr_argc;            /* initial argument count */
	uintptr_t pr_argv;          /* address of initial argument vector */
	uintptr_t pr_envp;          /* address of initial environment vector */
	char    pr_dmodel;          /* data model of the process */
	taskid_t pr_taskid;         /* task id */
	projid_t pr_projid;         /* project id */
	poolid_t pr_poolid;         /* pool id */
	zoneid_t pr_zoneid;         /* zone id */
} psinfo_t;

The pr_dmodel field is set to either PR_MODEL_ILP32, denoting a 32–bit process, or PR_MODEL_LP64, denoting a 64–bit process.