ptt_view - PTT raw and textual decoder


ptt_view [options] input_file


Its primary function is to decode the binary data collected by ptt_trace(1) in a raw or textual format.


Input options

-i file
input file name. The input file can also be the last command line option.

Output options

-o file
output file name. If it is `-' or not set, stdin will be used.

raw export. This format can easily be parsed by external tools like grep, awk, cut...

text export. This format is more human friendly by providing the meaning of the arguments.

-s {pid,pidx,tid}
split output by pid or tid.
pid: each pid has its own file. The file pattern is filename-pid.
pidx: each pid has its own file and the history of the parent process is copied (doesn't work well as threads are deleted after a fork...) after a fork. The file pattern is filename-pid.
tid: each (pid, tid) couple has its own file. The file pattern is filename-pid-tid.

Warning: fork is problematic...

-a alias_file
alias_file contains couples (address, name). In ptt_view(1) output, objects that have an address existing in alias_file will be replaced by the corresponding name. To create an alias file, include <alias.h> in the program source and use the following macros: alias_init, new_thread_alias and new_object_alias (for mutex, sem, cond_var, barrier).

For example, at runtime, the following program will create a file called alias with aliases for the 2 threads and the mutex:

    #include <alias.h>
    #include <stdio.h>
    #include <pthread.h>
    pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
    FILE *fd;
    void *func () {
        new_thread_alias (fd, "func");
        pthread_mutex_lock (&mutex);
        pthread_mutex_unlock (&mutex);
        return NULL;
    int main () {
        pthread_t thread;
        int ret;
        fd = alias_init ("alias");
        new_thread_alias (fd, "main");
        new_object_alias (fd, &mutex, "my_mutex");
        if (ret = pthread_create (&thread, NULL, func, NULL))
            printf("Thread creation failed: %d\n", ret);
        pthread_join (thread, NULL);
        return 0;

Filter options

-e pattern[,pattern...]
search for pattern* events.

It allows you to match the beginning of the event name and select a category of object. For example, you can select all the events related to mutexes with `-e MUTEX'.

The comma separator acts like an or, so you can filter multiple objects. For example, if you want mutex and cond-var, use `-e MUTEX,COND'.

You can repeat the option and the command line, but the result is a and, so only the names that are repeated will be displayed.

Use ptt_view -l to see the list of event.

-E pattern[,pattern...]
search for *pattern events

It allows you to match the end of the event name. Like -e, the comma separator acts like an or.

For example, to select input/output, you can use `-E _IN,_OUT'.

Use ptt-view -l to see the list of event.

list events that can be filtered by -e and -E options.

-p pid[,pid...]
search for pid. Select only events of the given pids.

The comma acts like an or.

Warning: some mutex, cond-var could be initialised in another process (not a selected pid) or some object could be shared between process. So you could see strange results.

-n name[,name...]
select the objects by their name (actually address)

The comma acts like an or.

Warning: sometimes you could get strange results. It selects only the name of the current object and its properties, but sometimes there are some consistency problems. For example, if you select a mutex name that is used by cond-var, you will see all the mutex operations, but not all the cond-var operations. This could be resolved by extending the function that gives a name to an object in order to manage more than one name, but it's not currently planned. A workaround is to selected all the object's names (here mutex + cond var).

There a similar problem after a fork for few events of the child. For example, we could wait for a cond wait, then fork. For the father there will be no problem, but the child won't have the cond wait out with a name.

-z start:end
event filter. This filter only displays end - start events skipping start events. The syntax -z :end or -z start: is also supported and imply start=0 or end=infinity.

Warning: the filter is applied to a group of events for performance issue, so the count is not always exact. You can have up to 3 more events than requested.

-Z start:end
time filter. This filter only displays events that occurred after start microseconds and before end microseconds. The syntax -Z :end or -Z start: is also supported and imply start=0 or end=infinity.

Display options

don't display the pid

display the pid (this is the default option)

display the help (all the ptt_view(1) commands)

Multiple file support

If you split your file with ptt_trace(1), hopefully you will be able to merge them. Just pass the first file you want to start with, and ptt_view(1) will decode the following files. If you don't want to decode up to the end, you can use -z and -Z options. You can use ptt_seq(1) in order to know the timestamp of the first element of a series of files.


Traces can be collected on a machine and visualize on an other provided that they have the same architecture size (32 or 64 bits).


ptt_trace(1), ptt_paje(1), ptt_stat(1), ptt_seq(1)


Matthieu CASTET, Guillaume DURANCEAU