PinkTrace-0.1.2

About
Overview
Current Status
Documentation
Bindings
Building
Compiling C Code
Examples
Contribute
Supported Platforms
License
News

About

PinkTrace is a ptrace() wrapper library.

Overview

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.

Current Status

Version 0.1.2 has an unstable API and ABI.

Documentation

An extensive API reference is available.

Bindings

Bindings are available for:

Note: Bindings for pinktrace-easy have not been written yet.

Building

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 ./configure are:

--enable-easy Build pinktrace-easy (default)
--enable-ipv6 Enable support for IPV6
--enable-doxygen Build API documentation using Doxygen
--enable-haskell Checks for cabal and generates Setup.lhs
--enable-python Build Python bindings
--enable-python-doc Build API documentation of Python using epydoc
--enable-ruby Build Ruby bindings
--enable-ruby-doc Build 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:

-fexample Build example programs
-ftest Build 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.

Examples

There are examples how to use the various parts of the library.

Example	C	Haskell	Python	Ruby	Description
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.

Contribute

Clone git://github.com/alip/pinktrace.git.
Format patches are preferred. Either send a mail to me or poke me on IRC.
My personal e-mail address is alip@exherbo.org
I’m available on IRC as alip on Freenode and OFTC

Supported Platforms

FreeBSD and Linux operating systems are supported.
The supported architectures are:

x86
x86_64
ia64 (Linux only)
ppc (Linux only)
ppc64 (Linux only)
arm (Linux only)

Note: pinktrace-easy does not support FreeBSD at the moment, but support is planned.

License

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.

News

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 SIGTRAP
Merge Haskell bindings

Sat Oct 30 2010:

Version 0.0.5 released; changes include:

Add new function pink_util_set_arg()
Add new functions pink_trace_sysemu() and pink_trace_sysemu_singlestep()
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:

Version 0.0.3 released; fixes a few bugs and adds an API to decode NULL-terminated string arrays.

Sun Oct 3 2010:

Version 0.0.2 released; fixes compilation on ARM due to missing header