| SystemTap Tapset ReferenceChapter 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. Namefunction::print_regs - Print a register dump. Synopsisfunction print_regs() DescriptionThis function prints a register dump.
Namefunction::execname - Returns the execname of a target process (or group of processes). Synopsisfunction execname:string() DescriptionReturns the execname of a target process (or group of processes).
Namefunction::pid - Returns the ID of a target process. Synopsisfunction pid:long() DescriptionThis function returns the ID of a targer process.
Namefunction::tid - Returns the thread ID of a target process. Synopsisfunction tid:long() DescriptionThis function returns the thread ID of the target process.
Namefunction::ppid - Returns the process ID of a target process's parent process. Synopsisfunction ppid:long() DescriptionThis function return the process ID of the target proccess's parent process.
Namefunction::pgrp - Returns the process group ID of the current process. Synopsisfunction pgrp:long() DescriptionThis function returns the process group ID of the current process.
Namefunction::sid - Returns the session ID of the current process. Synopsisfunction sid:long() DescriptionThe 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.
Namefunction::pexecname - Returns the execname of a target process's parent process. Synopsisfunction pexecname:string() DescriptionThis function returns the execname of a target process's parent procces.
Namefunction::gid - Returns the group ID of a target process. Synopsisfunction gid:long() DescriptionThis function returns the group ID of a target process.
Namefunction::egid - Returns the effective gid of a target process. Synopsisfunction egid:long() DescriptionThis function returns the effective gid of a target process
Namefunction::uid - Returns the user ID of a target process. Synopsisfunction uid:long() DescriptionThis function returns the user ID of the target process.
Namefunction::euid - Return the effective uid of a target process. Synopsisfunction euid:long() DescriptionReturns the effective user ID of the target process.
Namefunction::is_myproc - Determines if the current probe point has occurred in the user's own process. Synopsisfunction is_myproc:long() DescriptionThis function returns 1 if the current probe point has occurred in the user's own process.
Namefunction::cpu - Returns the current cpu number. Synopsisfunction cpu:long() DescriptionThis function returns the current cpu number.
Namefunction::pp - Returns the active probe point. Synopsisfunction pp:string() DescriptionThis 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.
Namefunction::registers_valid - Determines validity of register and u_register in current context. Synopsisfunction registers_valid:long() DescriptionThis 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.
Namefunction::user_mode - Determines if probe point occurs in user-mode. Synopsisfunction user_mode:long() General SyntaxReturn 1 if the probe point occurred in user-mode.
Namefunction::is_return - Whether the current probe context is a return probe. Synopsisfunction is_return:long() DescriptionReturns 1 if the current probe context is a return probe, returns 0 otherwise.
Namefunction::target - Return the process ID of the target process. Synopsisfunction target:long() DescriptionThis 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.
Namefunction::module_name - The module name of the current script. Synopsisfunction module_name:string() DescriptionThis 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>.
Namefunction::stp_pid - The process id of the stapio process. Synopsisfunction stp_pid:long() DescriptionThis 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.
Namefunction::stack_size - Return the size of the kernel stack. Synopsisfunction stack_size:long() DescriptionThis function returns the size of the kernel stack.
Namefunction::stack_used - Returns the amount of kernel stack used. Synopsisfunction stack_used:long() DescriptionThis function determines how many bytes are currently used in the kernel stack.
Namefunction::stack_unused - Returns the amount of kernel stack currently available. Synopsisfunction stack_unused:long() DescriptionThis function determines how many bytes are currently available in the kernel stack.
Namefunction::uaddr - User space address of current running task. EXPERIMENTAL. Synopsisfunction uaddr:long() DescriptionReturns 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.
Namefunction::cmdline_args - Fetch command line arguments from current process Synopsisfunction cmdline_args:string(n:long,m:long,delim:string) Argumentsn 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 Syntaxcmdline_args:string(n:long, m:long, delim:string) DescriptionReturns 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.
Namefunction::cmdline_arg - Fetch a command line argument. Synopsisfunction cmdline_arg:string(n:long) Argumentsn Argument to get (zero is the command itself)
General Syntaxcmdline_arg:string(n:long) DescriptionReturns 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.
Namefunction::cmdline_str - Fetch all command line arguments from current process Synopsisfunction cmdline_str:string() DescriptionReturns all arguments from the current process delimited by spaces. Returns the empty string when the arguments cannot be retrieved.
Namefunction::env_var - Fetch environment variable from current process Synopsisfunction env_var:string(name:string) Argumentsname Name of the environment variable to fetch
General Syntaxevn_var:string(name:string) DescriptionReturns the contents of the specified environment value for the current process. If the variable isn't set an empty string is returned.
Namefunction::print_stack - Print out kernel stack from string. Synopsisfunction print_stack(stk:string) Argumentsstk String with list of hexadecimal addresses.
DescriptionThis 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.
Namefunction::sprint_stack - Return stack for kernel addresses from string. EXPERIMENTAL! Synopsisfunction sprint_stack:string(stk:string) Argumentsstk String with list of hexadecimal (kernel) addresses.
DescriptionPerform 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.
Namefunction::probefunc - Return the probe point's function name, if known. Synopsisfunction probefunc:string() DescriptionThis function returns the name of the function being probed. It will do this based on the probe point string as returned by pp . Please notethis 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.
Namefunction::probemod - Return the probe point's kernel module name. Synopsisfunction probemod:string() DescriptionThis funciton returns the name of the kernel module containing the probe point, if known.
Namefunction::modname - Return the kernel module name loaded at the address. Synopsisfunction modname:string(addr:long) DescriptionReturns 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.
Namefunction::symname - Return the kernel symbol associated with the given address. Synopsisfunction symname:string(addr:long) Argumentsaddr The address to translate.
General Syntaxsymname:string(addr:long) DescriptionReturns the (function) symbol name associated with the given address if known. If not known it will return the hex string representation of addr.
Namefunction::symdata - Return the kernel symbol and module offset for the address. Synopsisfunction symdata:string(addr:long) Argumentsaddr The address to translate.
General Syntaxsymdata:string(addr:long) DescriptionReturns 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.
Namefunction::usymname - Return the symbol of an address in the current task. EXPERIMENTAL! Synopsisfunction usymname:string(addr:long) Argumentsaddr The address to translate.
DescriptionReturns the (function) symbol name associated with the given address if known. If not known it will return the hex string representation of addr.
Namefunction::usymdata - Return the symbol and module offset of an address. EXPERIMENTAL! Synopsisfunction usymdata:string(addr:long) Argumentsaddr The address to translate.
DescriptionReturns 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.
Namefunction::print_ustack - Print out stack for the current task from string. EXPERIMENTAL! Synopsisfunction print_ustack(stk:string) Argumentsstk String with list of hexadecimal addresses for the current task.
DescriptionPerform 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.
Namefunction::sprint_ustack - Return stack for the current task from string. EXPERIMENTAL! Synopsisfunction sprint_ustack:string(stk:string) Argumentsstk String with list of hexadecimal addresses for the current task.
DescriptionPerform 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.
Namefunction::print_backtrace - Print stack back trace Synopsisfunction print_backtrace() DescriptionThis function isEquivalent to print_stack( backtrace ), except that deeper stack nesting may be supported. The function does not return a value.
Namefunction::sprint_backtrace - Return stack back trace as string. EXPERIMENTAL! Synopsisfunction sprint_backtrace:string() DescriptionReturns 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).
Namefunction::backtrace - Hex backtrace of current stack Synopsisfunction backtrace:string() DescriptionThis 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).
Namefunction::task_backtrace - Hex backtrace of an arbitrary task Synopsisfunction task_backtrace:string(task:long) General Syntaxtask_backtrace:string(task:long) DescriptionThis 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.
Namefunction::caller - Return name and address of calling function Synopsisfunction caller:string() DescriptionThis 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.
Namefunction::caller_addr - Return caller address Synopsisfunction caller_addr:long() DescriptionThis function returns the address of the calling function. Works only for return probes at this time.
Namefunction::print_ubacktrace - Print stack back trace for current task. EXPERIMENTAL! Synopsisfunction print_ubacktrace() DescriptionEquivalent to print_ustack( ubacktrace ), except that deeper stack nesting may be supported. Returns nothing. NoteTo 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.
Namefunction::sprint_ubacktrace - Return stack back trace for current task as string. EXPERIMENTAL! Synopsisfunction sprint_ubacktrace:string() DescriptionReturns 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). NoteTo 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.
Namefunction::print_ubacktrace_brief - Print stack back trace for current task. EXPERIMENTAL! Synopsisfunction print_ubacktrace_brief() DescriptionEquivalent 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). NoteTo 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.
Namefunction::ubacktrace - Hex backtrace of current task stack. EXPERIMENTAL! Synopsisfunction ubacktrace:string() DescriptionReturn 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. NoteTo 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.
Namefunction::task_current - The current task_struct of the current task. Synopsisfunction task_current:long() DescriptionThis 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.
Namefunction::task_parent - The task_struct of the parent task. Synopsisfunction task_parent:long(task:long) General Syntaxtask_parent:long(task:long) DescriptionThis 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.
Namefunction::task_state - The state of the task. Synopsisfunction task_state:long(task:long) General Syntaxtask_state:long(task:long) DescriptionReturn 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).
Namefunction::task_execname - The name of the task. Synopsisfunction task_execname:string(task:long) General Syntaxtask_execname:string(task:long) DescriptionReturn the name of the given task.
Namefunction::task_pid - The process identifier of the task. Synopsisfunction task_pid:long(task:long) General Syntaxtask_pid:long (task:long) DescriptionThis fucntion returns the process id of the given task.
Namefunction::pid2task - The task_struct of the given process identifier. Synopsisfunction pid2task:long(pid:long) DescriptionReturn the task struct of the given process id.
Namefunction::pid2execname - The name of the given process identifier. Synopsisfunction pid2execname:string(pid:long) DescriptionReturn the name of the given process id.
Namefunction::task_tid - The thread identifier of the task. Synopsisfunction task_tid:long(task:long) DescriptionThis function returns the thread id of the given task.
Namefunction::task_gid - The group identifier of the task. Synopsisfunction task_gid:long(task:long) DescriptionThis function returns the group id of the given task.
Namefunction::task_egid - The effective group identifier of the task. Synopsisfunction task_egid:long(task:long) General Syntaxtask_egid:long(task:long) DescriptionThis function returns the effective group id of the given task.
Namefunction::task_uid - The user identifier of the task. Synopsisfunction task_uid:long(task:long) DescriptionThis function returns the user id of the given task.
Namefunction::task_euid - The effective user identifier of the task. Synopsisfunction task_euid:long(task:long) General Syntaxtask_euid:long(task:long) DescriptionThis function returns the effective user id of the given task.
Namefunction::task_prio - The priority value of the task. Synopsisfunction task_prio:long(task:long) General Syntaxtask_prio:long(task:long) DescriptionThis function returns the priority value of the given task.
Namefunction::task_nice - The nice value of the task. Synopsisfunction task_nice:long(task:long) General Syntaxtask_nice:long(task:long) DescriptionThis function returns the nice value of the given task.
Namefunction::task_cpu - The scheduled cpu of the task. Synopsisfunction task_cpu:long(task:long) DescriptionThis function returns the scheduled cpu for the given task.
Namefunction::task_open_file_handles - The number of open files of the task. Synopsisfunction task_open_file_handles:long(task:long) General Syntaxtask_open_file_handles:long(task:long) DescriptionThis function returns the number of open file handlers for the given task.
Namefunction::task_max_file_handles - The max number of open files for the task. Synopsisfunction task_max_file_handles:long(task:long) General Syntaxtask_max_file_handles:long(task:long) DescriptionThis function returns the maximum number of file handlers for the given task.
Namefunction::pn - Returns the active probe name. Synopsisfunction pn:string() DescriptionThis function returns the script-level probe point associated with a currently running probe handler, including wild-card expansion effects. Context: The current probe point. |
| |
|