NAME

ptt_view - PTT raw and textual decoder


SYNOPSIS

ptt_view [options] input_file


DESCRIPTION

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


OPTIONS

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.

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

-t
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.

-l
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

-m
don't display the pid

-d
display the pid (this is the default option)

-h
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.


LIMITATIONS

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


SEE ALSO

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


AUTHOR

Matthieu CASTET, Guillaume DURANCEAU