Add user_{int8,int16,uint16,int32,uint32,int64}.

[systemtap.git] / stapfuncs.3stap

.\" -*- nroff -*-
.TH STAPFUNCS 3stap
.SH NAME
stapfuncs \- systemtap functions

.SH DESCRIPTION
The following sections enumerate a few of public functions provided by
standard tapsets installed, show in the stappaths (7) manual page.   Most
are individually documented in the 
.IR 3stap
manual section, with the
.IR function::
prefix.
.PP
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 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 REGISTERS
.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 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
.TP
More files and their corresponding paths can be found in the stappaths (7) manual page.

.SH SEE ALSO
.IR stap (1),
.IR function::* (3stap),
.IR tapset::* (3stap),
.IR stappaths (7)