OUTPUT.md

October 5, 2024 · View on GitHub

Output format

Basic concepts

Every event generated by this module has following format:

<upid>,<cpu>,<time>,<timen>!<data>

where:

upid - the unique identifier of the process that called the given syscall. A 64-bit signed integer, but for convenience it is always >= 0
cpu - logical cpu core number, [0, max_logical_cpu_cores)
time - linux CLOCK_MONOTONIC time in seconds at the time of printing this event
timen - nanoseconds part of the time given by <time> parameter
data - event data. Different for each event. The rest of this document describes what goes here

No padding or alignment is applied to any of these fields.

Most syscalls will have multiple trace lines printed per one call. Notice that, due to multiple logical processors, these lines may be interleaved when you read global trace pipe.

Trace events can be divided into two categories: syscall events and data events.

Syscall events.

Syscall events indicate start and/or end of a syscall. They have following format:

<syscall_tag>|<opt_arg1>=<opt_val1>,<opt_arg2>=<opt_val2>,...

opt_arg=opt_val parameters are optional and depend on given syscall. Their description is given later on in Syscall events definitions.

Data events.

Data events are used to supply additional data related to given syscall. Apart from execve() syscall they are used for printing strings, mostly filenames. Data events format:

<data_tag>|<string>

or:

<data_tag>[0]<string_part1>
<data_tag>[1]<string_part2>
...
<data_tag>_end

When the string is shorter than 900 characters, the first version (with '|') is used to print it. Otherwise, the string is divided into parts of at most 900 characters and these parts are printed using the second form. When all parts are printed, an end marker (<data_tag>_end) is printed to indicate the end of string. If the string contains '\n' character, this character is replaced with Cont event. After each group of one or more adjacent Cont events, Cont_end event is printed. For example, for data tag FN and string

this is
a string with
new lines

the following will be printed to trace:

FN|this is
Cont|a string with
Cont|new lines
Cont_end|

and for string (assumming both 1st and 2nd line has more than 900 chars)

this is aaaaaaaaaa...aaa very
long string with new lines aaaaaaaaaaaaa...aaaand
many characters

the output will be:

FN[0]this is aaaaaaaaaaa...
FN[1]aaa very
Cont|long string with new lines aaaaaaaaaaaaaa...
Cont_end|
FN[2]aaaaand
Cont|many characters
Cont_end
FN_end

Note: When string is divided into parts, it is guaranteed that each part has at most 900 characters, but there is no lower size limit for any of the parts (i.e. middle parts of the string may have less than 900 characters).

Syscall events definitions

If not specified otherwise, all string sizes exclude null-byte.

execve

Syntax:

New_proc|argsize=nn,prognameisize=nn,prognamepsize=nn,cwdsize=nn
<data_event:PI>
<data_event:PP>
<data_event:CW>
<data_event:A>
End_of_args|

e.g.:

New_proc|argsize=31,prognameisize=7,prognamepsize=7,cwdsize=35
PI|/bin/sh
PP|/bin/sh
CW|/drive/tracing/tools/execve_tracing
A[0]sh
A[1]/usr/bin/setup_etrace.sh
A[2]-r
End_of_args|

Arguments:

Argument	Description
argsize	the size in bytes of arguments list (including null-bytes)
prognameisize	the length of interpreter path (PI)
prognamepsize	the length of program name path (PP)
cwdsize	the length of current working directory path (CW)

Data events:

Tag	Description
PI	Absolute program interpreter path. Usually the same as program name path, but can differ in case of executable scripts.
PP	Absolute program name path
CW	Absolute current working directory path
A	Arguments list, see below

The format of "A" data event differs slightly from other data events. When in other cases subsequent numbers indicate parts of the same string, here they are used to denote succesive arguments and the same repeated number is used for parts of the same argument, for example:

./test AAAAAAA...AAAAA BBBBBBB...BBBB

will be shown as

...
A[0]./test
A[1]AAAAAAA...A
A[1]AAAA
A[2]BBBBBBB...B
A[2]BBB
End_of_args|

fork

Syntax:

SchedFork|pid=nn

e.g.:

SchedFork|pid=9183

Arguments:

Argument	Description
pid	the unique identifier of newly created child process, 64-bit signed integer, always >= 0

clone

Syntax:

SysClone|flags=nn
SchedFork|pid=nn

OR

SysClone|flags=nn
SysCloneFailed|

e.g.:

SysClone|flags=18874385
SchedFork|pid=9181

Arguments:

