Chapter 3. Context Functions
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
Description
This function returns the current cpu number.
Name
function::pp — Returns the active probe point.
Synopsis
function 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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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)
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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)
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)
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()
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.
