Red Hat Training

A Red Hat training course is available for Red Hat Developer Toolset

Chapter 8. strace

strace is a diagnostic and debugging tool for the command line that can be used to trace system calls that are made and received by a running process. It records the name of each system call, its arguments, and its return value, as well as signals received by the process and other interactions with the kernel, and prints this record to standard error output or a selected file.

Red Hat Developer Toolset is distributed with strace 4.24.

8.1. Installing strace

In Red Hat Enterprise Linux, the strace utility is provided by the devtoolset-8-strace package and is automatically installed with devtoolset-8-toolchain as described in Section 1.5, “Installing Red Hat Developer Toolset”.

8.2. Using strace

To run the strace utility on a program you want to analyze:

$ scl enable devtoolset-8 'strace program argument...'

Replace program with the name of the program you want to analyze, and argument with any command line options and arguments you want to supply to this program. Alternatively, you can run the utility on an already running process by using the -p command line option followed by the process ID:

$ scl enable devtoolset-8 'strace -p process_id'

Note that you can execute any command using the scl utility, causing it to be run with the Red Hat Developer Toolset binaries used in preference to the Red Hat Enterprise Linux system equivalent. This allows you to run a shell session with Red Hat Developer Toolset strace as default:

$ scl enable devtoolset-8 'bash'
Note

To verify the version of strace you are using at any point:

$ which strace

Red Hat Developer Toolset’s strace executable path will begin with /opt. Alternatively, you can use the following command to confirm that the version number matches that for Red Hat Developer Toolset strace:

$ strace -V

8.2.1. Redirecting Output to a File

By default, strace prints the name of each system call, its arguments and the return value to standard error output. To redirect this output to a file, use the -o command line option followed by the file name:

$ scl enable devtoolset-8 'strace -o file_name program argument...'

Replace file_name with the name of the file.

Example 8.1. Redirecting Output to a File

Consider a slightly modified version of the fibonacci file from Example 7.1, “Compiling a C Program With Debugging Information”. This executable file displays the Fibonacci sequence and optionally allows you to specify how many members of this sequence to list. Run the strace utility on this file and redirect the trace output to fibonacci.log:

$ scl enable devtoolset-8 'strace -o fibonacci.log ./fibonacci 20'
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181 6765

This creates a new plain-text file called fibonacci.log in the current working directory.

8.2.2. Tracing Selected System Calls

To trace only a selected set of system calls, run the strace utility with the -e command line option:

$ scl enable devtoolset-8 'strace -e expression program argument...'

Replace expression with a comma-separated list of system calls to trace or any of the keywords listed in Table 8.1, “Commonly Used Values of the -e Option”. For a detailed description of all available values, see the strace(1) manual page.

Table 8.1. Commonly Used Values of the -e Option

ValueDescription

%file

System calls that accept a file name as an argument.

%process

System calls that are related to process management.

%network

System calls that are related to networking.

%signal

System calls that are related to signal management.

%ipc

System calls that are related to inter-process communication (IPC).

%desc

System calls that are related to file descriptors.

Note that the syntax -e expression is a shorthand for the full form -e trace=expression.

Example 8.2. Tracing Selected System Calls

Consider the employee file from Example 10.1, “Using memstomp”. Run the strace utility on this executable file and trace only the mmap and munmap system calls:

