Add portseal

1 files changed, 57 insertions, 0 deletions

diff --git a/README b/README
index 74aab4a..4fbc636 100644
--- a/README
+++ b/README
@@ -4,6 +4,63 @@ portseal - tools to locate port management bugs
 This is a collection of tools to find bugs related to Mach port
 handling like port leaks at runtime.
 
+Requirements
+------------
+
+portseal is written in python and leverages coccinelle for the source
+transformation.  libportseal requires liburcu.
+
+How to use it
+-------------
+
+Use "portseal patch" within the source of your target code to patch
+it, "portseal unpatch" to undo the change.  "make check" demonstrates
+how to use portseal and pinniped to find both port leaks and wrong use
+of port management functions:
+
+% make check
+rm -rf -- test-obj
+cp -a test test-obj
+(cd test-obj && ../bin/portseal patch)
+[...]
+bin/pinniped test-obj/test
+dosth looked up 146
+test-obj/test: leaked send right 146
+test-obj/test[0x80489c3]
+test-obj/test[0x8048d05]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+dosthelse looked up 148
+test-obj/test: leaked send right 148
+test-obj/test[0x8048d9d]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+dosthglobal looked up 153
+test-obj/test: leaked send right 153
+test-obj/test[0x8048dc2]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+allocated receive port 154
+test-obj/test: leaked receive right 154
+test-obj/test[0x8048c36]
+test-obj/test[0x8048dcc]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+dolookupcwd looked up 108
+test-obj/test: mach_port_deallocate (1, 12345): (os/kern) invalid name
+test-obj/test[0x8048ce0]
+test-obj/test[0x8048dd6]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+test-obj/test: mach_port_destroy (1, 54321): (os/kern) invalid name
+test-obj/test[0x8048cf5]
+test-obj/test[0x8048dd6]
+/lib/i386-gnu/libc.so.0.3(__libc_start_main+0xbc)[0x10aa69c]
+test-obj/test[0x8048811]
+% addr2line -e test-obj/test 0x8048c36
+.../portseal/test-obj/test.c:65
+
+
 libpinniped
 -----------