allow stand-alone executables

docs/reference_guide.md

@@ -170,6 +170,28 @@ iscsid is sleeping.
 [...]
 ```
 
+It can also be made executable to run stand-alone. Start by adding an interpreter line at the top (`#!`) with the path to your installed bpftrace (/usr/local/bin is the default):
+
+```
+     1	#!/usr/local/bin/bpftrace
+     2	
+     3	tracepoint:syscalls:sys_enter_nanosleep
+     4	{
+     5	        printf("%s is sleeping.\n", comm);
+     6	}
+```
+
+Then make it executable:
+
+```
+# chmod 755 sleepers.bt
+# ./sleepers.bt
+Attaching 1 probe...
+iscsid is sleeping.
+iscsid is sleeping.
+[...]
+```
+
 ## 4. `-l`: Listing Probes
 
 Probes from the tracepoint and kprobe libraries can be listed with `-l`.

src/lexer.l

@@ -39,6 +39,7 @@ path   :(\\.|[_\-\./a-zA-Z0-9])*:
 {hspace}+               { loc.step(); }
 {vspace}+               { loc.lines(yyleng); loc.step(); }
 
+^"#!".*$                // executable line
 "//".*$                 // single-line comments
 "/*"                    BEGIN(COMMENT);  // multi-line comments; see flex(1)
 <COMMENT>"/*"           driver.error(loc, std::string("nested comments unsupported"));
@@ -87,7 +88,7 @@ pid|tid|cgroup|uid|gid|nsecs|cpu|comm|stack|ustack|arg[0-9]|retval|func|name|cur
 "~"                     { return Parser::make_BNOT(loc); }
 "."                     { return Parser::make_DOT(loc); }
 "->"                    { return Parser::make_PTR(loc); }
-"#".*                   { return Parser::make_CPREPROC(yytext, loc); }
+"#"[^!].*               { return Parser::make_CPREPROC(yytext, loc); }
 "if"                    { return Parser::make_IF(yytext, loc); }
 "else"                  { return Parser::make_ELSE(yytext, loc); }
 "?"                     { return Parser::make_QUES(loc); }

tools/bashreadline.bt

