- Current Status
- Compiling C Code
- Supported Platforms
PinkTrace is a ptrace() wrapper library.
PinkTrace is a lightweight C99 library that eases the writing of tracing applications. It consists of the following parts:
- Wrappers around different ptrace() requests.
- An API for decoding arguments (strings, socket addresses, …)
- An experimental API for encoding arguments.
- An initial implementation of a callback-driven higher-level library called pinktrace-easy.
PinkTrace is currently used by sydbox.
Pandora uses PinkTrace-Easy.
An extensive API reference is available.
Bindings are available for:
Note: Bindings for pinktrace-easy have not been written yet.
This package is made with the GNU autotools, you should run
./configure inside the distribution directory for configuring the source tree. Some notable options you may pass to
--enable-easyBuild pinktrace-easy (default)
--enable-ipv6Enable support for IPV6
--enable-doxygenBuild API documentation using Doxygen
--enable-haskellChecks for cabal and generates Setup.lhs
--enable-pythonBuild Python bindings
--enable-python-docBuild API documentation of Python using epydoc
--enable-rubyBuild Ruby bindings
--enable-ruby-docBuild API documentation of Ruby using rdoc
After that you should run
make for compilation and
make install (as root) for installation of PinkTrace. Optionally you may run
make check to run the unit tests.
As an exception, you should use Cabal to build Haskell bindings. After running
make to build PinkTrace use
cabal configure to configure Haskell bindings. Some notable flags you may pass to
cabal configure are:
-fexampleBuild example programs
-ftestBuild test programs
After that run
cabal build for compilation and
cabal install (as root) for installation of Haskell bindings. Optionally you may run
cabal test to run the unit tests.
The source of this web site is also included in the distribution. To view them offline you should generate them using Jekyll. After
./configure change directory to doc/ and run
make site. The web site will be built under the
_site directory. You may then run
make site-check and point your browser to http://localhost:4000 and view this web site offline.
Compiling C Code
You will need to specify various compiler flags when compiling C code. The usual way to do this is via pkg-config:
$ gcc -c $(pkg-config --cflags pinktrace) -o example.o example.c $ gcc $(pkg-config --libs pinktrace) -o example example.o
To use pinktrace-easy use pinktrace_easy, e.g.
pkg-config --cflags pinktrace_easy
If you are using autotools, consider using PKG_CHECK_MODULES rather than calling pkg-config by hand.
There are examples how to use the various parts of the library.
|about||about.c (raw)||about.hs (raw)||about.py (raw)||about.rb (raw)||How to use PinkTrace version macros|
|fork (FreeBSD)||fork-freebsd.c (raw)||fork-freebsd.hs (raw)||fork-freebsd.py (raw)||fork-freebsd.rb (raw)||How to do tracing fork on FreeBSD|
|fork (Linux)||fork-linux.c (raw)||fork-linux.hs (raw)||fork-linux.py (raw)||fork-linux.rb (raw)||How to do tracing fork on Linux|
|simple-strace (FreeBSD)||simple-strace-freebsd.c (raw)||simple-strace-freebsd.hs (TODO)||simple-strace-freebsd.py (raw)||simple-strace-freebsd.rb (raw)||A simple strace-like program for FreeBSD|
|simple-strace (Linux)||simple-strace-linux.c (raw)||simple-strace-linux.hs (TODO)||simple-strace-linux.py (raw)||simple-strace-linux.rb (raw)||A simple strace-like program for Linux|
Note: There are not any examples for pinktrace-easy at the moment.
Format patches are preferred. Either send a mail to me or poke me on IRC.
My personal e-mail address is firstname.lastname@example.org
I’m available on IRC as alip on Freenode and OFTC
FreeBSD and Linux operating systems are supported.
The supported architectures are:
Note: pinktrace-easy does not support FreeBSD at the moment, but support is planned.
Copyright © 2010, 2011 Ali Polatel <email@example.com>
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Tue Jun 28 2011:
Version 0.1.2 released:
- autotools: fix kernel version check for Linux-3.0
- New function pink_name_lookup_with_length()
Tue May 03 2011:
Version 0.1.1 released;
- Include pinktrace.cabal.in and Setup.lhs.in in the tarball
- Include examples in the tarball
Mon May 02 2011:
Version 0.1.0 released;
- Add initial implementation of a higher-level library on top with the name pinktrace-easy
- Simplify GCC macros
- Implement basic pink_event_decide() for FreeBSD
- New functions pink_trace_lwpinfo() and pink_trace_followfork() for FreeBSD
- Add new event PINK_EVENT_TRAP for genuine
- Merge Haskell bindings
Sat Oct 30 2010:
Version 0.0.5 released; changes include:
- Add new function
- Add new functions
- Add support for decoding Netlink socket addresses
- Various enhancements for the bindings
Sun Oct 17 2010:
Version 0.0.4 released; fixes socket decoding functions for PPC64.
Tue Oct 12 2010:
Sun Oct 3 2010:
Version 0.0.2 released; fixes compilation on ARM due to missing header
Sun Oct 3 2010:
Version 0.0.1 released