path: root/stapfuncs.3stap.in

.\" -*- nroff -*-
.TH STAPFUNCS 3stap @DATE@ "Red Hat"
.SH NAME
stapfuncs \- systemtap functions

.SH DESCRIPTION
The following sections enumerate the public functions provided by
standard tapsets installed under @prefix@/share/systemtap/tapset.  Each
function is described with a signature, and its behavior/restrictions.
The signature line includes the name of the function, the type of
its return value (if any), and the names and types of all parameters.
The syntax is the same as printed with the 
.IR stap " option " \-p2 .
Examples:

.TP
example1:long (v:string, k:long)
In function "example1", do something with the given string and integer.
Return some integer.

.TP
example2:unknown ()
In function "example2", do something.  There is no explicit return value
and take no parameters.


.SS CONVERSIONS
.PP
These functions access kernel or user-space data.  They try to validate the
supplied addresses, and can thus result in errors if the pointers are invalid,
or if a user-space access would cause a fault.
.TP
kernel_string:string (addr:long)
Copy a 0-terminated string from kernel space at given address.
.TP
kernel_string_n:string (addr:long, n:long)
Similar with kernel_string, except that not more than n bytes are copied.
Thus, if there are null bytes among the first n bytes, it is same as
kernel_string(addr). If not, n bytes will be copied and a null byte will
be padded to the end.
.TP
kernel_long:long (addr:long)
Copy a long from kernel space at given address.
.TP
kernel_int:long (addr:long)
Copy an int from kernel space at given address.
.TP
kernel_short:long (addr:long)
Copy a short from kernel space at given address.
.TP
kernel_char:long (addr:long)
Copy a char from kernel space at given address.
.TP
user_string:string (addr:long)
Copy a string from user space at given address.  If the access would
fault, return "<unknown>" and signal no errors.
.TP
user_string2:string (addr:long, err_msg:string)
Copy a string from user space at given address.  If the access would
fault, return instead the err_msg value.
.TP
user_string_warn:string (addr:long)
Copy a string from user space at given address.  If the access would
fault, signal a warning and return "<unknown>".
.TP
user_string_quoted:string (addr:long)
Copy a string from user space at given address. Any ASCII characters
that are not printable are replaced by the corresponding escape
sequence in the returned string.
.TP
user_string_n:string (addr:long, n:long)
Copy a string of n bytes from user space at given address. If the access
would fault, return "<unknown>".
.TP
user_string_n2:string (addr:long, n:long, err_msg:string)
Copy a string of n bytes from user space at given address. If the access
would fault, return the err_msg value.
.TP
user_string_n_warn:string (addr:long, n:long)
Copy a string of n bytes from user space at given address. If the access
would fault, signal a warning and return "<unknown>".
.TP
user_string_n_quoted:string (addr:long, n:long)
Copy a string of n bytes from user space at given address. Any ASCII
characters that are not printable are replaced by the corresponding escape
sequence in the returned string. If the access would fault, return "<unknown>".
.TP
user_short:long (addr:long)
Copy a short from user space at given address. If the access would fault,
return 0.
.TP
user_short_warn:long (addr:long)
Copy a short from user space at given address. If the access would fault,
signal a warning and return 0.
.TP
user_int:long (addr:long)
Copy an int from user space at given address. If the access would fault,
return 0.
.TP
user_int_warn:long (addr:long)
Copy an int from user space at given address. If the access would fault,
signal a warning and return 0.
.TP
user_long:long (addr:long)
Copy a long from user space at given address. If the access would fault,
return 0.
.TP
user_long_warn:long (addr:long)
Copy a long from user space at given address. If the access would fault,
signal a warning and return 0.
.TP
user_char:long (addr:long)
Copy a char from user space at given address. If the access would fault,
return 0.
.TP
user_char_warn:long (addr:long)
Copy a char from user space at given address. If the access would fault,
signal a warning and return 0.
.SS STRING
.TP
strlen:long (str:string)
Return the number of characters in str.
.TP
substr:string (str:string,start:long, stop:long)
Return the substring of str starting from character start and ending at character stop.
.TP
stringat:string (str:string,pos:long)
Return the character in given position of string.
.TP
isinstr:long (s1:string, s2:string)
Return 1 if string s1 contains string s2, returns 0 otherwise.
.TP
strtol:long (str:string, base:long)
Convert the string representation of a number to a long using the numbering system
specified by base.  For example, strtol("1000", 16) returns 4096.  Returns 0 if the
string cannot be converted.
.TP
tokenize:string (str:string, delim:string)
Return the next non-empty token in the given str string, where the tokens are
delimited by characters in the delim string.  If the str string is not blank,
it returns the first token.  If the str string is blank, it returns the next
token in the string passed in the previous call to tokenize. If no delimiter
is found, the entire remaining str string is returned.  Returns blank when
no more tokens are left.