+#!/usr/local/bin/bpftrace
 /*
  * bashreadline    Print entered bash commands from all running shells.
  *                 For Linux, uses bpftrace and eBPF.

tools/bashreadline_example.txt

@@ -4,7 +4,7 @@ Demonstrations of bashreadline, the Linux bpftrace/eBPF version.
 This prints bash commands from all running bash shells on the system. For
 example:
 
-# bpftrace bashreadline.bt
+# bashreadline.bt
 Attaching 2 probes...
 Tracing bash commands... Hit Ctrl-C to end.
 TIME      PID    COMMAND

tools/biolatency.bt

+#!/usr/local/bin/bpftrace
 /*
  * biolatency.bt	Block I/O latency as a histogram.
  *			For Linux, uses bpftrace, eBPF.

tools/biosnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * biosnoop.bt   Block I/O tracing tool, showing per I/O latency.
  *               For Linux, uses bpftrace, eBPF.

tools/biosnoop_example.txt

@@ -4,7 +4,7 @@ Demonstrations of biosnoop, the Linux BPF/bpftrace version.
 This traces block I/O, and shows the issuing process (at least, the process
 that was on-CPU at the time of queue insert) and the latency of the I/O:
 
-# bpftrace biosnoop.bt
+# biosnoop.bt
 Attaching 4 probes...
 TIME(ms)     COMM             PID    LAT(ms)
 611          bash             4179        10
@@ -35,7 +35,7 @@ program start.
 
 An example of some background flushing:
 
-# bpftrace biosnoop.bt
+# biosnoop.bt
 Attaching 4 probes...
 TIME(ms)     COMM             PID    LAT(ms)
 2966         jbd2/nvme0n1-8   615          0

tools/bitesize.bt

+#!/usr/local/bin/bpftrace
 /*
  * bitesize	Show disk I/O size as a histogram.
  *		For Linux, uses bpftrace and eBPF.

tools/bitesize_example.txt

@@ -4,7 +4,7 @@ Demonstrations of bitesize, the Linux bpftrace/eBPF version.
 This traces disk I/O via the block I/O interface, and prints a summary of I/O
 sizes as histograms for each process name. For example:
 
-# bpftrace bitesize.bt
+# bitesize.bt
 Attaching 3 probes...
 Tracing block device I/O... Hit Ctrl-C to end.
 ^C

tools/capable.bt

+#!/usr/local/bin/bpftrace
 /*
  * capable	Trace security capabilitiy checks (cap_capable()).
  *		For Linux, uses bpftrace and eBPF.

tools/cpuwalk.bt

+#!/usr/local/bin/bpftrace
 /*
  * cpuwalk	Sample which CPUs are executing processes.
  *		For Linux, uses bpftrace and eBPF.

tools/dcsnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * dcsnoop	Trace directory entry cache (dcache) lookups.
  *		For Linux, uses bpftrace and eBPF.

tools/execsnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * execsnoop.bt   Trace new processes via exec() syscalls.
  *                For Linux, uses bpftrace and eBPF.

tools/execsnoop_example.txt

@@ -3,7 +3,7 @@ Demonstrations of execsnoop, the Linux BPF/bpftrace version.
 
 Tracing all new process execution (via exec()):
 
-# bpftrace execsnoop.bt
+# execsnoop.bt
 Attaching 3 probes...
 TIME(ms)   PID   ARGS
 2460       3466  ls --color=auto -lh execsnoop.bt execsnoop.bt.0 execsnoop.bt.1

tools/gethostlatency.bt

+#!/usr/local/bin/bpftrace
 /*
  * gethostlatency	Trace getaddrinfo/gethostbyname[2] calls.
  *			For Linux, uses bpftrace and eBPF.

tools/gethostlatency_example.txt

@@ -5,7 +5,7 @@ This traces host name lookup calls (getaddrinfo(), gethostbyname(), and
 gethostbyname2()), and shows the PID and command performing the lookup, the
 latency (duration) of the call in milliseconds, and the host string:
 
-# bpftrace gethostlatency.bt
+# gethostlatency.bt
 Attaching 7 probes...
 Tracing getaddr/gethost calls... Hit Ctrl-C to end.
 TIME      PID    COMM              LATms HOST

tools/killsnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * killsnoop	Trace signals issued by the kill() syscall.
  *		For Linux, uses bpftrace and eBPF.

tools/killsnoop_example.txt

@@ -3,7 +3,7 @@ Demonstrations of killsnoop, the Linux bpftrace/eBPF version.
 
 This traces signals sent via the kill() syscall. For example:
 
-# bpftrace killsnoop.bt
+# killsnoop.bt
 Attaching 3 probes...
 Tracing kill() signals... Hit Ctrl-C to end.
 TIME      PID    COMM             SIG  TPID   RESULT

tools/loads.bt

+#!/usr/local/bin/bpftrace
 /*
  * loads	Prints load averages.
  *		For Linux, uses bpftrace and eBPF.

tools/loads_example.txt

@@ -5,7 +5,7 @@ This is a simple tool that prints the system load averages, to three decimal
 places each (not that it really matters), as a demonstration of fetching
 kernel structures from bpftrace:
 
-# bpftrace loads.bt
+# loads.bt
 Attaching 2 probes...
 Reading load averages... Hit Ctrl-C to end.
 21:29:17 load averages: 2.091 2.048 1.947

tools/mdflush.bt

+#!/usr/local/bin/bpftrace
 /*
  * mdflush	Trace md flush events.
  *		For Linux, uses bpftrace and eBPF.

tools/mdflush_example.txt

@@ -4,7 +4,7 @@ Demonstrations of mdflush, the Linux bpftrace/eBPF version.
 The mdflush tool traces flushes at the md driver level, and prints details
 including the time of the flush:
 
-# ./mdflush.bt
+# mdflush.bt
 Tracing md flush requests... Hit Ctrl-C to end.
 TIME     PID    COMM             DEVICE
 03:13:49 16770  sync             md0

tools/oomkill.bt

+#!/usr/local/bin/bpftrace
 /*
  * oomkill	Trace OOM killer.
  *		For Linux, uses bpftrace and eBPF.

tools/oomkill_example.txt

@@ -4,7 +4,7 @@ Demonstrations of oomkill, the Linux bpftrace/eBPF version.
 oomkill is a simple program that traces the Linux out-of-memory (OOM) killer,
 and shows basic details on one line per OOM kill:
 
-# ./oomkill
+# oomkill
 Tracing oom_kill_process()... Ctrl-C to end.
 21:03:39 Triggered by PID 3297 ("ntpd"), OOM kill of PID 22516 ("perl"), 3850642 pages, loadavg: 0.99 0.39 0.30 3/282 22724
 21:03:48 Triggered by PID 22517 ("perl"), OOM kill of PID 22517 ("perl"), 3850642 pages, loadavg: 0.99 0.41 0.30 2/282 22932

tools/opensnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * opensnoop	Trace open() syscalls.
  *		For Linux, uses bpftrace and eBPF.

tools/opensnoop_example.txt

@@ -4,7 +4,7 @@ Demonstrations of opensnoop, the Linux bpftrace/eBPF version.
 opensnoop traces the open() syscall system-wide, and prints various details.
 Example output:
 
-# bpftrace opensnoop.bt
+# opensnoop.bt
 Attaching 3 probes...
 Tracing open syscalls... Hit Ctrl-C to end.
 PID    COMM               FD ERR PATH

tools/pidpersec.bt

+#!/usr/local/bin/bpftrace
 /*
  * pidpersec	Count new procesess (via fork).
  *		For Linux, uses bpftrace and eBPF.

tools/runqlat.bt

+#!/usr/local/bin/bpftrace
 /*
  * runqlat.bt	CPU scheduler run queue latency as a histogram.
  *		For Linux, uses bpftrace, eBPF.

tools/runqlat_example.txt

@@ -5,7 +5,7 @@ This traces time spent waiting in the CPU scheduler for a turn on-CPU. This
 metric is often called run queue latency, or scheduler latency. This tool shows
 this latency as a power-of-2 histogram in nanoseconds. For example:
 
-# bpftrace runqlat.bt
+# runqlat.bt
 Attaching 5 probes...
 Tracing CPU scheduler... Hit Ctrl-C to end.
 ^C
@@ -49,7 +49,7 @@ the CPU caches should be hotter.
 I'll now add a single-threaded CPU bound workload to this system, and bind
 it on one CPU:
 
-# bpftrace runqlat.bt
+# runqlat.bt
 Attaching 5 probes...
 Tracing CPU scheduler... Hit Ctrl-C to end.
 ^C
@@ -85,7 +85,7 @@ That didn't make much difference.
 Now I'll add a second single-threaded CPU workload, and bind it to the same
 CPU, causing contention:
 
-# bpftrace runqlat.bt
+# runqlat.bt
 Attaching 5 probes...
 Tracing CPU scheduler... Hit Ctrl-C to end.
 ^C
@@ -119,7 +119,7 @@ wait its turn on the one CPU.
 
 Now I'l run 10 CPU-bound throuds on one CPU:
 
-# bpftrace runqlat.bt
+# runqlat.bt
 Attaching 5 probes...
 Tracing CPU scheduler... Hit Ctrl-C to end.
 ^C

tools/runqlen.bt

+#!/usr/local/bin/bpftrace
 /*
  * runqlen.bt	CPU scheduler run queue length as a histogram.
  *		For Linux, uses bpftrace, eBPF.

tools/statsnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * statsnoop	Trace stat() syscalls.
  *		For Linux, uses bpftrace and eBPF.

tools/statsnoop_example.txt

@@ -4,7 +4,7 @@ Demonstrations of statsnoop, the Linux bpftrace/eBPF version.
 statsnoop traces different stat() syscalls system-wide, and prints details.
 Example output:
 
-# bpftrace statsnoop.bt
+# statsnoop.bt
 Attaching 9 probes...
 Tracing stat syscalls... Hit Ctrl-C to end.
 PID    COMM             ERR PATH

tools/syncsnoop.bt

+#!/usr/local/bin/bpftrace
 /*
  * syncsnoop	Trace sync() variety of syscalls.
  *		For Linux, uses bpftrace and eBPF.

tools/syncsnoop_example.txt

@@ -3,7 +3,7 @@ Demonstrations of syncsnoop, the Linux bpftrace/eBPF version.
 
 Tracing file system sync events:
 
-# bpftrace syncsnoop.bt
+# syncsnoop.bt
 Attaching 7 probes...
 Tracing sync syscalls... Hit Ctrl-C to end.
 TIME      PID    COMM             EVENT

tools/syscount.bt

+#!/usr/local/bin/bpftrace
 /*
  * syscount.bt	Count system callls.
  *		For Linux, uses bpftrace, eBPF.

tools/syscount_example.txt

@@ -4,7 +4,7 @@ Demonstrations of syscount, the Linux bpftrace/eBPF version.
 syscount counts system calls, and prints summaries of the top ten syscall IDs,
 and the top ten process names making syscalls. For example:
 
-# bpftrace syscount.bt
+# syscount.bt
 Attaching 3 probes...
 Counting syscalls... Hit Ctrl-C to end.
 ^C

tools/vfscount.bt

+#!/usr/local/bin/bpftrace
 /*
  * vfscount	Count VFS calls ("vfs_*").
  *		For Linux, uses bpftrace and eBPF.

tools/vfscount_example.txt

@@ -3,7 +3,7 @@ Demonstrations of vfscount, the Linux bpftrace/eBPF version.
 
 Tracing all VFS calls:
 
-# bpftrace vfscount.bt
+# vfscount.bt
 Attaching 54 probes...
 cannot attach kprobe, Invalid argument
 Warning: could not attach probe kprobe:vfs_dedupe_get_page.isra.21, skipping.

tools/vfsstat.bt

+#!/usr/local/bin/bpftrace
 /*
  * vfsstat	Count some VFS calls, with per-second summaries.
  *		For Linux, uses bpftrace and eBPF.

tools/vfsstat_example.txt

@@ -4,7 +4,7 @@ Demonstrations of vfsstat, the Linux bpftrace/eBPF version.
 This traces some common VFS calls (see the script for the list) and prints
 per-second summaries.
 
-# bpftrace vfsstat.bt
+# vfsstat.bt
 Attaching 8 probes...
 Tracing key VFS calls... Hit Ctrl-C to end.
 21:30:38

tools/writeback.bt

+#!/usr/local/bin/bpftrace
 /*
  * writeback	Trace file system writeback events with details.
  * 		For Linux, uses bpftrace and eBPF.

tools/writeback_example.txt

@@ -5,7 +5,7 @@ This tool traces when the kernel writeback procedure is writing dirtied pages
 to disk, and shows details such as the time, device numbers, reason for the
 write back, and the duration. For example:
 
-# bpftrace writeback.bt
+# writeback.bt
 Attaching 4 probes...
 Tracing writeback... Hit Ctrl-C to end.
 TIME      DEVICE   PAGES    REASON           ms

tools/xfsdist.bt

+#!/usr/local/bin/bpftrace
 /*
  * xfsdist	Summarize XFS operation latency.
  *		For Linux, uses bpftrace and eBPF.