Argument	Description
flags	flags passed to clone() syscall
pid	the unique identifier of newly created child process, 64-bit signed integer, always >= 0

exit

Syntax:

Exit|status=nn

Arguments:

Argument	Description
status	status passed to exit()

open, openat

Syntax:

Open|fnamesize=nn,forigsize=nn,flags=nn,mode=nn,fd=nn
<data_event:FN>
<data_event:FO>

e.g.:

Open|fnamesize=34,forigsize=31,flags=524288,mode=0,fd=3
FN|/lib/x86_64-linux-gnu/libc-2.27.so
FO|/lib/x86_64-linux-gnu/libc.so.6

Arguments:

Argument	Description
fnamesize	the length of file path (FN)
forigsize	the length of original file path (FO)
flags	flags passed to open() syscall
mode	mode argument passed to open() syscall. This is always present, though it is valid only when flags have O_CREAT set, otherwise the value is undefined. See `man open(2)` for details.
fd	file descriptor returned by the syscall

Data events:

Tag Description

FN Absolute path to opened file

FO "Original" file path, as provided by user to the syscall. If user provided an absolute path, then it is printed verbatim. Otherwise, the user-provided path is prepended with the path to current working directory (in case of open() or openat(AT_FDCWD, ...)) or the path to the directory specified as the first argument to openat(). The final path is built by simply concatenating both these paths with a / between. In any case no path canonicalization or symlinks resolution is performed.

Tag	Description
FN	Absolute path to opened file
FO	"Original" file path, as provided by user to the syscall. If user provided an absolute path, then it is printed verbatim. Otherwise, the user-provided path is prepended with the path to current working directory (in case of `open()` or `openat(AT_FDCWD, ...)`) or the path to the directory specified as the first argument to `openat()`. The final path is built by simply concatenating both these paths with a `/` between. In any case no path canonicalization or symlinks resolution is performed.

pipe, pipe2

Syntax:

Pipe|fd1=nn,fd2=nn,flags=nn

e.g.:

Pipe|fd1=3,fd2=4,flags=0

Arguments:

Argument	Description
fd1	the first file descriptor returned by the syscall
fd2	the second file descriptor returned by the syscall
flags	if this was pipe2() syscall, this is the value of user-provided flags; otherwise it is 0 (see `man pipe(2)`)

rename, renameat

Syntax:

RenameFrom|fnamesize=nn
<data_event:RF>
RenameTo|fnamesize=nn
<data_event:RT>

OR (2):

RenameFrom|fnamesize=nn
<data_event:RF>
RenameFailed|

OR (3):

RenameFailed|

e.g.:

RenameFrom|fnamesize=16
RF|/tmp/soong.4.log
RenameTo|fnamesize=16
RT|/tmp/soong.5.log

Arguments:

Argument	Description
fnamesize (RenameFrom)	the length of the source file path (RF)
fnamesize (RenameTo)	the length of the destination file path (RT)

Data events:

Tag	Description
RF	Absolute path to source file
RT	Absolute path to destination file

Forms (2) and (3) are used when the syscall fails.

renameat2

Syntax:

Rename2From|fnamesize=nn,flags=nn
<data_event:RF>
RenameTo|fnamesize=nn
<data_event:RT>

OR (2):

Rename2From|fnamesize=nn,flags=nn
<data_event:RF>
RenameFailed|

OR (3):

RenameFailed|

e.g.:

Rename2From|fnamesize=16,flags=0
RF|/tmp/soong.4.log
RenameTo|fnamesize=16
RT|/tmp/soong.5.log

Arguments:

Argument	Description
fnamesize (Rename2From)	the length of the source file path (RF)
fnamesize (RenameTo)	the length of the destination file path (RT)
flags	user-provided flags passed to the syscall

Data events:

Tag	Description
RF	Absolute path to source file
RT	Absolute path to destination file

Forms (2) and (3) are used when the syscall fails.

link, linkat

Syntax:

LinkFrom|fnamesize=nn
<data_event:LF>
LinkTo|fnamesize=nn
<data_event:LT>

OR (2):

LinkatFrom|fnamesize=nn,flags=nn
<data_event:LF>
LinkTo|fnamesize=nn
<data_event:LT>

OR (3):

LinkFrom|fnamesize=nn
<data_event:LF>
LinkFailed|

OR (4):

LinkFailed|

OR (5):

LinkatFrom|fnamesize=nn,flags=nn
<data_event:LF>
LinkFailed|

e.g.:

