Product SiteDocumentation Site

Chapter 3. Context Functions

function::print_regs — Print a register dump.
function::execname — Returns the execname of a target process (or group of processes).
function::pid — Returns the ID of a target process.
function::tid — Returns the thread ID of a target process.
function::ppid — Returns the process ID of a target process's parent process.
function::pgrp — Returns the process group ID of the current process.
function::sid — Returns the session ID of the current process.
function::pexecname — Returns the execname of a target process's parent process.
function::gid — Returns the group ID of a target process.
function::egid — Returns the effective gid of a target process.
function::uid — Returns the user ID of a target process.
function::euid — Return the effective uid of a target process.
function::is_myproc — Determines if the current probe point has occurred in the user's own process.
function::cpu — Returns the current cpu number.
function::pp — Returns the active probe point.
function::registers_valid — Determines validity of register and u_register in current context.
function::user_mode — Determines if probe point occurs in user-mode.
function::is_return — Whether the current probe context is a return probe.
function::target — Return the process ID of the target process.
function::module_name — The module name of the current script.
function::stp_pid — The process id of the stapio process.
function::stack_size — Return the size of the kernel stack.
function::stack_used — Returns the amount of kernel stack used.
function::stack_unused — Returns the amount of kernel stack currently available.
function::uaddr — User space address of current running task. EXPERIMENTAL.
function::cmdline_args — Fetch command line arguments from current process
function::cmdline_arg — Fetch a command line argument.
function::cmdline_str — Fetch all command line arguments from current process
function::env_var — Fetch environment variable from current process
function::print_stack — Print out kernel stack from string.
function::sprint_stack — Return stack for kernel addresses from string. EXPERIMENTAL!
function::probefunc — Return the probe point's function name, if known.
function::probemod — Return the probe point's kernel module name.
function::modname — Return the kernel module name loaded at the address.
function::symname — Return the kernel symbol associated with the given address.
function::symdata — Return the kernel symbol and module offset for the address.
function::usymname — Return the symbol of an address in the current task. EXPERIMENTAL!
function::usymdata — Return the symbol and module offset of an address. EXPERIMENTAL!
function::print_ustack — Print out stack for the current task from string. EXPERIMENTAL!
function::sprint_ustack — Return stack for the current task from string. EXPERIMENTAL!
function::print_backtrace — Print stack back trace
function::sprint_backtrace — Return stack back trace as string. EXPERIMENTAL!
function::backtrace — Hex backtrace of current stack
function::task_backtrace — Hex backtrace of an arbitrary task
function::caller — Return name and address of calling function
function::caller_addr — Return caller address
function::print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!
function::sprint_ubacktrace — Return stack back trace for current task as string. EXPERIMENTAL!
function::print_ubacktrace_brief — Print stack back trace for current task. EXPERIMENTAL!
function::ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!
function::task_current — The current task_struct of the current task.
function::task_parent — The task_struct of the parent task.
function::task_state — The state of the task.
function::task_execname — The name of the task.
function::task_pid — The process identifier of the task.
function::pid2task — The task_struct of the given process identifier.
function::pid2execname — The name of the given process identifier.
function::task_tid — The thread identifier of the task.
function::task_gid — The group identifier of the task.
function::task_egid — The effective group identifier of the task.
function::task_uid — The user identifier of the task.
function::task_euid — The effective user identifier of the task.
function::task_prio — The priority value of the task.
function::task_nice — The nice value of the task.
function::task_cpu — The scheduled cpu of the task.
function::task_open_file_handles — The number of open files of the task.
function::task_max_file_handles — The max number of open files for the task.
function::pn — Returns the active probe name.
The context functions provide additional information about where an event occurred. These functions can provide information such as a backtrace to where the event occurred and the current register values for the processor.

Name

function::print_regs — Print a register dump.

Synopsis

function print_regs()

Arguments

None

General Syntax

print_regs

Description

This function prints a register dump.

Name

function::execname — Returns the execname of a target process (or group of processes).

Synopsis

function execname:string()

Arguments

None

General Syntax

execname:string

Description

Returns the execname of a target process (or group of processes).

Name

function::pid — Returns the ID of a target process.

Synopsis

function pid:long()

Arguments

None

General Syntax

pid:long

Description

This function returns the ID of a targer process.

Name

function::tid — Returns the thread ID of a target process.

Synopsis

function tid:long()

Arguments

None

General Syntax

