PICOTRACE(1)

NAME
picotrace - system call process tracer

SYNOPSIS
picotrace [-i] [-o OUTPUT] [-p | command [arg ...]]

DESCRIPTION
picotrace enables syscall trace logging for the specified processes. Trace data is logged to the file OUTPUT, otherwise if not specified to stdout. The operations that are traced include system call entry and exit, signal delivery, forking, vforking, LWP creation, LWP exiting and process exiting. Additionally picotrace logs arguments passed to a program, environment variables and ELF auxiliary vector values.

Once tracing is enabled on a process, trace data will be logged until either the process exits or the trace point is cleared. A traced process can generate large amounts of log data quickly.

The trace output is in plain text, human readable.

The options are as follows:

-i  Inherit; pass the trace flags to all future children of the designated processes.

-o OUTPUT
    Log trace records to outfile. Without this option picotrace will print its output to standard output.

-p PID
    Enable (disable) tracing on the indicated process id (only one -p flag is permitted).

command [args ...]
    Execute command with the specified trace flags.

The -p and command options are mutually exclusive.

OUTPUT FORMAT
The output is grouped into 5 columns:

pid Traced process id.

lwp Traced process LWP that caused an event. The 0 value is a special case for whole-process events.

exename
    Traced process program basename.

event
    Recorded event:

    ARGV
        Field in the argv[] vector.

    ENV Field in the env[] vector.

    AUXV
        Field in the auxv[] vector.

    SCE System call entry.

    SCX System call exit.

    CONTINUED
        The process has been continued with SIGCONT.

    SIGNALED
        The process has received non-stoppable signal.

    EXITED
        The process has exited.

    EXEC
        The process has replaced its process image with a new process image.

    FORKED
        The process has forked.

    VFORKED
        The process has vforked.

    VFORK_DONE
        The process has resumed after vfork(2).

    LWP_CREATED
        The process has created a thread.

    LWP_EXITED
        The process has exited a thread.

    CRASHED
        The process has crashed.

    STOPPED
        The process has stopped

additional information
    If available, extra pieces of information.

IMPLEMENTATION NOTES
The tracer uses the ptrace(2) system call to perform the tracing process.

The picotrace program has been designed to ship bare functionality only, without pretty printing of data structures and interpreting passed arguments to syscalls.

picotrace is designed to be a framework for other more advanced tracers and illustration of the canonical usage of the ptrace(2) system call. New features are not expected unless they present a new feature in the NetBSD kernel.

EXAMPLES
# trace the events of process id 34
    $ picotrace -p 34

# spawn and trace process sh(1) with all of its children and log the record to "trace.txt"
    $ picotrace -o trace.txt -i sh

SEE ALSO
ktruss(1), ptrace(2)

HISTORY
picotrace is inspired by truss from FreeBSD and strace from Linux.

Tn picotrace command was designed for NetBSD 9.

AUTHORS
Kamil Rytarowski <kamil@NetBSD.org>