diff options
Diffstat (limited to 'stapfuncs.3stap.in')
| -rw-r--r-- | stapfuncs.3stap.in | 679 |
1 files changed, 679 insertions, 0 deletions
diff --git a/stapfuncs.3stap.in b/stapfuncs.3stap.in new file mode 100644 index 00000000..b9326fde --- /dev/null +++ b/stapfuncs.3stap.in @@ -0,0 +1,679 @@ +.\" -*- 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 PRINTING + +.TP +log:unknown (msg:string) +Writes the given string to the common trace buffer. Append an implicit +end-of-line. Deprecated. Please use the faster print functions. + +.TP +warn:unknown (msg:string) +Write the given string to the warning stream. Append an implicit end-of-line. +.I staprun +prepends the string "WARNING:". + +.TP +error:unknown (msg:string) +An error has occurred. Write the given string to the error stream. +Append an implicit end-of-line. +.I staprun +prepends the string "ERROR:". +Block any further execution of statements in this probe. If the number +of errors so far exceeds the MAXERRORS parameter, also trigger an +.IR exit() . + +.TP +exit:unknown () +Enqueue a request to shut down the systemtap session. This does +.B not +unwind the current probe handler, nor block new probe handlers. +.I staprun +will shortly respond to the request and initiate an orderly shutdown. + +.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 token in the given str string, where the tokens are delimited +by one of the 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 +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) |