tid:long

Description

This function returns the thread ID of the target process.

Name

function::ppid — Returns the process ID of a target process's parent process.

Synopsis

function ppid:long()

Arguments

None

General Syntax

ppid:long

Description

This function return the process ID of the target proccess's parent process.

Name

function::pgrp — Returns the process group ID of the current process.

Synopsis

function pgrp:long()

Arguments

None

General Syntax

pgrp:long

Description

This function returns the process group ID of the current process.

Name

function::sid — Returns the session ID of the current process.

Synopsis

function sid:long()

Arguments

None

General Syntax

sid:long

Description

The session ID of a process is the process group ID of the session leader. Session ID is stored in the signal_struct since Kernel 2.6.0.

Name

function::pexecname — Returns the execname of a target process's parent process.

Synopsis

function pexecname:string()

Arguments

None

General Syntax

pexecname:string

Description

This function returns the execname of a target process's parent procces.

Name

function::gid — Returns the group ID of a target process.

Synopsis

function gid:long()

Arguments

None

General Syntax

gid:long

Description

This function returns the group ID of a target process.

Name

function::egid — Returns the effective gid of a target process.

Synopsis

function egid:long()

Arguments

None

General Syntax

egid:long

Description

This function returns the effective gid of a target process

Name

function::uid — Returns the user ID of a target process.

Synopsis

function uid:long()

Arguments

None

General Syntax

uid:long

Description

This function returns the user ID of the target process.

Name

function::euid — Return the effective uid of a target process.

Synopsis

function euid:long()

Arguments

None

General Syntax

euid:long

Description

Returns the effective user ID of the target process.

Name

function::is_myproc — Determines if the current probe point has occurred in the user's own process.

Synopsis

function is_myproc:long()

Arguments

None

General Syntax

is_myproc:long

Description

This function returns 1 if the current probe point has occurred in the user's own process.

Name

function::cpu — Returns the current cpu number.

Synopsis

function cpu:long()

Arguments

None

General Syntax

cpu:long

Description

This function returns the current cpu number.

Name

function::pp — Returns the active probe point.

Synopsis

function pp:string()

Arguments

None

General Syntax

pp:string

Description

This function returns the fully-resolved probe point associated with a currently running probe handler, including alias and wild-card expansion effects. Context: The current probe point.

Name

function::registers_valid — Determines validity of register and u_register in current context.

Synopsis

function registers_valid:long()

Arguments

None

General Syntax

registers_valid:long

Description

This function returns 1 if register and u_register can be used in the current context, or 0 otherwise. For example, registers_valid returns 0 when called from a begin or end probe.

Name

function::user_mode — Determines if probe point occurs in user-mode.

Synopsis

function user_mode:long()

Arguments

None

General Syntax

user_mode:long
Return 1 if the probe point occurred in user-mode.

Name

function::is_return — Whether the current probe context is a return probe.

Synopsis

function is_return:long()

Arguments

None

General Syntax

is_return:long

Description

Returns 1 if the current probe context is a return probe, returns 0 otherwise.

Name

function::target — Return the process ID of the target process.

Synopsis

function target:long()

Arguments

None

General Syntax

target:long

Description

This function returns the process ID of the target process. This is useful in conjunction with the -x PID or -c CMD command-line options to stap. An example of its use is to create scripts that filter on a specific process.

Name

function::module_name — The module name of the current script.

Synopsis

function module_name:string()

Arguments

None

General Syntax

module_name:string

Description

This function returns the name of the stap module. Either generated randomly (stap_[0-9a-f]+_[0-9a-f]+) or set by stap -m <module_name>.

Name

function::stp_pid — The process id of the stapio process.

Synopsis

function stp_pid:long()

Arguments

None

General Syntax

stp_pid:long

Description

This function returns the process id of the stapio process that launched this script. There could be other SystemTap scripts and stapio processes running on the system.

Name

function::stack_size — Return the size of the kernel stack.

Synopsis

function stack_size:long()

Arguments

None

General Syntax

stack_size:long

Description

This function returns the size of the kernel stack.

Name

function::stack_used — Returns the amount of kernel stack used.

Synopsis

function stack_used:long()

Arguments

None

General Syntax

stack_used:long

Description

This function determines how many bytes are currently used in the kernel stack.

Name

function::stack_unused — Returns the amount of kernel stack currently available.

Synopsis

function stack_unused:long()

Arguments

