Added examples

diff --git a/tools/memleak_examples.txt b/tools/memleak_examples.txt
new file mode 100644 (file)
index 0000000..35d235d
--- /dev/null
+++ b/tools/memleak_examples.txt
@@ -0,0 +1,105 @@
+Demonstrations of memleak.
+
+
+memleak traces and matches memory allocation and deallocation requests, and
+collects call stacks for each allocation. memleak can then print a summary
+of which call stacks performed allocations that weren't subsequently freed.
+For example:
+
+# ./memleak.py -p $(pidof allocs)
+Attaching to malloc and free in pid 5193, Ctrl+C to quit.
+*** Outstanding allocations:
+        80 bytes in 5 allocations from stack
+                 main+0x6d [/home/vagrant/allocs] (400862) 
+                 __libc_start_main+0xf0 [/usr/lib64/libc-2.21.so] (7fd460ac2790) 
+
+*** Outstanding allocations:
+        160 bytes in 10 allocations from stack
+                 main+0x6d [/home/vagrant/allocs] (400862) 
+                 __libc_start_main+0xf0 [/usr/lib64/libc-2.21.so] (7fd460ac2790) 
+
+
+When using the -p switch, memleak traces the allocations of a particular
+process. Without this switch, kernel allocations (kmalloc) are traced instead.
+For example:
+
+# ./memleak.py
+Attaching to kmalloc and kfree, Ctrl+C to quit.
+...
+        248 bytes in 4 allocations from stack
+                 bpf_prog_load [kernel] (ffffffff8118c471) 
+                 sys_bpf [kernel] (ffffffff8118c8b5) 
+
+        328 bytes in 1 allocations from stack
+                 perf_mmap [kernel] (ffffffff811990fd) 
+                 mmap_region [kernel] (ffffffff811df5d4) 
+                 do_mmap [kernel] (ffffffff811dfb83) 
+                 vm_mmap_pgoff [kernel] (ffffffff811c494f) 
+                 sys_mmap_pgoff [kernel] (ffffffff811ddf02) 
+                 sys_mmap [kernel] (ffffffff8101b0ab) 
+
+        464 bytes in 1 allocations from stack
+                 traceprobe_command [kernel] (ffffffff81187cf2) 
+                 traceprobe_probes_write [kernel] (ffffffff81187d86) 
+                 probes_write [kernel] (ffffffff81181580) 
+                 __vfs_write [kernel] (ffffffff812237b7) 
+                 vfs_write [kernel] (ffffffff81223ec6) 
+                 sys_write [kernel] (ffffffff81224b85) 
+                 entry_SYSCALL_64_fastpath [kernel] (ffffffff8178182e) 
+
+        8192 bytes in 1 allocations from stack
+                 alloc_and_copy_ftrace_hash.constprop.59 [kernel] (ffffffff8115d17e) 
+                 ftrace_set_hash [kernel] (ffffffff8115e767) 
+                 ftrace_set_filter_ip [kernel] (ffffffff8115e9a8) 
+                 arm_kprobe [kernel] (ffffffff81148600) 
+                 enable_kprobe [kernel] (ffffffff811486f6) 
+                 kprobe_register [kernel] (ffffffff81182399) 
+                 perf_trace_init [kernel] (ffffffff8117c4e0) 
+                 perf_tp_event_init [kernel] (ffffffff81192479) 
+
+
+memleak stores each allocated block along with its size, timestamp, and the
+stack that allocated it. When the block is deleted, this information is freed
+to reduce the memory overhead.
+
+To avoid false positives, allocations younger than a certain age (500ms by
+default) are not printed. To change this threshold, use the -o switch.
+
+By default, memleak prints its output every 5 seconds. To change this 
+interval, use the -i switch. 
+
+
+USAGE message:
+
+# ./memleak.py -h
+usage: memleak.py [-h] [-p PID] [-t] [-i INTERVAL] [-a] [-o OLDER]                                                                              
+                  [-c COMMAND]
+
+Trace outstanding memory allocations that weren't freed.
+Supports both user-mode allocations made with malloc/free and kernel-mode
+allocations made with kmalloc/kfree.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -p PID, --pid PID     the PID to trace; if not specified, trace kernel
+                        allocs
+  -t, --trace           print trace messages for each alloc/free call
+  -i INTERVAL, --interval INTERVAL
+                        interval in seconds to print outstanding allocations
+  -a, --show-allocs     show allocation addresses and sizes as well as call
+                        stacks
+  -o OLDER, --older OLDER
+                        prune allocations younger than this age in
+                        milliseconds
+  -c COMMAND, --command COMMAND
+                        execute and trace the specified command
+
+EXAMPLES:
+
+./memleak.py -p $(pidof allocs)
+        Trace allocations and display a summary of "leaked" (outstanding)
+        allocations every 5 seconds
+./memleak.py -p $(pidof allocs) -t
+        Trace allocations and display each individual call to malloc/free
+./memleak.py -p $(pidof allocs) -a -i 10                                                                                                                Trace allocations and display allocated addresses, sizes, and stacks                                                                            every 10 seconds for outstanding allocations                                                                                            ./memleak.py -c "./allocs"                                                                                                                              Run the specified command and trace its allocations                                                                                     ./memleak.py                                                                                                                                            Trace allocations in kernel mode and display a summary of outstanding                                                                           allocations every 5 seconds                                                                                                             ./memleak.py -o 60000                                                                                                                                   Trace allocations in kernel mode and display a summary of outstanding                                                                           allocations that are at least one minute (60 seconds) old  
+