PICOTRACE(1)                General Commands Manual               PICOTRACE(1)

NAME
     picotrace - system call process tracer

SYNOPSIS
     picotrace [-i] [-o OUTPUT] [-p PID | <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
             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.

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

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 system call.  New
     features are not expected unless they present a new feature in the NetBSD
     kernel.

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>

NetBSD 8.99.38                    May 6, 2019                   NetBSD 8.99.38