None

General Syntax

stack_unused:long

Description

This function determines how many bytes are currently available in the kernel stack.

Name

function::uaddr — User space address of current running task. EXPERIMENTAL.

Synopsis

function uaddr:long()

Arguments

None

General Syntax

uaddr:long

Description

Returns the address in userspace that the current task was at when the probe occurred. When the current running task isn't a user space thread, or the address cannot be found, zero is returned. Can be used to see where the current task is combined with usymname or symdata. Often the task will be in the VDSO where it entered the kernel. FIXME - need VDSO tracking support #10080.

Name

function::cmdline_args — Fetch command line arguments from current process

Synopsis

function cmdline_args:string(n:long,m:long,delim:string)

Arguments

n
First argument to get (zero is the command itself)
m
Last argument to get (or minus one for all arguments after n)
delim
String to use to delimit arguments when more than one.

General Syntax

cmdline_args:string(n:long, m:long, delim:string)

Description

Returns arguments from the current process starting with argument number n, up to argument m. If there are less than n arguments, or the arguments cannot be retrieved from the current process, the empty string is returned. If m is smaller than n then all arguments starting from argument n are returned. Argument zero is traditionally the command itself.

Name

function::cmdline_arg — Fetch a command line argument.

Synopsis

function cmdline_arg:string(n:long)

Arguments

n
Argument to get (zero is the command itself)

General Syntax

cmdline_arg:string(n:long)

Description

Returns argument the requested argument from the current process or the empty string when there are not that many arguments or there is a problem retrieving the argument. Argument zero is traditionally the command itself.

Name

function::cmdline_str — Fetch all command line arguments from current process

Synopsis

function cmdline_str:string()

Arguments

None

General Syntax

cmdline_str:string

Description

Returns all arguments from the current process delimited by spaces. Returns the empty string when the arguments cannot be retrieved.

Name

function::env_var — Fetch environment variable from current process

Synopsis

function env_var:string(name:string)

Arguments

name
Name of the environment variable to fetch

General Syntax

evn_var:string(name:string)

Description

Returns the contents of the specified environment value for the current process. If the variable isn't set an empty string is returned.

Name

function::print_stack — Print out kernel stack from string.

Synopsis

function print_stack(stk:string)

Arguments

stk
String with list of hexadecimal addresses.

General Syntax

print_stack(stk:string)

Description

This function performs a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to backtrace.
Print one line per address, including the address, the name of the function containing the address, and an estimate of its position within that function. Return nothing.

Name

function::sprint_stack — Return stack for kernel addresses from string. EXPERIMENTAL!

Synopsis

function sprint_stack:string(stk:string)

Arguments

stk
String with list of hexadecimal (kernel) addresses.

Description

