Provided by: systemtap-doc_1.6-1ubuntu1_all bug

NAME

       stapfuncs - systemtap functions

DESCRIPTION

       The  following  sections  enumerate a few of public functions provided by standard tapsets
       installed, show in the stappaths (7) manual page.   Most are  individually  documented  in
       the 3stap manual section, with the function:: prefix.

       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 stap option
       -p2.  Examples:

       example1:long (v:string, k:long)
              In function "example1", do something with the given  string  and  integer.   Return
              some integer.

       example2:unknown ()
              In  function  "example2", do something.  There is no explicit return value and take
              no parameters.

   TARGET_SET
       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.

       target_set_report:unknown ()
              Print a report about the target set, and their ancestry.

   ERRNO
       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.

   REGISTERS
       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.

       u_register:long (name:string)
              Same as register(name), except that if the register is 32 bits, it is zero-extended
              to 64 bits.

   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 — and when probing 32-bit applications on 64-bit architectures — 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.)

       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).

       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).

       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.

       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.

       longlong_arg:long (n:long)
              Return the value of argument n as a 64-bit value.

       ulonglong_arg:long (n:long)
              Same as longlong_arg(n).

       pointer_arg:long (n:long)
              Same as ulong_arg(n).  Use with any type of pointer.

       s32_arg:long (n:long)
              Same as int_arg(n).

       u32_arg:long (n:long)
              Same as uint_arg(n).

       s64_arg:long (n:long)
              Same as longlong_arg(n).

       u64_arg:long (n:long)
              Same as [u]longlong_arg(n).

       asmlinkage:unknown ()
              The probed kernel function is declared asmlinkage in the source.

       fastcall:unknown ()
              The probed kernel function is declared fastcall in the source.

       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.

   QUEUE_STATS
       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.

       qs_wait:unknown (qname:string)
              Record that a new request was enqueued for the given queue name.

       qs_run:unknown (qname:string)
              Record that a previously enqueued request was removed from the given wait queue and
              is now being serviced.

       qs_done:unknown (qname:string)
              Record that a request originally from the given queue has completed being serviced.

       Functions  with  the  prefix qsq_ are for querying the statistics averaged since the first
       queue operation (or when 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.

       qsq_start:unknown (qname:string)
              Reset the statistics counters for the given queue, and  start  tracking  anew  from
              this moment.

       qsq_print:unknown (qname:string)
              Print a line containing a selection of the given queue's statistics.

       qsq_utilization:long (qname:string, scale:long)
              Return the fraction of elapsed time when the resource was utilized.

       qsq_blocked:long (qname:string, scale:long)
              Return the fraction of elapsed time when the wait queue was used.

       qsq_wait_queue_length:long (qname:string, scale:long)
              Return the average length of the wait queue.

       qsq_service_time:long (qname:string, scale:long)
              Return the average time required to service a request.

       qsq_wait_time:long (qname:string, scale:long)
              Return the average time a request took from being enqueued to completed.

       qsq_throughput:long (qname:string, scale:long)
              Return the average rate of requests per scale units of time.

   INDENT
       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.

       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.

       thread_timestamp:long ()
              Return an absolute timestamp value  for  use  by  the  indentation  function.   The
              default function uses gettimeofday_us

   SYSTEM
       system (cmd:string)
              Runs  a  command  on  the  system.  The command will run in the background when the
              current probe completes.

   INET
       These functions convert between network (big-endian)  and  host  byte  order,  like  their
       namesake C functions.

       ntohll:long (x:long)
              Convert from network to host byte order, 64-bit.

       ntohl:long (x:long)
              Convert from network to host byte order, 32-bit.

       ntohs:long (x:long)
              Convert from network to host byte order, 16-bit.

       htonll:long (x:long)
              Convert from host to network byte order, 64-bit.

       htonl:long (x:long)
              Convert from host to network byte order, 32-bit.

       htons:long (x:long)
              Convert from host to network byte order, 16-bit.

   SIGNAL
       get_sa_flags:long (act:long)
              Returns the numeric value of sa_flags.

       get_sa_handler:long (act:long)
              Returns the numeric value of sa_handler.

       sigset_mask_str:string (mask:long)
              Returns the string representation of the sigset sa_mask.

       is_sig_blocked:long (task:long, sig:long)
              Returns 1 if the signal is currently blocked, or 0 if it is not.

       sa_flags_str:string (sa_flags:long)
              Returns the string representation of sa_flags.

       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.

       signal_str(num)
              Returns the string representation of the given signal number.

   DEVICE
       MAJOR:long(dev:long)
              Extracts the major device number from a kernel device number (kdev_t).

       MINOR:long(dev:long)
              Extracts the minor device number from a kernel device number (kdev_t).

       MKDEV:long(major:long, minor:long)
              Creates a value that can be compared to a kernel device number (kdev_t).

       usrdev2kerndev:long(dev:long)
              Converts a user-space device number into the format used in the kernel.

FILES

       More files and their corresponding paths can be found in the stappaths (7) manual page.

SEE ALSO

       stap(1), function::*(3stap), tapset::*(3stap), stappaths(7)

                                                                                 STAPFUNCS(3stap)