stapex.3stap

   1 .\" -*- nroff -*-
   2 .TH STAPEX 3stap
   3 .SH NAME
   4 stapex \- systemtap examples
   5
   6 .\" macros
   7 .de SAMPLE
   8 .br
   9 .RS
  10 .nf
  11 .nh
  12 ..
  13 .de ESAMPLE
  14 .hy
  15 .fi
  16 .RE
  17 ..
  18
  19 .SH LANGUAGE BASICS
  20 These examples give a feel for basic systemtap syntax and
  21 control structures.
  22
  23 .SAMPLE
  24 global odds, evens
  25
  26 probe begin {
  27   # "no" and "ne" are local integers
  28   for (i=0; i<10; i++) {
  29     if (i % 2) odds [no++] = i
  30     else evens [ne++] = i
  31   }
  32   delete odds[2]
  33   delete evens[3]
  34   exit ()
  35 }
  36
  37 probe end {
  38   foreach (x+ in odds) {
  39     printf ("odds[%d] = %d\n", x, odds[x])
  40   }
  41   foreach (x in evens\-) {
  42     printf ("evens[%d] = %d\n", x, evens[x])
  43   }
  44 }
  45 .ESAMPLE
  46 This prints:
  47 .SAMPLE
  48 odds[1] = 1
  49 odds[3] = 5
  50 odds[4] = 7
  51 odds[5] = 9
  52 evens[5] = 8
  53 evens[4] = 6
  54 evens[2] = 2
  55 evens[1] = 0
  56 .ESAMPLE
  57 Note that all variables types are inferred, and that all locals
  58 and globals are automatically initialized.
  59
  60 .PP
  61 This script prints the primes between 0 and 49.
  62 .SAMPLE
  63 function isprime (x) {
  64   if (x < 2) return 0
  65   for (i=2; i<x; i++) {
  66     if (x % i == 0) return 0
  67     if (i * i > x) break
  68   }
  69   return 1
  70 }
  71 probe begin {
  72   for (i=0; i<50; i++)
  73     if (isprime (i)) printf("%d\n", i)
  74   exit()
  75 }
  76 .ESAMPLE
  77
  78 .PP
  79 This script demonstrates recursive functions.
  80 .SAMPLE
  81 function fibonacci(i) {
  82   if (i < 1) error ("bad number")
  83   if (i == 1) return 1
  84   if (i == 2) return 2
  85   return fibonacci (i\-1) + fibonacci (i\-2)
  86 }
  87 probe begin {
  88   printf ("11th fibonacci number: %d\n", fibonacci (11))
  89   exit ()
  90 }
  91 .ESAMPLE
  92 Any larger number may exceed the MAXACTION or MAXNESTING
  93 limits, and result in an error.
  94
  95
  96 .SH PROBING
  97
  98 To trace entry and exit from a function, use a pair of probes:
  99 .SAMPLE
 100 probe kernel.function("sys_mkdir") { println ("enter") }
 101 probe kernel.function("sys_mkdir").return { println ("exit") }
 102 .ESAMPLE
 103
 104 To list the probeable functions in the kernel, use the listings mode.
 105 .SAMPLE
 106 % stap \-l \[aq]kernel.function("*")\[aq]
 107 .ESAMPLE
 108
 109 To list the probeable functions and local variables in the kernel, use another listings mode.
 110 .SAMPLE
 111 % stap \-L \[aq]kernel.function("*")\[aq]
 112 .ESAMPLE
 113
 114 .SH MORE EXAMPLES
 115
 116 The directory to find more examples can be found in the stappaths (7) manual page.
 117
 118 .SH SEE ALSO
 119 .IR stap (1)
 120 .IR stapprobes (3stap)
 121 .IR stapfuncs (3stap)
 122 .IR stappaths (7)