Perform a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to backtrace.
Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name (or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from the start of the function if found, otherwise the offset will be added to the module (if found, between brackets). Returns the backtrace as string (each line terminated by a newline character). Note that the returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_stack.

Name

function::probefunc — Return the probe point's function name, if known.

Synopsis

function probefunc:string()

Arguments

None

General Syntax

probefunc:string

Description

This function returns the name of the function being probed. It will do this based on the probe point string as returned by pp.

Please note

this function is deprecated, please use symname and/or usymname. This function might return a function name based on the current address if the probe point context couldn't be parsed.

Name

function::probemod — Return the probe point's kernel module name.

Synopsis

function probemod:string()

Arguments

None

General Syntax

probemod:string

Description

This funciton returns the name of the kernel module containing the probe point, if known.

Name

function::modname — Return the kernel module name loaded at the address.

Synopsis

function modname:string(addr:long)

Arguments

addr
The address.

Description

Returns the module name associated with the given address if known. If not known it will return the string <unknown>. If the address was not in a kernel module, but in the kernel itself, then the string kernel will be returned.

Name

function::symname — Return the kernel symbol associated with the given address.

Synopsis

function symname:string(addr:long)

Arguments

addr
The address to translate.

General Syntax

symname:string(addr:long)

Description

Returns the (function) symbol name associated with the given address if known. If not known it will return the hex string representation of addr.

Name

function::symdata — Return the kernel symbol and module offset for the address.

Synopsis

function symdata:string(addr:long)

Arguments

addr
The address to translate.

General Syntax

symdata:string(addr:long)

Description

Returns the (function) symbol name associated with the given address if known, the offset from the start and size of the symbol, plus module name (between brackets). If symbol is unknown, but module is known, the offset inside the module, plus the size of the module is added. If any element is not known it will be omitted and if the symbol name is unknown it will return the hex string for the given address.

Name

function::usymname — Return the symbol of an address in the current task. EXPERIMENTAL!

Synopsis

function usymname:string(addr:long)

Arguments

addr
The address to translate.

Description

Returns the (function) symbol name associated with the given address if known. If not known it will return the hex string representation of addr.

Name

function::usymdata — Return the symbol and module offset of an address. EXPERIMENTAL!

Synopsis

function usymdata:string(addr:long)

Arguments

addr
The address to translate.

Description

Returns the (function) symbol name associated with the given address in the current task if known, the offset from the start and the size of the symbol, plus the module name (between brackets). If symbol is unknown, but module is known, the offset inside the module, plus the size of the module is added. If any element is not known it will be omitted and if the symbol name is unknown it will return the hex string for the given address.

Name

function::print_ustack — Print out stack for the current task from string. EXPERIMENTAL!

Synopsis

function print_ustack(stk:string)

Arguments

stk
String with list of hexadecimal addresses for the current task.

Description

Perform a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to ubacktrace for the current task.
Print one line per address, including the address, the name of the function containing the address, and an estimate of its position within that function. Return nothing.

Name

function::sprint_ustack — Return stack for the current task from string. EXPERIMENTAL!

Synopsis

function sprint_ustack:string(stk:string)

Arguments

stk
String with list of hexadecimal addresses for the current task.

Description

Perform a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to ubacktrace for the current task.
Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name (or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from the start of the function if found, otherwise the offset will be added to the module (if found, between brackets). Returns the backtrace as string (each line terminated by a newline character). Note that the returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_ustack.

Name

function::print_backtrace — Print stack back trace

Synopsis

function print_backtrace()

Arguments

None

General Syntax

print_backtrace

Description

This function isEquivalent to print_stack(backtrace), except that deeper stack nesting may be supported. The function does not return a value.

Name

function::sprint_backtrace — Return stack back trace as string. EXPERIMENTAL!

Synopsis

function sprint_backtrace:string()

Arguments

None

Description

Returns a simple (kernel) backtrace. One line per address. Includes the symbol name (or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from the start of the function if found, otherwise the offset will be added to the module (if found, between brackets). Returns the backtrace as string (each line terminated by a newline character). Note that the returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_backtrace. Equivalent to sprint_stack(backtrace), but more efficient (no need to translate between hex strings and final backtrace string).

Name

function::backtrace — Hex backtrace of current stack

Synopsis

function backtrace:string()

Arguments

None

General Syntax

backtrace:string

Description

This function returns a string of hex addresses that are a backtrace of the stack. Output may be truncated as as per maximum string length (MAXSTRINGLEN).

Name

function::task_backtrace — Hex backtrace of an arbitrary task

Synopsis

function task_backtrace:string(task:long)

Arguments

task
pointer to task_struct

General Syntax

task_backtrace:string(task:long)

Description

This function returns a string of hex addresses that are a backtrace of the stack of a particular task Output may be truncated as per maximum string length.

Name

function::caller — Return name and address of calling function

Synopsis

function caller:string()

Arguments

None

General Syntax

caller:string

Description

This function returns the address and name of the calling function. This is equivalent to calling: sprintf(s 0xx, symname(caller_addr, caller_addr)) Works only for return probes at this time.

Name

function::caller_addr — Return caller address

Synopsis

function caller_addr:long()

Arguments

None

General Syntax

caller_addr:long

Description

This function returns the address of the calling function. Works only for return probes at this time.

Name

function::print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!

Synopsis

function print_ubacktrace()

Arguments

None

Description

Equivalent to print_ustack(ubacktrace), except that deeper stack nesting may be supported. Returns nothing.

Note

To get (full) backtraces for user space applications and shared shared libraries not mentioned in the current script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.

Name

function::sprint_ubacktrace — Return stack back trace for current task as string. EXPERIMENTAL!

Synopsis

function sprint_ubacktrace:string()

Arguments

None

Description

Returns a simple backtrace for the current task. One line per address. Includes the symbol name (or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from the start of the function if found, otherwise the offset will be added to the module (if found, between brackets). Returns the backtrace as string (each line terminated by a newline character). Note that the returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_ubacktrace. Equivalent to sprint_ustack(ubacktrace), but more efficient (no need to translate between hex strings and final backtrace string).

Note

To get (full) backtraces for user space applications and shared shared libraries not mentioned in the current script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.

Name

function::print_ubacktrace_brief — Print stack back trace for current task. EXPERIMENTAL!

Synopsis

function print_ubacktrace_brief()

Arguments

None

Description

Equivalent to print_ubacktrace, but output for each symbol is shorter (just name and offset, or just the hex address of no symbol could be found).

Note

To get (full) backtraces for user space applications and shared shared libraries not mentioned in the current script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.

Name

function::ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!

Synopsis

function ubacktrace:string()

Arguments

None

Description

Return a string of hex addresses that are a backtrace of the stack of the current task. Output may be truncated as per maximum string length. Returns empty string when current probe point cannot determine user backtrace.

Note

To get (full) backtraces for user space applications and shared shared libraries not mentioned in the current script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.

Name

function::task_current — The current task_struct of the current task.

Synopsis

function task_current:long()

Arguments

None

General Syntax

task_current:long

Description

This function returns the task_struct representing the current process. This address can be passed to the various task_*() functions to extract more task-specific data.

Name

function::task_parent — The task_struct of the parent task.

Synopsis

function task_parent:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_parent:long(task:long)

Description

This function returns the parent task_struct of the given task. This address can be passed to the various task_*() functions to extract more task-specific data.

Name

function::task_state — The state of the task.

Synopsis

function task_state:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_state:long(task:long)

Description

Return the state of the given task, one of: TASK_RUNNING (0), TASK_INTERRUPTIBLE (1), TASK_UNINTERRUPTIBLE (2), TASK_STOPPED (4), TASK_TRACED (8), EXIT_ZOMBIE (16), EXIT_DEAD (32).

Name

function::task_execname — The name of the task.

Synopsis

function task_execname:string(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_execname:string(task:long)

Description

Return the name of the given task.

Name

function::task_pid — The process identifier of the task.

Synopsis

function task_pid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_pid:long (task:long)

Description

This fucntion returns the process id of the given task.

Name

function::pid2task — The task_struct of the given process identifier.

Synopsis

function pid2task:long(pid:long)

Arguments

pid
Process identifier.

Description

Return the task struct of the given process id.

Name

function::pid2execname — The name of the given process identifier.

Synopsis

function pid2execname:string(pid:long)

Arguments

pid
Process identifier.

Description

Return the name of the given process id.

Name

function::task_tid — The thread identifier of the task.

Synopsis

function task_tid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_tid:long(task:long)

Description

This function returns the thread id of the given task.

Name

function::task_gid — The group identifier of the task.

Synopsis

function task_gid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_gid:long(task:long)

Description

This function returns the group id of the given task.

Name

function::task_egid — The effective group identifier of the task.

Synopsis

function task_egid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_egid:long(task:long)

Description

This function returns the effective group id of the given task.

Name

function::task_uid — The user identifier of the task.

Synopsis

function task_uid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_uid:long(task:long)

Description

This function returns the user id of the given task.

Name

function::task_euid — The effective user identifier of the task.

Synopsis

function task_euid:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_euid:long(task:long)

Description

This function returns the effective user id of the given task.

Name

function::task_prio — The priority value of the task.

Synopsis

function task_prio:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_prio:long(task:long)

Description

This function returns the priority value of the given task.

Name

function::task_nice — The nice value of the task.

Synopsis

function task_nice:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_nice:long(task:long)

Description

This function returns the nice value of the given task.

Name

function::task_cpu — The scheduled cpu of the task.

Synopsis

function task_cpu:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_cpu:long(task:long)

Description

This function returns the scheduled cpu for the given task.

Name

function::task_open_file_handles — The number of open files of the task.

Synopsis

function task_open_file_handles:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_open_file_handles:long(task:long)

Description

This function returns the number of open file handlers for the given task.

Name

function::task_max_file_handles — The max number of open files for the task.

Synopsis

function task_max_file_handles:long(task:long)

Arguments

task
task_struct pointer.

General Syntax

task_max_file_handles:long(task:long)

Description

This function returns the maximum number of file handlers for the given task.

Name

function::pn — Returns the active probe name.

Synopsis

function pn:string()

Arguments

None

General Syntax

pn:string

Description

This function returns the script-level probe point associated with a currently running probe handler, including wild-card expansion effects. Context: The current probe point.