.SS TIMESTAMP
.TP
get_cycles:long ()
Return the processor cycle counter value, or 0 if unavailable.
.TP
gettimeofday_ns:long ()
Return the number of nanoseconds since the UNIX epoch.
.TP
gettimeofday_us:long ()
Return the number of microseconds since the UNIX epoch.
.TP
gettimeofday_ms:long ()
Return the number of milliseconds since the UNIX epoch.
.TP
gettimeofday_s:long ()
Return the number of seconds since the UNIX epoch.

.SS CONTEXT INFO
.TP
cpu:long ()
Return the current cpu number.
.TP
execname:string ()
Return the name of the current process.
.TP
pexecname:string()
Return the name of the parent process.
.TP
tid:long ()
Return the id of the current thread.
.TP
pid:long ()
Return the id of the current process.
.TP
ppid:long ()
Return the id of the parent process.
.TP
pgrp:long ()
Return the pgrp of the current process.
.TP
sid:long ()
Return the sid of the current process.
.TP
uid:long ()
Return the uid of the current process.
.TP
euid:long ()
Return the effective uid of the current process.
.TP
gid:long ()
Return the gid of the current process.
.TP
egid:long ()
Return the effective gid of the current process.
.TP
print_regs:unknown ()
Print a register dump.
.TP
backtrace:string ()
Return a string of hex addresses that are a backtrace of the stack.
It may be truncated due to maximum string length.
.TP
print_stack:unknown (bt:string)
Perform a symbolic lookup of the addresses in the given string,
which is assumed to be the result of a prior call to
.IR 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.
.TP
print_backtrace:unknown ()
Equivalent to
.IR print_stack(backtrace()) ,
except that deeper stack nesting may be supported.  Return nothing.
.TP
pp:string ()
Return the probe point associated with the currently running probe handler,
including alias and wildcard expansion effects.
.TP
probefunc:string ()
Return the probe point's function name, if known.
.TP
probemod:string ()
Return the probe point's module name, if known.
.TP
target:long ()
Return the pid of the target process.
.TP
user_mode:long ()
Return 1 if the probe point occurred in user-mode.
.TP
is_return:long ()
Return 1 if the probe point is a return probe.  Deprecated.

.SS TARGET_SET
.TP
target_set_pid:long (tid:long)
Return whether the given process-id is within the "target set", that is whether
it is a descendent of the top-level target() process.
.TP
target_set_report:unknown ()
Print a report about the target set, and their ancestry. 

.SS ERRNO
.TP
errno_str:string (e:long)
Return the symbolic string associated with the given error code, like
"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333.

.SS TASK
.PP
These functions return data about a task.  They all require
a task handle as input, such as the value return by task_current() or the variables
prev_task and next_task in the scheduler.ctxswitch probe alias.

.TP
task_current:long()
Return the task_struct of the current process.

.TP
task_parent:long(task:long)
Return the parent task_struct of the given task.
.TP
task_state:long(task:long)
Return the state of the given task, which can be one of the following:

   TASK_RUNNING           0
   TASK_INTERRUPTIBLE     1
   TASK_UNINTERRUPTIBLE   2
   TASK_STOPPED           4
   TASK_TRACED            8
   EXIT_ZOMBIE           16
   EXIT_DEAD             32

.TP
task_execname:string(task:long)
Return the name of the given task.

.TP
task_pid:long(task:long)
Return the process id of the given task.

.TP
task_tid:long(task:long)
Return the thread id of the given task.

.TP
task_gid:long(task:long)
Return the group id of the given task.

.TP
task_egid:long(task:long)
Return the effective group id of the given task.

.TP
task_uid:long(task:long)
Return the user id of the given task.

.TP
task_euid:long(task:long)
Return the effective user id of the given task.

.TP
task_prio:long(task:long)
Return the priority of the given task.

.TP
task_nice:long(task:long)
Return the nice value of the given task.

.TP
task_cpu:long(task:long)
Return the scheduled cpu for the given task.

.TP
task_open_file_handles:long(task:long)
Return the number of open file handles for the given task.

.TP
task_max_file_handles:long(task:long)
Return the maximum number of file handles for the given task.

.TP
pid2task:long(pid:long)
Return the task of the given process id.

.TP
pid2execname:string(pid:long)
Return the name of the given process id.

.SS CPU REGISTERS
.TP
registers_valid:long ()
Return 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.
.TP
register:long (name:string)
Return the value of the named CPU register,
as it was saved when the current probe point was hit.
If the register is 32 bits, it is sign-extended to 64 bits.

