1STAPFUNCS(3stap) STAPFUNCS(3stap)
2
6 stapfuncs - systemtap functions
7
10 The following sections enumerate a few of public functions provided by
11 standard tapsets installed, show in the stappaths (7) manual page.
12 Most are individually documented in the 3stap manual section, with the
13 function:: prefix.
14 Each function is described with a signature, and its behavior/restric‐
16 tions. The signature line includes the name of the function, the type
17 of its return value (if any), and the names and types of all parame‐
18 ters. The syntax is the same as printed with the stap option -p2.
19 Examples:
20 example1:long (v:string, k:long)
23 In function "example1", do something with the given string and
24 integer. Return some integer.
25 example2:unknown ()
28 In function "example2", do something. There is no explicit
29 return value and take no parameters.
30 TARGET_SET
34 target_set_pid:long (tid:long)
35 Return whether the given process-id is within the "target set",
36 that is whether it is a descendent of the top-level target()
37 process.
38 target_set_report:unknown ()
40 Print a report about the target set, and their ancestry.
41 ERRNO
44 errno_str:string (e:long)
45 Return the symbolic string associated with the given error code,
46 like "ENOENT" for the number 2, or "E#3333" for an out-of-range
47 value like 3333.
48 REGISTERS
51 register:long (name:string)
52 Return the value of the named CPU register, as it was saved when
53 the current probe point was hit. If the register is 32 bits, it
54 is sign-extended to 64 bits.
55 For the i386 architecture, the following names are recognized.
57 (name1/name2 indicates that name1 and name2 are alternative
58 names for the same register.) eax/ax, ebp/bp, ebx/bx, ecx/cx,
59 edi/di, edx/dx, eflags/flags, eip/ip, esi/si, esp/sp,
60 orig_eax/orig_ax, xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss.
61 For the x86_64 architecture, the following names are recognized:
63 64-bit registers: r8, r9, r10, r11, r12, r13, r14, r15, rax/ax,
64 rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx, rip/ip, rsi/si, rsp/sp;
65 32-bit registers: eax, ebp, ebx, ecx, edx, edi, edx, eip, esi,
66 esp, flags/eflags, orig_eax; segment registers: xcs/cs, xss/ss.
67 For powerpc, the following names are recognized: r0, r1, ...
69 r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap, dar,
70 dsisr, result.
71 For s390x, the following names are recognized: r0, r1, ... r15,
73 args, psw.mask, psw.addr, orig_gpr2, ilc, trap.
74 u_register:long (name:string)
77 Same as register(name), except that if the register is 32 bits,
78 it is zero-extended to 64 bits.
79 NUMBERED FUNCTION ARGUMENTS
82 The functions in this section provide the values of a probed function's
83 arguments. They can be called when you have hit a probe point at the
84 entry to a function. Arguments are referred to by number, starting at
85 1. Ordinarily, you can access arguments by name as well, but you may
86 find these functions useful if the code you are probing was built with‐
87 out debugging information.
88 On 32-bit architectures — and when probing 32-bit applications on
90 64-bit architectures — a 64-bit argument occupies two "arg slots." For
91 example, if you are probing the following function
92 void f(int a, long long b, char *c)
94 you would refer to a, b, and c as int_arg(1), longlong_arg(2), and
96 pointer_arg(3), respectively, on a 64-bit architecture; but on a 32-bit
97 architecture, you would refer to c as pointer_arg(4) (since b occupies
98 slots 2 and 3).
99 If the function you are probing doesn't follow the default rules for
101 argument passing, you need to call one of the following functions
102 (which see) in your handler before calling any *_arg function: asmlink‐
103 age(), fastcall(), or regparm(). (This isn't necessary when referring
104 to arguments only by name.)
105 int_arg:long (n:long)
107 Return the value of argument n as a signed int (i.e., a 32-bit
108 integer sign-extended to 64 bits).
109 uint_arg:long (n:long)
111 Return the value of argument n as an unsigned int (i.e., a
112 32-bit integer zero-extended to 64 bits).
113 long_arg:long (n:long)
115 Return the value of argument n as a signed long. On architec‐
116 tures where a long is 32 bits, the value is sign-extended to 64
117 bits.
118 ulong_arg:long (n:long)
120 Return the value of argument n as an unsigned long. On archi‐
121 tectures where a long is 32 bits, the value is zero-extended to
122 64 bits.
123 longlong_arg:long (n:long)
125 Return the value of argument n as a 64-bit value.
126 ulonglong_arg:long (n:long)
128 Same as longlong_arg(n).
129 pointer_arg:long (n:long)
131 Same as ulong_arg(n). Use with any type of pointer.
132 s32_arg:long (n:long)
134 Same as int_arg(n).
135 u32_arg:long (n:long)
137 Same as uint_arg(n).
138 s64_arg:long (n:long)
140 Same as longlong_arg(n).
141 u64_arg:long (n:long)
143 Same as [u]longlong_arg(n).
144 asmlinkage:unknown ()
146 The probed kernel function is declared asmlinkage in the source.
147 fastcall:unknown ()
149 The probed kernel function is declared fastcall in the source.
150 regparm:unknown (n:long)
152 The probed function was built with the gcc -mregparm=n option.
153 (The i386 kernel is built with -mregparm=3, so systemtap consid‐
154 ers regparm(3) the default for kernel functions on that archi‐
155 tecture.)
156 For some architectures, the *_arg functions may reject unusually
158 high values of n.
159 QUEUE_STATS
162 The queue_stats tapset provides functions that, given notifications of
163 elementary queuing events (wait, run, done), tracks averages such as
164 queue length, service and wait times, utilization. The following three
165 functions should be called from appropriate probes, in sequence.
166 qs_wait:unknown (qname:string)
168 Record that a new request was enqueued for the given queue name.
169 qs_run:unknown (qname:string)
171 Record that a previously enqueued request was removed from the
172 given wait queue and is now being serviced.
173 qs_done:unknown (qname:string)
175 Record that a request originally from the given queue has com‐
176 pleted being serviced.
177 Functions with the prefix qsq_ are for querying the statistics averaged
179 since the first queue operation (or when qsq_start was called). Since
180 statistics are often fractional, a scale parameter is multiplies the
181 result to a more useful scale. For some fractions, a scale of 100 will
182 usefully return percentage numbers.
183 qsq_start:unknown (qname:string)
185 Reset the statistics counters for the given queue, and start
186 tracking anew from this moment.
187 qsq_print:unknown (qname:string)
189 Print a line containing a selection of the given queue's statis‐
190 tics.
191 qsq_utilization:long (qname:string, scale:long)
193 Return the fraction of elapsed time when the resource was uti‐
194 lized.
195 qsq_blocked:long (qname:string, scale:long)
197 Return the fraction of elapsed time when the wait queue was
198 used.
199 qsq_wait_queue_length:long (qname:string, scale:long)
201 Return the average length of the wait queue.
202 qsq_service_time:long (qname:string, scale:long)
204 Return the average time required to service a request.
205 qsq_wait_time:long (qname:string, scale:long)
207 Return the average time a request took from being enqueued to
208 completed.
209 qsq_throughput:long (qname:string, scale:long)
211 Return the average rate of requests per scale units of time.
212 INDENT
215 The indent tapset provides functions to generate indented lines for
216 nested kinds of trace messages. Each line contains a relative time‐
217 stamp, and the process name / pid.
218 thread_indent:string (delta:long)
220 Return a string with an appropriate indentation for this thread.
221 Call it with a small positive or matching negative delta. If
222 this is the outermost, initial level of indentation, reset the
223 relative timestamp base to zero.
224 thread_timestamp:long ()
226 Return an absolute timestamp value for use by the indentation
227 function. The default function uses gettimeofday_us
228 SYSTEM
231 system (cmd:string)
232 Runs a command on the system. The command will run in the back‐
233 ground when the current probe completes.
234 INET
238 These functions convert between network (big-endian) and host byte
239 order, like their namesake C functions.
240 ntohll:long (x:long)
242 Convert from network to host byte order, 64-bit.
243 ntohl:long (x:long)
245 Convert from network to host byte order, 32-bit.
246 ntohs:long (x:long)
248 Convert from network to host byte order, 16-bit.
249 htonll:long (x:long)
251 Convert from host to network byte order, 64-bit.
252 htonl:long (x:long)
254 Convert from host to network byte order, 32-bit.
255 htons:long (x:long)
257 Convert from host to network byte order, 16-bit.
258 SIGNAL
261 get_sa_flags:long (act:long)
262 Returns the numeric value of sa_flags.
263 get_sa_handler:long (act:long)
265 Returns the numeric value of sa_handler.
266 sigset_mask_str:string (mask:long)
268 Returns the string representation of the sigset sa_mask.
269 is_sig_blocked:long (task:long, sig:long)
271 Returns 1 if the signal is currently blocked, or 0 if it is not.
272 sa_flags_str:string (sa_flags:long)
274 Returns the string representation of sa_flags.
275 sa_handler_str(handler)
277 Returns the string representation of sa_handler. If it is not
278 SIG_DFL, SIG_IGN or SIG_ERR, it will return the address of the
279 handler.
280 signal_str(num)
282 Returns the string representation of the given signal number.
283 DEVICE
286 MAJOR:long(dev:long)
287 Extracts the major device number from a kernel device number
288 (kdev_t).
289 MINOR:long(dev:long)
291 Extracts the minor device number from a kernel device number
292 (kdev_t).
293 MKDEV:long(major:long, minor:long)
295 Creates a value that can be compared to a kernel device number
296 (kdev_t).
297 usrdev2kerndev:long(dev:long)
299 Converts a user-space device number into the format used in the
300 kernel.
301
304 More files and their corresponding paths can be found in the stappaths
305 (7) manual page.
306
309 stap(1), function::*[24m(3stap), tapset::*[24m(3stap), stappaths(7)
310 STAPFUNCS(3stap)