stapfuncs.3stap.in

   1 .\" -*- nroff -*-
   2 .TH STAPFUNCS 3stap @DATE@ "Red Hat"
   3 .SH NAME
   4 stapfuncs \- systemtap functions
   5
   6 .SH DESCRIPTION
   7 The following sections enumerate the public functions provided by
   8 standard tapsets installed under @prefix@/share/systemtap/tapset.  Each
   9 function is described with a signature, and its behavior/restrictions.
  10 The signature line includes the name of the function, the type of
  11 its return value (if any), and the names and types of all parameters.
  12 The syntax is the same as printed with the
  13 .IR stap " option " \-p2 .
  14 Examples:
  15
  16 .TP
  17 example1:long (v:string, k:long)
  18 In function "example1", do something with the given string and integer.
  19 Return some integer.
  20
  21 .TP
  22 example2:unknown ()
  23 In function "example2", do something.  There is no explicit return value
  24 and take no parameters.
  25
  26
  27 .SS CONVERSIONS
  28 .PP
  29 These functions access kernel or user-space data.  They try to validate the
  30 supplied addresses, and can thus result in errors if the pointers are invalid,
  31 or if a user-space access would cause a fault.
  32 .TP
  33 kernel_string:string (addr:long)
  34 Copy a 0-terminated string from kernel space at given address.
  35 .TP
  36 kernel_string_n:string (addr:long, n:long)
  37 Similar with kernel_string, except that not more than n bytes are copied.
  38 Thus, if there are null bytes among the first n bytes, it is same as
  39 kernel_string(addr). If not, n bytes will be copied and a null byte will
  40 be padded to the end.
  41 .TP
  42 kernel_long:long (addr:long)
  43 Copy a long from kernel space at given address.
  44 .TP
  45 kernel_int:long (addr:long)
  46 Copy an int from kernel space at given address.
  47 .TP
  48 kernel_short:long (addr:long)
  49 Copy a short from kernel space at given address.
  50 .TP
  51 kernel_char:long (addr:long)
  52 Copy a char from kernel space at given address.
  53 .TP
  54 user_string:string (addr:long)
  55 Copy a string from user space at given address.  If the access would
  56 fault, return "<unknown>" and signal no errors.
  57 .TP
  58 user_string2:string (addr:long, err_msg:string)
  59 Copy a string from user space at given address.  If the access would
  60 fault, return instead the err_msg value.
  61 .TP
  62 user_string_warn:string (addr:long)
  63 Copy a string from user space at given address.  If the access would
  64 fault, signal a warning and return "<unknown>".
  65 .TP
  66 user_string_quoted:string (addr:long)
  67 Copy a string from user space at given address. Any ASCII characters
  68 that are not printable are replaced by the corresponding escape
  69 sequence in the returned string.
  70 .TP
  71 user_string_n:string (addr:long, n:long)
  72 Copy a string of n bytes from user space at given address. If the access
  73 would fault, return "<unknown>".
  74 .TP
  75 user_string_n2:string (addr:long, n:long, err_msg:string)
  76 Copy a string of n bytes from user space at given address. If the access
  77 would fault, return the err_msg value.
  78 .TP
  79 user_string_n_warn:string (addr:long, n:long)
  80 Copy a string of n bytes from user space at given address. If the access
  81 would fault, signal a warning and return "<unknown>".
  82 .TP
  83 user_string_n_quoted:string (addr:long, n:long)
  84 Copy a string of n bytes from user space at given address. Any ASCII
  85 characters that are not printable are replaced by the corresponding escape
  86 sequence in the returned string. If the access would fault, return "<unknown>".
  87 .TP
  88 user_short:long (addr:long)
  89 Copy a short from user space at given address. If the access would fault,
  90 return 0.
  91 .TP
  92 user_short_warn:long (addr:long)
  93 Copy a short from user space at given address. If the access would fault,
  94 signal a warning and return 0.
  95 .TP
  96 user_int:long (addr:long)
  97 Copy an int from user space at given address. If the access would fault,
  98 return 0.
  99 .TP
 100 user_int_warn:long (addr:long)
 101 Copy an int from user space at given address. If the access would fault,
 102 signal a warning and return 0.
 103 .TP
 104 user_long:long (addr:long)
 105 Copy a long from user space at given address. If the access would fault,
 106 return 0.
 107 .TP
 108 user_long_warn:long (addr:long)
 109 Copy a long from user space at given address. If the access would fault,
 110 signal a warning and return 0.
 111 .TP
 112 user_char:long (addr:long)
 113 Copy a char from user space at given address. If the access would fault,
 114 return 0.
 115 .TP
 116 user_char_warn:long (addr:long)
 117 Copy a char from user space at given address. If the access would fault,
 118 signal a warning and return 0.
 119 .SS STRING
 120 .TP
 121 strlen:long (str:string)
 122 Return the number of characters in str.
 123 .TP
 124 substr:string (str:string,start:long, stop:long)
 125 Return the substring of str starting from character start and ending at character stop.
 126 .TP
 127 stringat:string (str:string,pos:long)
 128 Return the character in given position of string.
 129 .TP
 130 isinstr:long (s1:string, s2:string)
 131 Return 1 if string s1 contains string s2, returns 0 otherwise.
 132 .TP
 133 strtol:long (str:string, base:long)
 134 Convert the string representation of a number to a long using the numbering system
 135 specified by base.  For example, strtol("1000", 16) returns 4096.  Returns 0 if the
 136 string cannot be converted.
 137 .TP
 138 tokenize:string (str:string, delim:string)
 139 Return the next non-empty token in the given str string, where the tokens are
 140 delimited by characters in the delim string.  If the str string is not blank,
 141 it returns the first token.  If the str string is blank, it returns the next
 142 token in the string passed in the previous call to tokenize. If no delimiter
 143 is found, the entire remaining str string is returned.  Returns blank when
 144 no more tokens are left.
 145
 146 .SS TIMESTAMP
 147 .TP
 148 get_cycles:long ()
 149 Return the processor cycle counter value, or 0 if unavailable.
 150 .TP
 151 gettimeofday_ns:long ()
 152 Return the number of nanoseconds since the UNIX epoch.
 153 .TP
 154 gettimeofday_us:long ()
 155 Return the number of microseconds since the UNIX epoch.
 156 .TP
 157 gettimeofday_ms:long ()
 158 Return the number of milliseconds since the UNIX epoch.
 159 .TP
 160 gettimeofday_s:long ()
 161 Return the number of seconds since the UNIX epoch.
 162
 163 .SS CONTEXT INFO
 164 .TP
 165 cpu:long ()
 166 Return the current cpu number.
 167 .TP
 168 execname:string ()
 169 Return the name of the current process.
 170 .TP
 171 pexecname:string()
 172 Return the name of the parent process.
 173 .TP
 174 tid:long ()
 175 Return the id of the current thread.
 176 .TP
 177 pid:long ()
 178 Return the id of the current process.
 179 .TP
 180 ppid:long ()
 181 Return the id of the parent process.
 182 .TP
 183 pgrp:long ()
 184 Return the pgrp of the current process.
 185 .TP
 186 sid:long ()
 187 Return the sid of the current process.
 188 .TP
 189 uid:long ()
 190 Return the uid of the current process.
 191 .TP
 192 euid:long ()
 193 Return the effective uid of the current process.
 194 .TP
 195 gid:long ()
 196 Return the gid of the current process.
 197 .TP
 198 egid:long ()
 199 Return the effective gid of the current process.
 200 .TP
 201 print_regs:unknown ()
 202 Print a register dump.
 203 .TP
 204 backtrace:string ()
 205 Return a string of hex addresses that are a backtrace of the stack.
 206 It may be truncated due to maximum string length.
 207 .TP
 208 print_stack:unknown (bt:string)
 209 Perform a symbolic lookup of the addresses in the given string,
 210 which is assumed to be the result of a prior call to
 211 .IR backtrace() .
 212 Print one line per address, including the address, the name of the
 213 function containing the address, and an estimate of its position
 214 within that function.  Return nothing.
 215 .TP
 216 print_backtrace:unknown ()
 217 Equivalent to
 218 .IR print_stack(backtrace()) ,
 219 except that deeper stack nesting may be supported.  Return nothing.
 220 .TP
 221 pp:string ()
 222 Return the probe point associated with the currently running probe handler,
 223 including alias and wildcard expansion effects.
 224 .TP
 225 probefunc:string ()
 226 Return the probe point's function name, if known.
 227 .TP
 228 probemod:string ()
 229 Return the probe point's module name, if known.
 230 .TP
 231 target:long ()
 232 Return the pid of the target process.
 233 .TP
 234 user_mode:long ()
 235 Return 1 if the probe point occurred in user-mode.
 236 .TP
 237 is_return:long ()
 238 Return 1 if the probe point is a return probe.  Deprecated.
 239
 240 .SS TARGET_SET
 241 .TP
 242 target_set_pid:long (tid:long)
 243 Return whether the given process-id is within the "target set", that is whether
 244 it is a descendent of the top-level target() process.
 245 .TP
 246 target_set_report:unknown ()
 247 Print a report about the target set, and their ancestry.
 248
 249 .SS ERRNO
 250 .TP
 251 errno_str:string (e:long)
 252 Return the symbolic string associated with the given error code, like
 253 "ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333.
 254
 255 .SS TASK
 256 .PP
 257 These functions return data about a task.  They all require
 258 a task handle as input, such as the value return by task_current() or the variables
 259 prev_task and next_task in the scheduler.ctxswitch probe alias.
 260
 261 .TP
 262 task_current:long()
 263 Return the task_struct of the current process.
 264
 265 .TP
 266 task_parent:long(task:long)
 267 Return the parent task_struct of the given task.
 268 .TP
 269 task_state:long(task:long)
 270 Return the state of the given task, which can be one of the following:
 271
 272    TASK_RUNNING           0
 273    TASK_INTERRUPTIBLE     1
 274    TASK_UNINTERRUPTIBLE   2
 275    TASK_STOPPED           4
 276    TASK_TRACED            8
 277    EXIT_ZOMBIE           16
 278    EXIT_DEAD             32
 279
 280 .TP
 281 task_execname:string(task:long)
 282 Return the name of the given task.
 283
 284 .TP
 285 task_pid:long(task:long)
 286 Return the process id of the given task.
 287
 288 .TP
 289 task_tid:long(task:long)
 290 Return the thread id of the given task.
 291
 292 .TP
 293 task_gid:long(task:long)
 294 Return the group id of the given task.
 295
 296 .TP
 297 task_egid:long(task:long)
 298 Return the effective group id of the given task.
 299
 300 .TP
 301 task_uid:long(task:long)
 302 Return the user id of the given task.
 303
 304 .TP
 305 task_euid:long(task:long)
 306 Return the effective user id of the given task.
 307
 308 .TP
 309 task_prio:long(task:long)
 310 Return the priority of the given task.
 311
 312 .TP
 313 task_nice:long(task:long)
 314 Return the nice value of the given task.
 315
 316 .TP
 317 task_cpu:long(task:long)
 318 Return the scheduled cpu for the given task.
 319
 320 .TP
 321 task_open_file_handles:long(task:long)
 322 Return the number of open file handles for the given task.
 323
 324 .TP
 325 task_max_file_handles:long(task:long)
 326 Return the maximum number of file handles for the given task.
 327
 328 .TP
 329 pid2task:long(pid:long)
 330 Return the task of the given process id.
 331
 332 .TP
 333 pid2execname:string(pid:long)
 334 Return the name of the given process id.
 335
 336 .SS CPU REGISTERS
 337 .TP
 338 registers_valid:long ()
 339 Return 1 if register() and u_register() can be used
 340 in the current context, or 0 otherwise.
 341 For example, registers_valid() returns 0 when called from a begin or end probe.
 342 .TP
 343 register:long (name:string)
 344 Return the value of the named CPU register,
 345 as it was saved when the current probe point was hit.
 346 If the register is 32 bits, it is sign-extended to 64 bits.
 347
 348 For the i386 architecture, the following names are recognized.
 349 (name1/name2 indicates that name1 and name2 are alternative names
 350 for the same register.)
 351 eax/ax, ebp/bp, ebx/bx, ecx/cx, edi/di, edx/dx, eflags/flags,
 352 eip/ip, esi/si, esp/sp, orig_eax/orig_ax,
 353 xcs/cs, xds/ds, xes/es, xfs/fs, xss/ss.
 354
 355 For the x86_64 architecture, the following names are recognized:
 356 64-bit registers:
 357 r8, r9, r10, r11, r12, r13, r14, r15,
 358 rax/ax, rbp/bp, rbx/bx, rcx/cx, rdi/di, rdx/dx,
 359 rip/ip, rsi/si, rsp/sp;
 360 32-bit registers:
 361 eax, ebp, ebx, ecx, edx, edi, edx, eip, esi, esp, flags/eflags, orig_eax;
 362 segment registers: xcs/cs, xss/ss.
 363
 364 For powerpc, the following names are recognized:
 365 r0, r1, ... r31, nip, msr, orig_gpr3, ctr, link, xer, ccr, softe, trap,
 366 dar, dsisr, result.
 367
 368 For s390x, the following names are recognized:
 369 r0, r1, ... r15, args, psw.mask, psw.addr, orig_gpr2, ilc, trap.
 370
 371 .TP
 372 u_register:long (name:string)
 373 Same as register(name), except that
 374 if the register is 32 bits, it is zero-extended to 64 bits.
 375
 376 .SS NUMBERED FUNCTION ARGUMENTS
 377 The functions in this section provide the values of a probed function's
 378 arguments.
 379 They can be called when you have hit
 380 a probe point at the entry to a function.
 381 Arguments are referred to by number, starting at 1.
 382 Ordinarily, you can access arguments by name as well,
 383 but you may find these functions useful if the code you are probing
 384 was built without debugging information.
 385
 386 On 32-bit architectures
 387 \(em and when probing 32-bit applications on 64-bit architectures \(em
 388 a 64-bit argument occupies two "arg slots."
 389 For example, if you are probing the following function
 390
 391    void f(int a, long long b, char *c)
 392
 393 you would refer to a, b, and c as int_arg(1), longlong_arg(2), and
 394 pointer_arg(3), respectively, on a 64-bit architecture;
 395 but on a 32-bit architecture, you would refer to c as pointer_arg(4)
 396 (since b occupies slots 2 and 3).
 397
 398 If the function you are probing doesn't follow the default rules
 399 for argument passing, you need to call one of the following functions
 400 (which see) in your handler before calling any *_arg function:
 401 asmlinkage(), fastcall(), or regparm().
 402 (This isn't necessary when referring to arguments only by name.)
 403 .TP
 404 int_arg:long (n:long)
 405 Return the value of argument n as a signed int
 406 (i.e., a 32-bit integer sign-extended to 64 bits).
 407 .TP
 408 uint_arg:long (n:long)
 409 Return the value of argument n as an unsigned int
 410 (i.e., a 32-bit integer zero-extended to 64 bits).
 411 .TP
 412 long_arg:long (n:long)
 413 Return the value of argument n as a signed long.
 414 On architectures where a long is 32 bits, the value is sign-extended to 64 bits.
 415 .TP
 416 ulong_arg:long (n:long)
 417 Return the value of argument n as an unsigned long.
 418 On architectures where a long is 32 bits, the value is zero-extended to 64 bits.
 419 .TP
 420 longlong_arg:long (n:long)
 421 Return the value of argument n as a 64-bit value.
 422 .TP
 423 ulonglong_arg:long (n:long)
 424 Same as longlong_arg(n).
 425 .TP
 426 pointer_arg:long (n:long)
 427 Same as ulong_arg(n).
 428 Use with any type of pointer.
 429 .TP
 430 s32_arg:long (n:long)
 431 Same as int_arg(n).
 432 .TP
 433 u32_arg:long (n:long)
 434 Same as uint_arg(n).
 435 .TP
 436 s64_arg:long (n:long)
 437 Same as longlong_arg(n).
 438 .TP
 439 u64_arg:long (n:long)
 440 Same as [u]longlong_arg(n).
 441 .TP
 442 asmlinkage:unknown ()
 443 The probed kernel function is declared asmlinkage in the source.
 444 .TP
 445 fastcall:unknown ()
 446 The probed kernel function is declared fastcall in the source.
 447 .TP
 448 regparm:unknown (n:long)
 449 The probed function was built with the gcc \-mregparm=n option.
 450 (The i386 kernel is built with \-mregparm=3, so systemtap considers
 451 regparm(3) the default for kernel functions on that architecture.)
 452
 453 For some architectures, the *_arg functions may reject unusually high
 454 values of n.
 455
 456 .SS QUEUE_STATS
 457 .PP
 458 The queue_stats tapset provides functions that, given notifications of
 459 elementary queuing events (wait, run, done), tracks averages such as
 460 queue length, service and wait times, utilization.  The following
 461 three functions should be called from appropriate probes, in sequence.
 462 .TP
 463 qs_wait:unknown (qname:string)
 464 Record that a new request was enqueued for the given queue name.
 465 .TP
 466 qs_run:unknown (qname:string)
 467 Record that a previously enqueued request was removed from the given
 468 wait queue and is now being serviced.
 469 .TP
 470 qs_done:unknown (qname:string)
 471 Record that a request originally from the given queue has completed
 472 being serviced.
 473 .\" XXX: qs_time
 474 .PP
 475 Functions with the prefix
 476 .BR qsq_
 477 are for querying the statistics averaged since the first queue operation
 478 (or when
 479 .BR qsq_start
 480 was called). Since statistics are often fractional, a scale parameter
 481 is multiplies the result to a more useful scale.  For some fractions,
 482 a scale of 100 will usefully return percentage numbers.
 483 .TP
 484 qsq_start:unknown (qname:string)
 485 Reset the statistics counters for the given queue, and start tracking
 486 anew from this moment.
 487 .TP
 488 qsq_print:unknown (qname:string)
 489 Print a line containing a selection of the given queue's statistics.
 490 .TP
 491 qsq_utilization:long (qname:string, scale:long)
 492 Return the fraction of elapsed time when the resource was utilized.
 493 .TP
 494 qsq_blocked:long (qname:string, scale:long)
 495 Return the fraction of elapsed time when the wait queue was used.
 496 .TP
 497 qsq_wait_queue_length:long (qname:string, scale:long)
 498 Return the average length of the wait queue.
 499 .TP
 500 qsq_service_time:long (qname:string, scale:long)
 501 Return the average time required to service a request.
 502 .TP
 503 qsq_wait_time:long (qname:string, scale:long)
 504 Return the average time a request took from being enqueued to completed.
 505 .TP
 506 qsq_throughput:long (qname:string, scale:long)
 507 Return the average rate of requests per scale units of time.
 508
 509 .SS INDENT
 510 .PP
 511 The indent tapset provides functions to generate indented lines for
 512 nested kinds of trace messages.  Each line contains a relative
 513 timestamp, and the process name / pid.
 514 .TP
 515 thread_indent:string (delta:long)
 516 Return a string with an appropriate indentation for this thread.
 517 Call it with a small positive or matching negative delta.
 518 If this is the outermost, initial level of indentation, reset the
 519 relative timestamp base to zero.
 520 .TP
 521 thread_timestamp:long ()
 522 Return an absolute timestamp value for use by the indentation function.
 523 The default function uses
 524 .IR gettimeofday_us
 525
 526 .SS SYSTEM
 527 .TP
 528 system (cmd:string)
 529 Runs a command on the system. The command will run in the background
 530 when the current probe completes.
 531
 532 .SS NUMA
 533 .TP
 534 addr_to_node:long (addr:long)
 535 Return which node the given address belongs to in a NUMA system.
 536
 537 .SS CTIME
 538 .TP
 539 ctime:string (seconds:long)
 540 Return a simple textual rendering (e.g., "Wed\ Jun\ 30\ 21:49:008\ 1993")
 541 of the given number of seconds since the epoch, as perhaps returned by
 542 .IR gettimeofday_s() .
 543
 544 .SS PERFMON
 545 .TP
 546 read_counter:long (handle:long)
 547 Returns the value for the processor's performance counter for the associated
 548 handle. The body of the a perfmon probe should set record
 549 the handle being used for that event.
 550
 551 .SS SOCKETS
 552 These functions convert arguments in the socket tapset back and
 553 forth between their numeric and string representations.
 554 See
 555 .IR stapprobes.socket (3stap)
 556 for details.
 557
 558 .TP
 559 sock_prot_num2str:string (proto:long)
 560 Returns the string representation of the given protocol value.
 561 .TP
 562 sock_prot_str2num:long (proto:string)
 563 Returns the numeric value associated with the given protocol string.
 564 .TP
 565 sock_fam_num2str:string (family:long)
 566 Returns the string representation of the given protocol family value.
 567 .TP
 568 sock_fam_str2num:long (family:string)
 569 Returns the numeric value associated with the given protocol family string.
 570 .TP
 571 sock_state_num2str:string (state:long)
 572 Returns the string representation of the given socket state value.
 573 .TP
 574 sock_state_str2num:long (state:string)
 575 Returns the numeric value associated with the given socket state string.
 576 .TP
 577 sock_type_num2str:string (type:long)
 578 Returns the string representation of the given socket type value.
 579 .TP
 580 sock_type_str2num:long (type:string)
 581 Returns the numeric value associated with the given socket type string.
 582 .TP
 583 sock_flags_num2str:string (flags:long)
 584 Returns the string representation of the given socket flags value.
 585 .TP
 586 msg_flags_num2str:string (flags:long)
 587 Returns the string representation of the given message flags bit map.
 588
 589 .SS INET
 590 These functions convert between network (big-endian) and host byte order, like their
 591 namesake C functions.
 592 .TP
 593 ntohll:long (x:long)
 594 Convert from network to host byte order, 64-bit.
 595 .TP
 596 ntohl:long (x:long)
 597 Convert from network to host byte order, 32-bit.
 598 .TP
 599 ntohs:long (x:long)
 600 Convert from network to host byte order, 16-bit.
 601 .TP
 602 htonll:long (x:long)
 603 Convert from host to network byte order, 64-bit.
 604 .TP
 605 htonl:long (x:long)
 606 Convert from host to network byte order, 32-bit.
 607 .TP
 608 htons:long (x:long)
 609 Convert from host to network byte order, 16-bit.
 610
 611 .SS SIGNAL
 612 .TP
 613 get_sa_flags:long (act:long)
 614 Returns the numeric value of sa_flags.
 615 .TP
 616 get_sa_handler:long (act:long)
 617 Returns the numeric value of sa_handler.
 618 .TP
 619 sigset_mask_str:string (mask:long)
 620 Returns the string representation of the sigset sa_mask.
 621 .TP
 622 is_sig_blocked:long (task:long, sig:long)
 623 Returns 1 if the signal is currently blocked, or 0 if it is not.
 624 .TP
 625 sa_flags_str:string (sa_flags:long)
 626 Returns the string representation of sa_flags.
 627 .TP
 628 sa_handler_str(handler)
 629 Returns the string representation of sa_handler. If it is not SIG_DFL, SIG_IGN
 630 or SIG_ERR, it will return the address of the handler.
 631 .TP
 632 signal_str(num)
 633 Returns the string representation of the given signal number.
 634
 635 .SS DEVICE
 636 .TP
 637 MAJOR:long(dev:long)
 638 Extracts the major device number from a kernel device number (kdev_t).
 639 .TP
 640 MINOR:long(dev:long)
 641 Extracts the minor device number from a kernel device number (kdev_t).
 642 .TP
 643 MKDEV:long(major:long, minor:long)
 644 Creates a value that can be compared to a kernel device number (kdev_t).
 645 .TP
 646 usrdev2kerndev:long(dev:long)
 647 Converts a user-space device number into the format used in the kernel.
 648
 649 .SH FILES
 650 .nh
 651 .IR @prefix@/share/systemtap/tapset
 652 .hy
 653
 654 .SH SEE ALSO
 655 .IR stap (1)