For the i386 architecture, the following names are recognized.
(name1/name2 indicates that name1 and name2 are alternative names
for the same register.)
eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags,
eip/ip, esi/si, esp/sp, orig_eax/orig_ax,
xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss.

For the x86_64 architecture, the following names are recognized:
64-bit registers:
r8, r9, r10, r11, r12, r13, r14, r15,
rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx,
rip/ip, rsi/si, rsp/sp;
32-bit registers:
eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax;
segment registers: xcs/cs, xss/ss.

For powerpc, the following names are recognized:
r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap,
dar, dsisr, result.

For s390x, the following names are recognized:
r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap.

.TP
u_register:long (name:string)
Same as register(name), except that
if the register is 32 bits, it is zero-extended to 64 bits.

.SS NUMBERED FUNCTION ARGUMENTS
The functions in this section provide the values of a probed function's
arguments.
They can be called when you have hit
a probe point at the entry to a function.
Arguments are referred to by number, starting at 1.
Ordinarily, you can access arguments by name as well,
but you may find these functions useful if the code you are probing
was built without debugging information.

On 32-bit architectures
\(em and when probing 32-bit applications on 64-bit architectures \(em
a 64-bit argument occupies two "arg slots."
For example, if you are probing the following function

   void f(int a, long long b, char *c)

you would refer to a, b, and c as int_arg(1), longlong_arg(2), and
pointer_arg(3), respectively, on a 64-bit architecture;
but on a 32-bit architecture, you would refer to c as pointer_arg(4)
(since b occupies slots 2 and 3).

If the function you are probing doesn't follow the default rules
for argument passing, you need to call one of the following functions
(which see) in your handler before calling any *_arg function:
asmlinkage(), fastcall(), or regparm().
(This isn't necessary when referring to arguments only by name.)
.TP
int_arg:long (n:long)
Return the value of argument n as a signed int
(i.e., a 32-bit integer sign-extended to 64 bits).
.TP
uint_arg:long (n:long)
Return the value of argument n as an unsigned int
(i.e., a 32-bit integer zero-extended to 64 bits).
.TP
long_arg:long (n:long)
Return the value of argument n as a signed long.
On architectures where a long is 32 bits, the value is sign-extended to 64 bits.
.TP
ulong_arg:long (n:long)
Return the value of argument n as an unsigned long.
On architectures where a long is 32 bits, the value is zero-extended to 64 bits.
.TP
longlong_arg:long (n:long)
Return the value of argument n as a 64-bit value.
.TP
ulonglong_arg:long (n:long)
Same as longlong_arg(n).
.TP
pointer_arg:long (n:long)
Same as ulong_arg(n).
Use with any type of pointer.
.TP
s32_arg:long (n:long)
Same as int_arg(n).
.TP
u32_arg:long (n:long)
Same as uint_arg(n).
.TP
s64_arg:long (n:long)
Same as longlong_arg(n).
.TP
u64_arg:long (n:long)
Same as [u]longlong_arg(n).
.TP
asmlinkage:unknown ()
The probed kernel function is declared asmlinkage in the source.
.TP
fastcall:unknown ()
The probed kernel function is declared fastcall in the source.
.TP
regparm:unknown (n:long)
The probed function was built with the gcc \-mregparm=n option.
(The i386 kernel is built with \-mregparm=3, so systemtap considers
regparm(3) the default for kernel functions on that architecture.)

For some architectures, the *_arg functions may reject unusually high
values of n.

.SS QUEUE_STATS
.PP
The queue_stats tapset provides functions that, given notifications of
elementary queuing events (wait, run, done), tracks averages such as
queue length, service and wait times, utilization.  The following
three functions should be called from appropriate probes, in sequence.
.TP
qs_wait:unknown (qname:string)
Record that a new request was enqueued for the given queue name.
.TP
qs_run:unknown (qname:string)
Record that a previously enqueued request was removed from the given
wait queue and is now being serviced.
.TP
qs_done:unknown (qname:string)
Record that a request originally from the given queue has completed
being serviced.
.\" XXX: qs_time
.PP
Functions with the prefix 
.BR qsq_
are for querying the statistics averaged since the first queue operation
(or when
.BR qsq_start
was called). Since statistics are often fractional, a scale parameter
is multiplies the result to a more useful scale.  For some fractions,
a scale of 100 will usefully return percentage numbers.
.TP
qsq_start:unknown (qname:string)
Reset the statistics counters for the given queue, and start tracking
anew from this moment.
.TP
qsq_print:unknown (qname:string)
Print a line containing a selection of the given queue's statistics.
.TP
qsq_utilization:long (qname:string, scale:long)
Return the fraction of elapsed time when the resource was utilized.
.TP
qsq_blocked:long (qname:string, scale:long)
Return the fraction of elapsed time when the wait queue was used.
.TP
qsq_wait_queue_length:long (qname:string, scale:long)
Return the average length of the wait queue.
.TP
qsq_service_time:long (qname:string, scale:long)
Return the average time required to service a request.
.TP
qsq_wait_time:long (qname:string, scale:long)
Return the average time a request took from being enqueued to completed.
.TP
qsq_throughput:long (qname:string, scale:long)
Return the average rate of requests per scale units of time.

.SS INDENT
.PP
The indent tapset provides functions to generate indented lines for
nested kinds of trace messages.  Each line contains a relative
timestamp, and the process name / pid.
.TP
thread_indent:string (delta:long)
Return a string with an appropriate indentation for this thread.
Call it with a small positive or matching negative delta.
If this is the outermost, initial level of indentation, reset the
relative timestamp base to zero.
.TP
thread_timestamp:long ()
Return an absolute timestamp value for use by the indentation function.
The default function uses 
.IR gettimeofday_us

.SS SYSTEM
.TP
system (cmd:string)
Runs a command on the system. The command will run in the background
when the current probe completes.

.SS NUMA
.TP
addr_to_node:long (addr:long)
Return which node the given address belongs to in a NUMA system.

.SS CTIME
.TP
ctime:string (seconds:long)
Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993")
of the given number of seconds since the epoch, as perhaps returned by
.IR gettimeofday_s() .

.SS PERFMON
.TP
read_counter:long (handle:long)
Returns the value for the processor's performance counter for the associated
handle. The body of the a perfmon probe should set record
the handle being used for that event.

.SS SOCKETS
These functions convert arguments in the socket tapset back and
forth between their numeric and string representations.
See 
.IR stapprobes.socket (3stap)
for details.

.TP
sock_prot_num2str:string (proto:long)
Returns the string representation of the given protocol value.
.TP
sock_prot_str2num:long (proto:string)
Returns the numeric value associated with the given protocol string.
.TP
sock_fam_num2str:string (family:long)
Returns the string representation of the given protocol family value.
.TP
sock_fam_str2num:long (family:string)
Returns the numeric value associated with the given protocol family string.
.TP
sock_state_num2str:string (state:long)
Returns the string representation of the given socket state value.
.TP
sock_state_str2num:long (state:string)
Returns the numeric value associated with the given socket state string.
.TP
sock_type_num2str:string (type:long)
Returns the string representation of the given socket type value.
.TP
sock_type_str2num:long (type:string)
Returns the numeric value associated with the given socket type string.
.TP
sock_flags_num2str:string (flags:long)
Returns the string representation of the given socket flags value.
.TP
msg_flags_num2str:string (flags:long)
Returns the string representation of the given message flags bit map.

.SS INET
These functions convert between network (big-endian) and host byte order, like their
namesake C functions.
.TP
ntohll:long (x:long)
Convert from network to host byte order, 64-bit.
.TP
ntohl:long (x:long)
Convert from network to host byte order, 32-bit.
.TP
ntohs:long (x:long)
Convert from network to host byte order, 16-bit.
.TP
htonll:long (x:long)
Convert from host to network byte order, 64-bit.
.TP
htonl:long (x:long)
Convert from host to network byte order, 32-bit.
.TP
htons:long (x:long)
Convert from host to network byte order, 16-bit.

.SS SIGNAL
.TP
get_sa_flags:long (act:long)
Returns the numeric value of sa_flags.
.TP
get_sa_handler:long (act:long)
Returns the numeric value of sa_handler.
.TP
sigset_mask_str:string (mask:long)
Returns the string representation of the sigset sa_mask.
.TP
is_sig_blocked:long (task:long, sig:long)
Returns 1 if the signal is currently blocked, or 0 if it is not.
.TP
sa_flags_str:string (sa_flags:long)
Returns the string representation of sa_flags.
.TP
sa_handler_str(handler)
Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN
or SIG_ERR, it will return the address of the handler.
.TP
signal_str(num)
Returns the string representation of the given signal number.

.SS DEVICE
.TP
MAJOR:long(dev:long)
Extracts the major device number from a kernel device number (kdev_t).
.TP
MINOR:long(dev:long)
Extracts the minor device number from a kernel device number (kdev_t).
.TP
MKDEV:long(major:long, minor:long)
Creates a value that can be compared to a kernel device number (kdev_t).
.TP
usrdev2kerndev:long(dev:long)
Converts a user-space device number into the format used in the kernel.

.SH FILES
.nh
.IR @prefix@/share/systemtap/tapset
.hy

.SH SEE ALSO
.IR stap (1)