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:

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:

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:

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:

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

License

Copyright © 2010, 2011 Ali Polatel <alip@exherbo.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. 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.
  3. 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:

Tue May 03 2011:

Version 0.1.1 released;

Mon May 02 2011:

Version 0.1.0 released;

Sat Oct 30 2010:

Version 0.0.5 released; changes include:

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

Sun Oct 3 2010:

Version 0.0.1 released