Provided by: systemtap_0.0.20080705-2ubuntu1_i386 bug

NAME

       stapfuncs - systemtap functions

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

   PRINTING
       log:unknown (msg:string)
              Writes the given string to the common trace buffer.   Append  an
              implicit  end-of-line.  Deprecated.  Please use the faster print
              functions.

       warn:unknown (msg:string)
              Write the  given  string  to  the  warning  stream.   Append  an
              implicit end-of-line.  staprun prepends the string "WARNING:".

       error:unknown (msg:string)
              An  error  has  occurred.   Write  the given string to the error
              stream.  Append an implicit end-of-line.  staprun  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 exit().

       exit:unknown ()
              Enqueue a request to shut down the systemtap session.  This does
              not unwind the  current  probe  handler,  nor  block  new  probe
              handlers.   staprun  will  shortly  respond  to  the request and
              initiate an orderly shutdown.

   CONVERSIONS
       These functions access kernel or user-space data.  They try to validate
       the  supplied  addresses, and can thus result in errors if the pointers
       are invalid, or if a user-space access would cause a fault.

       kernel_string:string (addr:long)
              Copy a 0-terminated string from kernel space at given address.

       kernel_string_n:string (addr:long, n:long)
              Similar with kernel_string, except that not more  than  n  bytes
              are  copied.   Thus,  if  there are null bytes among the first n
              bytes, it is same as kernel_string(addr). If not, n  bytes  will
              be copied and a null byte will be padded to the end.

       kernel_long:long (addr:long)
              Copy a long from kernel space at given address.

       kernel_int:long (addr:long)
              Copy an int from kernel space at given address.

       kernel_short:long (addr:long)
              Copy a short from kernel space at given address.

       kernel_char:long (addr:long)
              Copy a char from kernel space at given address.

       user_string:string (addr:long)
              Copy  a  string from user space at given address.  If the access
              would fault, return "<unknown>" and signal no errors.

       user_string2:string (addr:long, err_msg:string)
              Copy a string from user space at given address.  If  the  access
              would fault, return instead the err_msg value.

       user_string_warn:string (addr:long)
              Copy  a  string from user space at given address.  If the access
              would fault, signal a warning and return "<unknown>".

       user_string_quoted:string (addr:long)
              Copy a string from  user  space  at  given  address.  Any  ASCII
              characters   that   are   not  printable  are  replaced  by  the
              corresponding escape sequence in the returned string.

       user_string_n:string (addr:long, n:long)
              Copy a string of n bytes from user space at  given  address.  If
              the access would fault, return "<unknown>".

       user_string_n2:string (addr:long, n:long, err_msg:string)
              Copy  a  string  of n bytes from user space at given address. If
              the access would fault, return the err_msg value.

       user_string_n_warn:string (addr:long, n:long)
              Copy a string of n bytes from user space at  given  address.  If
              the access would fault, signal a warning and return "<unknown>".

       user_string_n_quoted:string (addr:long, n:long)
              Copy a string of n bytes from user space at given  address.  Any
              ASCII  characters  that  are  not  printable are replaced by the
              corresponding escape sequence in the  returned  string.  If  the
              access would fault, return "<unknown>".

       user_short:long (addr:long)
              Copy  a  short  from  user space at given address. If the access
              would fault, return 0.

       user_short_warn:long (addr:long)
              Copy a short from user space at given  address.  If  the  access
              would fault, signal a warning and return 0.

       user_int:long (addr:long)
              Copy  an  int  from  user  space at given address. If the access
              would fault, return 0.

       user_int_warn:long (addr:long)
              Copy an int from user space at  given  address.  If  the  access
              would fault, signal a warning and return 0.

       user_long:long (addr:long)
              Copy  a  long  from  user  space at given address. If the access
              would fault, return 0.

       user_long_warn:long (addr:long)
              Copy a long from user space at  given  address.  If  the  access
              would fault, signal a warning and return 0.

       user_char:long (addr:long)
              Copy  a  char  from  user  space at given address. If the access
              would fault, return 0.

       user_char_warn:long (addr:long)
              Copy a char from user space at  given  address.  If  the  access
              would fault, signal a warning and return 0.

   STRING
       strlen:long (str:string)
              Return the number of characters in str.

       substr:string (str:string,start:long, stop:long)
              Return  the  substring  of str starting from character start and
              ending at character stop.

       isinstr:long (s1:string, s2:string)
              Return 1 if string s1 contains string s2, returns 0 otherwise.

       strtol:long (str:string, base:long)
              Convert the string representation of a number to  a  long  using
              the   numbering   system   specified   by  base.   For  example,
              strtol("1000", 16) returns 4096.  Returns 0 if the string cannot
              be converted.

       tokenize:string (str:string, delim:string)
              Return  the next token in the given str string, where the tokens
              are delimited by one of the characters in the delim string.   If
              the str string is not blank, it returns the first token.  If the
              str string is blank, it returns the next  token  in  the  string
              passed  in  the  previous  call  to tokenize. If no delimiter is
              found, the entire remaining str  string  is  returned.   Returns
              blank when no more tokens are left.

   TIMESTAMP
       get_cycles:long ()
              Return the processor cycle counter value, or 0 if unavailable.

       gettimeofday_ns:long ()
              Return the number of nanoseconds since the UNIX epoch.

       gettimeofday_us:long ()
              Return the number of microseconds since the UNIX epoch.

       gettimeofday_ms:long ()
              Return the number of milliseconds since the UNIX epoch.

       gettimeofday_s:long ()
              Return the number of seconds since the UNIX epoch.

   CONTEXT INFO
       cpu:long ()
              Return the current cpu number.

       execname:string ()
              Return the name of the current process.

       pexecname:string()
              Return the name of the parent process.

       tid:long ()
              Return the id of the current thread.

       pid:long ()
              Return the id of the current process.

       ppid:long ()
              Return the id of the parent process.

       uid:long ()
              Return the uid of the current process.

       euid:long ()
              Return the effective uid of the current process.

       gid:long ()
              Return the gid of the current process.

       egid:long ()
              Return the effective gid of the current process.

       print_regs:unknown ()
              Print a register dump.

       backtrace:string ()
              Return  a  string  of  hex addresses that are a backtrace of the
              stack.  It may be truncated due to maximum string length.

       print_stack:unknown (bt:string)
              Perform a symbolic lookup of the addresses in the given  string,
              which   is  assumed  to  be  the  result  of  a  prior  call  to
              backtrace().  Print one line per address, including the address,
              the name of the function containing the address, and an estimate
              of its position within that function.  Return nothing.

       print_backtrace:unknown ()
              Equivalent to print_stack(backtrace()), except that deeper stack
              nesting may be supported.  Return nothing.

       pp:string ()
              Return  the  probe  point  associated with the currently running
              probe handler, including alias and wildcard expansion effects.

       probefunc:string ()
              Return the probe point’s function name, if known.

       probemod:string ()
              Return the probe point’s module name, if known.

       target:long ()
              Return the pid of the target process.

       user_mode:long ()
              Return 1 if the probe point occurred in user-mode.

       is_return:long ()
              Return 1 if the probe point is a return probe.  Deprecated.

   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.

   TASK
       These functions return data about a task.   They  all  require  a  task
       handle  as  input,  such  as  the value return by task_current() or the
       variables prev_task and  next_task  in  the  scheduler.ctxswitch  probe
       alias.

       task_current:long()
              Return the task_struct of the current process.

       task_parent:long(task:long)
              Return the parent task_struct of the given task.

       task_state:long(task:long)
              Return  the  state  of  the  given task, which can be one of the
              following:

                 TASK_RUNNING           0
                 TASK_INTERRUPTIBLE     1
                 TASK_UNINTERRUPTIBLE   2
                 TASK_STOPPED           4
                 TASK_TRACED            8
                 EXIT_ZOMBIE           16
                 EXIT_DEAD             32

       task_execname:string(task:long)
              Return the name of the given task.

       task_pid:long(task:long)
              Return the process id of the given task.

       task_tid:long(task:long)
              Return the thread id of the given task.

       task_gid:long(task:long)
              Return the group id of the given task.

       task_egid:long(task:long)
              Return the effective group id of the given task.

       task_uid:long(task:long)
              Return the user id of the given task.

       task_euid:long(task:long)
              Return the effective user id of the given task.

       task_prio:long(task:long)
              Return the priority of the given task.

       task_nice:long(task:long)
              Return the nice value of the given task.

       task_cpu:long(task:long)
              Return the scheduled cpu for the given task.

       task_open_file_handles:long(task:long)
              Return the number of open file handles for the given task.

       task_max_file_handles:long(task:long)
              Return the maximum number of file handles for the given task.

   CPU REGISTERS
       registers_valid:long ()
              Return 1 if register() and  u_register()  can  be  used  in  the
              current context, or 0 otherwise.  For example, registers_valid()
              returns 0 when called from a begin or end probe.

       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: r1, r2... r31,
              nip, msr, orig_gpr3, ctr, link,  xer,  ccr,  softe,  trap,  dar,
              dsisr, result.

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

   NUMA
       addr_to_node:long (addr:long)
              Return which node the given address belongs to in a NUMA system.

   CTIME
       ctime:string (seconds:long)
              Return     a      simple      textual      rendering      (e.g.,
              "Wed Jun 30 21:49:008 1993")  of  the  given  number  of seconds
              since the epoch, as perhaps returned by gettimeofday_s().

   PERFMON
       read_counter:long (handle:long)
              Returns the value for the processor’s  performance  counter  for
              the  associated  handle.  The body of the a perfmon probe should
              set record the handle being used for that event.

   SOCKETS
       These functions convert arguments in the socket tapset back  and  forth
       between    their    numeric    and    string    representations.    See
       stapprobes.socket(5) for details.

       sock_prot_num2str:string (proto:long)
              Returns the string representation of the given protocol value.

       sock_prot_str2num:long (proto:string)
              Returns the numeric value associated  with  the  given  protocol
              string.

       sock_fam_num2str:string (family:long)
              Returns  the  string representation of the given protocol family
              value.

       sock_fam_str2num:long (family:string)
              Returns the numeric value associated  with  the  given  protocol
              family string.

       sock_state_num2str:string (state:long)
              Returns  the  string  representation  of  the given socket state
              value.

       sock_state_str2num:long (state:string)
              Returns the numeric value associated with the given socket state
              string.

       sock_type_num2str:string (type:long)
              Returns  the  string  representation  of  the  given socket type
              value.

       sock_type_str2num:long (type:string)
              Returns the numeric value associated with the given socket  type
              string.

       sock_flags_num2str:string (flags:long)
              Returns  the  string  representation  of  the given socket flags
              value.

       msg_flags_num2str:string (flags:long)
              Returns the string representation of the given message flags bit
              map.

   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

       /usr/share/systemtap/tapset

SEE ALSO

       stap(1)