$ scl enable devtoolset-8 'strace -e mmap,munmap ./employee'
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f896c744000
mmap(NULL, 61239, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7f896c735000
mmap(0x3146a00000, 3745960, PROT_READ|PROT_EXEC, MAP_PRIVATE|MAP_DENYWRITE, 3, 0) = 0x3146a00000
mmap(0x3146d89000, 20480, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x189000) = 0x3146d89000
mmap(0x3146d8e000, 18600, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_ANONYMOUS, -1, 0) = 0x3146d8e000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f896c734000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f896c733000
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f896c732000
munmap(0x7f896c735000, 61239)           = 0
mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f896c743000
John,john@example.comDoe,
+++ exited with 0 +++

8.2.3. Displaying Time Stamps

To prefix each line of the trace with the exact time of the day in hours, minutes, and seconds, run the strace utility with the -t command line option:

$ scl enable devtoolset-8 'strace -t program argument...'

To also display milliseconds, supply the -t option twice:

$ scl enable devtoolset-8 'strace -tt program argument...'

To prefix each line of the trace with the time required to execute the respective system call, use the -r command line option:

$ scl enable devtoolset-8 'strace -r program argument...'

Example 8.3. Displaying Time Stamps

Consider an executable file named pwd. Run the strace utility on this file and include time stamps in the output:

$ scl enable devtoolset-8 'strace -tt pwd'
19:43:28.011815 execve("./pwd", ["./pwd"], [/* 36 vars */]) = 0
19:43:28.012128 brk(0)                  = 0xcd3000
19:43:28.012174 mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7fc869cb0000
19:43:28.012427 open("/etc/ld.so.cache", O_RDONLY) = 3
19:43:28.012446 fstat(3, {st_mode=S_IFREG|0644, st_size=61239, ...}) = 0
19:43:28.012464 mmap(NULL, 61239, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7fc869ca1000
19:43:28.012483 close(3)                = 0
...
19:43:28.013410 +++ exited with 0 +++

8.2.4. Displaying a Summary

To display a summary of how much time was required to execute each system call, how many times were these system calls executed, and how many errors were encountered during their execution, run the strace utility with the -c command line option:

$ scl enable devtoolset-8 'strace -c program argument...'

Example 8.4. Displaying a Summary

Consider an executable file named lsblk. Run the strace utility on this file and display a trace summary:

$ scl enable devtoolset-8 'strace -c lsblk > /dev/null'
% time     seconds  usecs/call     calls    errors syscall
------ ----------- ----------- --------- --------- ----------------
 80.88    0.000055           1       106        16 open
 19.12    0.000013           0       140           munmap
  0.00    0.000000           0       148           read
  0.00    0.000000           0         1           write
  0.00    0.000000           0       258           close
  0.00    0.000000           0        37         2 stat
...
------ ----------- ----------- --------- --------- ----------------
100.00    0.000068                  1790        35 total

8.2.5. Tampering with System Call Results

Simulating errors returned from system calls can help identify missing error handling in programs.

To make a program receive a generic error as the result of a particular system call, run the strace utility with the -e fault= option and supply the system call:

$ scl enable devtoolset-8 'strace -e fault=syscall program argument...'

To specify the error type or return value, use the -e inject= option:

$ scl enable devtoolset-8 'strace -e inject=syscall:error=error-type program argument'
$ scl enable devtoolset-8 'strace -e inject=syscall:retval=return-value program argument'

Note that specifying the error type and return value is mutually exclusive.

Example 8.5. Tampering with System Call Results

Consider an executable file named lsblk. Run the strace utility on this file and make the mmap() system call return an error:

$ scl enable devtoolset-8 'strace -e fault=mmap:error=EPERM lsblk > /dev/null'
execve("/usr/bin/lsblk", ["lsblk"], 0x7fff1c0e02a0 /* 54 vars */) = 0
brk(NULL)                               = 0x55d9e8b43000
mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = -1 EPERM (Operation not permitted) (INJECTED)
writev(2, [{iov_base="lsblk", iov_len=5}, {iov_base=": ", iov_len=2}, {iov_base="error while loading shared libra"..., iov_len=36}, {iov_base=": ", iov_len=2}, {iov_base="", iov_len=0}, {iov_base="", iov_len=0}, {iov_base="cannot create cache for search p"..., iov_len=35}, {iov_base=": ", iov_len=2}, {iov_base="Cannot allocate memory", iov_len=22}, {iov_base="\n", iov_len=1}], 10lsblk: error while loading shared libraries: cannot create cache for search path: Cannot allocate memory
) = 105
exit_group(127)                         = ?
+++ exited with 127 +++

8.3. Additional Resources

For more information about strace and its features, see the resources listed below.

Installed Documentation

  • strace(1) — The manual page for the strace utility provides detailed information about its usage. To display the manual page for the version included in Red Hat Developer Toolset:

    $ scl enable devtoolset-8 'man strace'

See Also