LinkFrom|fnamesize=15
LF|/dev/shm/FRk1Ce
LinkTo|fnamesize=43
LT|/dev/shm/sem.mp3192055-12140030561392220055

Arguments:

Argument	Description
fnamesize (LinkFrom)	the length of the source file path (LF)
fnamesize (LinkTo)	the length of the destination file path (LT)
flags (LinkatFrom)	user-provided flags passed to the syscall

Data events:

Tag	Description
LF	Absolute path to source file
LT	Absolute path to destination file

Forms (3), (4) and (5) are used when the syscall fails.

symlink, symlinkat

Syntax:

Symlink|targetnamesize=nn,[resolvednamesize=nn,]linknamesize=nn
<data_event:ST>
[<data_event:SR>]
<data_event:SL>

e.g.:

Symlink|targetnamesize=19,linknamesize=30
ST|../.path_interposer
SL|/drive/android/out/.path/jinfo

Symlink|targetnamesize=21,resolvednamesize=1,linknamesize=15
ST|../../../../../../../
SR|/
SL|/bin/linktoroot

Arguments:

Argument	Description
targetnamesize	the length of the target string (ST)
resolvednamesize	the length of the resolved absolute path to the target (SR). Appears only, if the symlink is valid at the time of creation (links to an existing file/directory).
linknamesize	the length of the symlink file path (SL)

Data events:

Tag	Description
ST	Symlink's target string. It is not resolved as a path
SR	Absoulte path to symlink's target, if it exists at the time of symlink creation
SL	Absolute path to symlink

close

Syntax:

Close|fd=nn

e.g.:

Close|fd=3

Arguments:

Argument	Description
fd	File descriptor that was closed

dup, dup2, dup3, fcntl(..., F_DUPFD, ...), fnctl(..., F_DUPFD_CLOEXEC, ...)

Syntax:

Dup|oldfd=nn,newfd=nn,flags=nn

e.g.:

Dup|oldfd=2,newfd=5,flags=0

Arguments:

Argument	Description
oldfd	File descriptor to be copied
newfd	New file descriptor that is a copy of oldfd
flags	The flags passed to or inferred from the syscalls. It is O_CLOEXEC (0x80000) in case of dup3() and fnctl(..., F_DUPFD_CLOEXEC, ...) or 0 otherwise

mount

Syntax:

Mount|[sourcenamesize=nn,]targetnamesize=nn,[typenamesize=nn,]flags=nn
[MS|/home/example_dir/source_dir]
MT|/home/example_dir/target_dir
[MX|example_fstype]
[MountFailed|]

OR (1):
Mount|sourcenamesize=nn,targetnamesize=nn,typenamesize=nn,flags=nn
MS|/home/example_dir/source_dir
MT|/home/example_dir/target_dir
MX|example_fstype

OR (2):
Mount|sourcenamesize=nn,targetnamesize=nn,flags=nn
MS|/home/example_dir/source_dir
MT|/home/example_dir/target_dir
MountFailed|

OR (3):
Mount|targetnamesize=nn,flags=nn
MT|/home/example_dir/target_dir

Arguments:

Argument	Description
sourcenamesize	length of source string
targetnamesize	length of target path string
typenamesize	length of fs type string
flags	flags passed to syscall

Data events:

Tag	Description
MS	Source passed to mount syscall, it does not have to by path (as specified by manpages), if it is not passed, then flags should contain MS_REMOUNT
MT	Target mount path string
MX	Filesystem for which mount is performed, does not have to appear if NULL was passed to mount()

umount

Syntax:

Umount|targetnamesize=nn,flags=nn
MT|/mnt/

OR (1):
Umount|targetnamesize=nn,flags=nn
MT|/mnt/
UmountFailed|

OR (2):
UmountFailed|

Arguments:

Argument	Description
targetnamesize	length of target path string
flags	flags passed to umount2()

Data events:

Tag	Description
MT	Target umount path string

prctl(PR_SET_NAME, ...), write("/proc/[pid]/comm", ...)

Command change events will be printed only if tracer's trace_thread_names parameter is set to true.

Syntax:

Comm|size=nn
<data_event:CN>

e.g.:

Comm|size=8
CN|new_name

Arguments:

Argument	Description
size	the length of new command (CN)

Data events:

Tag	Description
CN	New command string

UPID/Env

Syntax

UPID|<upid1>
UPID|<upid2>
UPID|<upid3>
UPID|<upid4>
UPID|<upid5>
Env|foo=bar

This construct represents a set of upids which processes contain a certain environmental variable.