Line
1	Contents
2	========
3	A.Gathering traces in Linux
4	B.Gathering simple test traces
5	C.Parsing traces
6
7
8
9	A.Gathering traces in Linux
10	===========================
11
12	Traces in Linux can be gathered using the strace utility (man strace). The
13	expected options to use with strace to gather traces that can be parsed by the
14	parser provided in this project is the following:
15
16	strace -v -f -s1024 -o output_filename command
17
18	Options:
19	-v print structure values unabbreviated (verbose).
20	-f follow and trace child processes
21	-s1024 allow string arguments in system calls up to 1024 characters. If this
22	option is skipped, strace will truncate strings exceeding 32 characters.
23
24
25	B.Gathering simple test traces
26	==============================
27	A C program is provided under the syscalls directory which can be used to
28	explicitly run certain system calls. This program can be used in combination
29	with strace to gather simple traces of specific system calls. Running the
30	syscall program.
31
32	make
33	./syscalls help           # prints usage information.
34	./syscalls list           # lists all system calls supported by this program.
35	./syscalls syscall_name   # executes the system call indicated by syscall_name.
36
37	Usually the indicated system call will be executed more than once, with
38	different options each time, in order to provide more information when traced.
39
40	Example using the syscalls program and the strace utility to generate a trace
41	file of a specific system call:
42
43	make
44	strace -v -f -s1024 -o open.strace ./syscalls open
45
46	In this example we use strace to trace the system calls involved when running
47	the command "./syscalls open". This will generate a file called "open.strace"
48	which will contain several traced system calls, one in each line. Towards the
49	end of this file there should be two lines similar to the following ones:
50
51	3579  open("syscalls.txt", O_RDONLY|O_CREAT, 0664) = 3
52	3579  open("syscalls2.txt", O_RDWR|O_CREAT|O_APPEND, 0664) = 4
53
54	These two lines are examples of the strace output format, when tracing the open
55	system call.
56
57	Similrly to tracing the "syscall" program, strace can be used to trace any
58	application. For example:
59
60	strace -v -f -s1024 -o cat.strace cat > test.txt
61	strace -v -f -s1024 -o firefox.strace firefox www.google.com
62
63
64	C.Parsing traces
65	================
66	Once a trace is gathered and stored in a trace file using a tracing utility such
67	as "strace", it can then be parsed. The POSIX Omni Tracer (POT) is provided,
68	able to parse trace files coming from different tracing utilities in different
69	operating systems, such as strace, truss and dtrace.
70	Using the POT parser:
71
72	export REPY_PATH="`pwd`"         # required to generate the lind file system
73	python parser.py <trace_file> [trace_type]
74
75	Arguments:
76	- trace_file is the file containing the output of the tracing utility, in this
77	case the strace output.
78	- trace_type is an optional second argument that indicates which tool was used
79	to generate the trace_file, for example strace. This argument is only needed if
80	the type of the trace_file cannot be automaitically inferred.