Merge pull request #949 from ShelbyFrances/trace_enhancements

tools/trace accepts abspath arguments to -I (and some doc tweaks)

tools/argdist.py

@@ -619,7 +619,8 @@ argdist -p 2780 -z 120 \\
                   "(see examples below)")
                 parser.add_argument("-I", "--include", action="append",
                   metavar="header",
-                  help="additional header files to include in the BPF program")
+                  help="additional header files to include in the BPF program "
+                       "as either full path, or relative to '/usr/include'")
                 self.args = parser.parse_args()
                 self.usdt_ctx = None
 
@@ -640,7 +641,12 @@ struct __string_t { char s[%d]; };
 #include <uapi/linux/ptrace.h>
                 """ % self.args.string_size
                 for include in (self.args.include or []):
-                        bpf_source += "#include <%s>\n" % include
+                        if include.startswith((".", "/")):
+                                include = os.path.abspath(include)
+                                bpf_source += "#include \"%s\"\n" % include
+                        else:
+                                bpf_source += "#include <%s>\n" % include
+
                 bpf_source += BPF.generate_auto_includes(
                                 map(lambda p: p.raw_spec, self.probes))
                 for probe in self.probes:

tools/argdist_example.txt

@@ -363,6 +363,7 @@ optional arguments:
                         below)
   -I header, --include header
                         additional header files to include in the BPF program
+                        as either full path, or relative to '/usr/include'
 
 Probe specifier syntax:
         {p,r,t,u}:{[library],category}:function(signature)[:type[,type...]:expr[,expr...][:filter]][#label]

tools/trace.py

@@ -624,7 +624,8 @@ trace 'p::SyS_nanosleep(struct timespec *ts) "sleep for %lld ns", ts->tv_nsec'
                   help="probe specifier (see examples)")
                 parser.add_argument("-I", "--include", action="append",
                   metavar="header",
-                  help="additional header files to include in the BPF program")
+                  help="additional header files to include in the BPF program "
+                       "as either full path, or relative to '/usr/include'")
                 self.args = parser.parse_args()
                 if self.args.tgid and self.args.pid:
                         parser.error("only one of -p and -t may be specified")
@@ -644,7 +645,11 @@ trace 'p::SyS_nanosleep(struct timespec *ts) "sleep for %lld ns", ts->tv_nsec'
 
 """
                 for include in (self.args.include or []):
-                        self.program += "#include <%s>\n" % include
+                        if include.startswith((".", "/")):
+                                include = os.path.abspath(include)
+                                self.program += "#include \"%s\"\n" % include
+                        else:
+                                self.program += "#include <%s>\n" % include
                 self.program += BPF.generate_auto_includes(
                         map(lambda p: p.raw_probe, self.probes))
                 for probe in self.probes:

tools/trace_example.txt

@@ -2,8 +2,8 @@ Demonstrations of trace.
 
 
 trace probes functions you specify and displays trace messages if a particular
-condition is met. You can control the message format to display function 
-arguments and return values. 
+condition is met. You can control the message format to display function
+arguments and return values.
 
 For example, suppose you want to trace all commands being exec'd across the
 system:
@@ -135,6 +135,16 @@ TIME     PID    COMM         FUNC             -
 In the previous invocation, arg1 and arg2 are the class name and method name
 for the Ruby method being invoked.
 
+You can also trace exported functions from shared libraries, or an imported
+function on the actual executable:
+
+# sudo ./trace.py 'r:/usr/lib64/libtinfo.so:curses_version "Version=%s", retval'
+# tput -V
+
+PID    TID    COMM         FUNC             -
+21720  21720  tput         curses_version   Version=ncurses 6.0.20160709
+^C
+
 
 Occasionally, it can be useful to filter specific strings. For example, you
 might be interested in open() calls that open a specific file:
@@ -164,8 +174,12 @@ PID    TID    COMM         FUNC             -
 777    785    automount    SyS_nanosleep    sleep for 500000000 ns
 ^C
 
+Remember to use the -I argument include the appropriate header file. We didn't
+need to do that here because `struct timespec` is used internally by the tool,
+so it always includes this header file.
+
 
-As a final example, let's trace open syscalls for a specific process. By 
+As a final example, let's trace open syscalls for a specific process. By
 default, tracing is system-wide, but the -p switch overrides this:
 
 # trace -p 2740 'do_sys_open "%s", arg2' -T
@@ -215,6 +229,7 @@ optional arguments:
   -U, --user-stack      output user stack trace
   -I header, --include header
                         additional header files to include in the BPF program
+                        as either full path, or relative to '/usr/include'
 
 EXAMPLES: