.\" -*- nroff -*- .TH STAPFUNCS 5 @DATE@ "Red Hat" .SH NAME stapfuncs \- systemtap functions .SH DESCRIPTION The following sections enumerate the public functions provided by standard tapsets installed under /usr/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 LOGGING .TP log:unknown (msg:string) Log the given string to the common trace buffer. Append an implicit end-of-line. .TP print:unknown (...) Print the given integer, string, or statistics value to the common trace buffer. .TP printf:unknown (fmt:string, ...) Like the C printf, except valid types are limited to string ("%s") and integer ("%d"). .TP warn:unknown (msg:string) Log the given string to the warning stream. Append an implicit end-of-line. .I stpd prepends the string "WARNING:". .TP error:unknown (msg:string) An error has occurred. Log the given string to the error stream. Append an implicit end-of-line. .I stpd 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 stpd will shortly respond to the request and initiate an orderly shutdown. .SS CONVERSIONS .TP hexstring:string (num:long) Return a hexadecimal string representation of the given integer, including the leading "0x". .TP string:string (num:long) Return a decimal string representation of the given integer. .TP kernel_string:string (addr:long) Copy a string from kernel space at given address. The validation of this address is only partial at present. .TP user_string:string (addr:long) Copy a string from user space at given address. The validation of this address is only partial at present. .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 isinstr:long (s1:string, s2:string) Return 1 if string s1 contains string s2, returns 0 otherwise. .SS TIMESTAMP .TP get_cycles:long () Return the processor cycle counter value, or 0 if unavailable. .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 CONTEXTINFO .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 print_backtrace:unknown () Print a symbolic backtrace. Use with care. May be timeconsuming. .TP backtrace:string () Return a string of hex addresses that are a backtrace of the stack. May be truncated due to maximum string length. .TP print_stack (bt:string) Perform a symbolic lookup of the addresses in bt and prints one per line. .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. .TP target:long () Return the pid of the target process. .TP is_return:long () Return 1 if the probe point is a return probe. .TP returnval:long () Return the pending return value of the function being return-probed. .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 QUEUE_STATS .PP The queue_stats tapset provides functions that, given notifications of elementary queuing events (wait, run, done), tracks averages such as queue lenghth, 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. .SH FILES .nh .IR /usr/share/systemtap/tapset .hy .SH SEE ALSO .IR stap (1)