1STAPFUNCS(5) File Formats Manual STAPFUNCS(5)
2
6 stapfuncs - systemtap functions
7
10 The following sections enumerate the public functions provided by stan‐
11 dard tapsets installed under /usr/share/systemtap/tapset. Each func‐
12 tion is described with a signature, and its behavior/restrictions. The
13 signature line includes the name of the function, the type of its
14 return value (if any), and the names and types of all parameters. The
15 syntax is the same as printed with the stap option -p2. Examples:
16 example1:long (v:string, k:long)
19 In function "example1", do something with the given string and
20 integer. Return some integer.
21 example2:unknown ()
24 In function "example2", do something. There is no explicit
25 return value and take no parameters.
26 PRINTING
29 log:unknown (msg:string)
30 Writes the given string to the common trace buffer. Append an
31 implicit end-of-line. Deprecated. Please use the faster print
32 functions.
33 warn:unknown (msg:string)
36 Write the given string to the warning stream. Append an
37 implicit end-of-line. staprun prepends the string "WARNING:".
38 error:unknown (msg:string)
41 An error has occurred. Write the given string to the error
42 stream. Append an implicit end-of-line. staprun prepends the
43 string "ERROR:". Block any further execution of statements in
44 this probe. If the number of errors so far exceeds the MAXER‐
45 RORS parameter, also trigger an exit().
46 exit:unknown ()
49 Enqueue a request to shut down the systemtap session. This does
50 not unwind the current probe handler, nor block new probe han‐
51 dlers. staprun will shortly respond to the request and initiate
52 an orderly shutdown.
53 CONVERSIONS
56 These functions access kernel or user-space data. They try to validate
57 the supplied addresses, and can thus result in errors if the pointers
58 are invalid, or if a user-space access would cause a fault.
59 kernel_string:string (addr:long)
61 Copy a 0-terminated string from kernel space at given address.
62 kernel_string_n:string (addr:long, n:long)
64 Similar with kernel_string, except that not more than n bytes
65 are copied. Thus, if there are null bytes among the first n
66 bytes, it is same as kernel_string(addr). If not, n bytes will
67 be copied and a null byte will be padded to the end.
68 kernel_long:long (addr:long)
70 Copy a long from kernel space at given address.
71 kernel_int:long (addr:long)
73 Copy an int from kernel space at given address.
74 kernel_short:long (addr:long)
76 Copy a short from kernel space at given address.
77 kernel_char:long (addr:long)
79 Copy a char from kernel space at given address.
80 user_string:string (addr:long)
82 Copy a string from user space at given address. If the access
83 would fault, return "<unknown>" and signal no errors.
84 user_string2:string (addr:long, err_msg:string)
86 Copy a string from user space at given address. If the access
87 would fault, return instead the err_msg value.
88 user_string_warn:string (addr:long)
90 Copy a string from user space at given address. If the access
91 would fault, signal a warning and return "<unknown>".
92 STRING
94 strlen:long (str:string)
95 Return the number of characters in str.
96 substr:string (str:string,start:long, stop:long)
98 Return the substring of str starting from character start and
99 ending at character stop.
100 isinstr:long (s1:string, s2:string)
102 Return 1 if string s1 contains string s2, returns 0 otherwise.
103 strtol:long (str:string, base:long)
105 Convert the string representation of a number to a long using
106 the numbering system specified by base. For example, str‐
107 tol("1000", 16) returns 4096. Returns 0 if the string cannot be
108 converted.
109 tokenize:string (str:string, delim:string)
111 Return the next token in the given str string, where the tokens
112 are delimited by one of the characters in the delim string. If
113 the str string is not blank, it returns the first token. If the
114 str string is blank, it returns the next token in the string
115 passed in the previous call to tokenize. If no delimiter is
116 found, the entire remaining str string is returned. Returns
117 blank when no more tokens are left.
118 TIMESTAMP
121 get_cycles:long ()
122 Return the processor cycle counter value, or 0 if unavailable.
123 gettimeofday_ns:long ()
125 Return the number of nanoseconds since the UNIX epoch.
126 gettimeofday_us:long ()
128 Return the number of microseconds since the UNIX epoch.
129 gettimeofday_ms:long ()
131 Return the number of milliseconds since the UNIX epoch.
132 gettimeofday_s:long ()
134 Return the number of seconds since the UNIX epoch.
135 CONTEXT INFO
138 cpu:long ()
139 Return the current cpu number.
140 execname:string ()
142 Return the name of the current process.
143 pexecname:string()
145 Return the name of the parent process.
146 tid:long ()
148 Return the id of the current thread.
149 pid:long ()
151 Return the id of the current process.
152 ppid:long ()
154 Return the id of the parent process.
155 uid:long ()
157 Return the uid of the current process.
158 euid:long ()
160 Return the effective uid of the current process.
161 gid:long ()
163 Return the gid of the current process.
164 egid:long ()
166 Return the effective gid of the current process.
167 print_regs:unknown ()
169 Print a register dump.
170 backtrace:string ()
172 Return a string of hex addresses that are a backtrace of the
173 stack. It may be truncated due to maximum string length.
174 print_stack:unknown (bt:string)
176 Perform a symbolic lookup of the addresses in the given string,
177 which is assumed to be the result of a prior call to back‐
178 trace(). Print one line per address, including the address, the
179 name of the function containing the address, and an estimate of
180 its position within that function. Return nothing.
181 print_backtrace:unknown ()
183 Equivalent to print_stack(backtrace()), except that deeper stack
184 nesting may be supported. Return nothing.
185 pp:string ()
187 Return the probe point associated with the currently running
188 probe handler, including alias and wildcard expansion effects.
189 probefunc:string ()
191 Return the probe point's function name, if known.
192 probemod:string ()
194 Return the probe point's module name, if known.
195 target:long ()
197 Return the pid of the target process.
198 is_return:long ()
200 Return 1 if the probe point is a return probe. Deprecated.
201 TARGET_SET
204 target_set_pid:long (tid:long)
205 Return whether the given process-id is within the "target set",
206 that is whether it is a descendent of the top-level target()
207 process.
208 target_set_report:unknown ()
210 Print a report about the target set, and their ancestry.
211 ERRNO
214 errno_str:string (e:long)
215 Return the symbolic string associated with the given error code,
216 like "ENOENT" for the number 2, or "E#3333" for an out-of-range
217 value like 3333.
218 TASK
221 These functions return data about a task. They all require a task han‐
222 dle as input, such as the value return by task_current() or the vari‐
223 ables prev_task and next_task in the scheduler.ctxswitch probe alias.
224 task_current:long()
227 Return the task_struct of the current process.
228 task_parent:long(task:long)
231 Return the parent task_struct of the given task.
232 task_state:long(task:long)
234 Return the state of the given task, which can be one of the fol‐
235 lowing:
236 TASK_RUNNING 0
238 TASK_INTERRUPTIBLE 1
239 TASK_UNINTERRUPTIBLE 2
240 TASK_STOPPED 4
241 TASK_TRACED 8
242 EXIT_ZOMBIE 16
243 EXIT_DEAD 32
244 task_execname:string(task:long)
247 Return the name of the given task.
248 task_pid:long(task:long)
251 Return the process id of the given task.
252 task_tid:long(task:long)
255 Return the thread id of the given task.
256 task_gid:long(task:long)
259 Return the group id of the given task.
260 task_egid:long(task:long)
263 Return the effective group id of the given task.
264 task_uid:long(task:long)
267 Return the user id of the given task.
268 task_euid:long(task:long)
271 Return the effective user id of the given task.
272 task_prio:long(task:long)
275 Return the priority of the given task.
276 task_nice:long(task:long)
279 Return the nice value of the given task.
280 task_cpu:long(task:long)
283 Return the scheduled cpu for the given task.
284 task_open_file_handles:long(task:long)
287 Return the number of open file handles for the given task.
288 task_max_file_handles:long(task:long)
291 Return the maximum number of file handles for the given task.
292 QUEUE_STATS
295 The queue_stats tapset provides functions that, given notifications of
296 elementary queuing events (wait, run, done), tracks averages such as
297 queue length, service and wait times, utilization. The following three
298 functions should be called from appropriate probes, in sequence.
299 qs_wait:unknown (qname:string)
301 Record that a new request was enqueued for the given queue name.
302 qs_run:unknown (qname:string)
304 Record that a previously enqueued request was removed from the
305 given wait queue and is now being serviced.
306 qs_done:unknown (qname:string)
308 Record that a request originally from the given queue has com‐
309 pleted being serviced.
310 Functions with the prefix qsq_ are for querying the statistics averaged
312 since the first queue operation (or when qsq_start was called). Since
313 statistics are often fractional, a scale parameter is multiplies the
314 result to a more useful scale. For some fractions, a scale of 100 will
315 usefully return percentage numbers.
316 qsq_start:unknown (qname:string)
318 Reset the statistics counters for the given queue, and start
319 tracking anew from this moment.
320 qsq_print:unknown (qname:string)
322 Print a line containing a selection of the given queue's statis‐
323 tics.
324 qsq_utilization:long (qname:string, scale:long)
326 Return the fraction of elapsed time when the resource was uti‐
327 lized.
328 qsq_blocked:long (qname:string, scale:long)
330 Return the fraction of elapsed time when the wait queue was
331 used.
332 qsq_wait_queue_length:long (qname:string, scale:long)
334 Return the average length of the wait queue.
335 qsq_service_time:long (qname:string, scale:long)
337 Return the average time required to service a request.
338 qsq_wait_time:long (qname:string, scale:long)
340 Return the average time a request took from being enqueued to
341 completed.
342 qsq_throughput:long (qname:string, scale:long)
344 Return the average rate of requests per scale units of time.
345 INDENT
348 The indent tapset provides functions to generate indented lines for
349 nested kinds of trace messages. Each line contains a relative time‐
350 stamp, and the process name / pid.
351 thread_indent:string (delta:long)
353 Return a string with an appropriate indentation for this thread.
354 Call it with a small positive or matching negative delta. If
355 this is the outermost, initial level of indentation, reset the
356 relative timestamp base to zero.
357 thread_timestamp:long ()
359 Return an absolute timestamp value for use by the indentation
360 function. The default function uses gettimeofday_us
361 SYSTEM
364 system (cmd:string)
365 Runs a command on the system. The command will run in the back‐
366 ground when the current probe completes.
367 NUMA
370 addr_to_node:long (addr:long)
371 Return which node the given address belongs to in a NUMA system.
372 CTIME
375 ctime:string (seconds:long)
376 Return a simple textual rendering (e.g.,
377 "Wed Jun 30 21:49:008 1993") of the given number of seconds
378 since the epoch, as perhaps returned by gettimeofday_s().
379 PERFMON
382 read_counter:long (handle:long)
383 Returns the value for the processor's performance counter for
384 the associated handle. The body of the a perfmon probe should
385 set record the handle being used for that event.
386 SOCKETS
389 These functions convert arguments in the socket tapset back and forth
390 between their numeric and string representations. See stap‐
391 probes.socket(5) for details.
392 sock_prot_num2str:string (proto:long)
395 Returns the string representation of the given protocol value.
396 sock_prot_str2num:long (proto:string)
398 Returns the numeric value associated with the given protocol
399 string.
400 sock_fam_num2str:string (family:long)
402 Returns the string representation of the given protocol family
403 value.
404 sock_fam_str2num:long (family:string)
406 Returns the numeric value associated with the given protocol
407 family string.
408 sock_state_num2str:string (state:long)
410 Returns the string representation of the given socket state
411 value.
412 sock_state_str2num:long (state:string)
414 Returns the numeric value associated with the given socket state
415 string.
416 sock_type_num2str:string (type:long)
418 Returns the string representation of the given socket type
419 value.
420 sock_type_str2num:long (type:string)
422 Returns the numeric value associated with the given socket type
423 string.
424 sock_flags_num2str:string (flags:long)
426 Returns the string representation of the given socket flags
427 value.
428 msg_flags_num2str:string (flags:long)
430 Returns the string representation of the given message flags bit
431 map.
432 INET
435 These functions convert between network (big-endian) and host byte
436 order, like their namesake C functions.
437 ntohll:long (x:long)
439 Convert from network to host byte order, 64-bit.
440 ntohl:long (x:long)
442 Convert from network to host byte order, 32-bit.
443 ntohs:long (x:long)
445 Convert from network to host byte order, 16-bit.
446 htonll:long (x:long)
448 Convert from host to network byte order, 64-bit.
449 htonl:long (x:long)
451 Convert from host to network byte order, 32-bit.
452 htons:long (x:long)
454 Convert from host to network byte order, 16-bit.
455 SIGNAL
458 get_sa_flags:long (act:long)
459 Returns the numeric value of sa_flags.
460 get_sa_handler:long (act:long)
462 Returns the numeric value of sa_handler.
463 sigset_mask_str:string (mask:long)
465 Returns the string representation of the sigset sa_mask.
466 is_sig_blocked:long (task:long, sig:long)
468 Returns 1 if the signal is currently blocked, or 0 if it is not.
469 sa_flags_str:string (sa_flags:long)
471 Returns the string representation of sa_flags.
472 sa_handler_str(handler)
474 Returns the string representation of sa_handler. If it is not
475 SIG_DFL, SIG_IGN or SIG_ERR, it will return the address of the
476 handler.
477 signal_str(num)
479 Returns the string representation of the given signal number.
480
483 /usr/share/systemtap/tapset
484
487 stap(1)
488Red Hat 2008-03-27 STAPFUNCS(5)