├── system └── bin │ ├── rawlibst │ ├── libdw.so │ ├── libelf.so │ ├── libbz2.so │ ├── libbz2.so.1.0 │ ├── libdw.so.1 │ ├── libelf.so.1 │ ├── libzstd.so │ ├── libzstd.so.1 │ ├── libdw-0.182.so │ ├── libbz2.so.1.0.8 │ ├── libelf-0.182.so │ ├── libzstd.so.1.4.8 │ ├── libBlocksRuntime.so │ └── libandroid-support.so │ ├── rawst │ ├── strace │ └── strace-log-merge │ ├── strace │ └── strace-log-merge ├── .gitattributes ├── META-INF └── com │ └── google │ └── android │ ├── updater-script │ └── update-binary ├── common ├── system.prop ├── service.sh └── post-fs-data.sh ├── module.prop ├── README.md ├── custom └── man │ └── man1 │ ├── strace-log-merge.1 │ └── strace.1 └── install.sh /system/bin/rawlibst/libdw.so: -------------------------------------------------------------------------------- 1 | libdw.so.1 -------------------------------------------------------------------------------- /system/bin/rawlibst/libelf.so: -------------------------------------------------------------------------------- 1 | libelf.so.1 -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | *.* linguist-language=Shell 2 | -------------------------------------------------------------------------------- /system/bin/rawlibst/libbz2.so: -------------------------------------------------------------------------------- 1 | libbz2.so.1.0.8 -------------------------------------------------------------------------------- /system/bin/rawlibst/libbz2.so.1.0: -------------------------------------------------------------------------------- 1 | libbz2.so.1.0.8 -------------------------------------------------------------------------------- /system/bin/rawlibst/libdw.so.1: -------------------------------------------------------------------------------- 1 | libdw-0.182.so -------------------------------------------------------------------------------- /system/bin/rawlibst/libelf.so.1: -------------------------------------------------------------------------------- 1 | libelf-0.182.so -------------------------------------------------------------------------------- /system/bin/rawlibst/libzstd.so: -------------------------------------------------------------------------------- 1 | libzstd.so.1.4.8 -------------------------------------------------------------------------------- /system/bin/rawlibst/libzstd.so.1: -------------------------------------------------------------------------------- 1 | libzstd.so.1.4.8 -------------------------------------------------------------------------------- /META-INF/com/google/android/updater-script: -------------------------------------------------------------------------------- 1 | #MAGISK 2 | -------------------------------------------------------------------------------- /common/system.prop: -------------------------------------------------------------------------------- 1 | # This file will be read by resetprop 2 | # Example: Change dpi 3 | # ro.sf.lcd_density=320 4 | -------------------------------------------------------------------------------- /system/bin/rawst/strace: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawst/strace -------------------------------------------------------------------------------- /system/bin/rawlibst/libdw-0.182.so: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libdw-0.182.so -------------------------------------------------------------------------------- /system/bin/rawlibst/libbz2.so.1.0.8: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libbz2.so.1.0.8 -------------------------------------------------------------------------------- /system/bin/rawlibst/libelf-0.182.so: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libelf-0.182.so -------------------------------------------------------------------------------- /system/bin/rawlibst/libzstd.so.1.4.8: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libzstd.so.1.4.8 -------------------------------------------------------------------------------- /system/bin/rawlibst/libBlocksRuntime.so: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libBlocksRuntime.so -------------------------------------------------------------------------------- /system/bin/rawlibst/libandroid-support.so: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/henriknelson/strace-magisk-module/HEAD/system/bin/rawlibst/libandroid-support.so -------------------------------------------------------------------------------- /module.prop: -------------------------------------------------------------------------------- 1 | id=strace-nelshh 2 | nname=strace for Android 3 | version=v5.11 4 | versionCode=8 5 | author=nelshh 6 | description=A statically built version of the strace tool for android (aarch64) 7 | -------------------------------------------------------------------------------- /system/bin/strace: -------------------------------------------------------------------------------- 1 | #!/system/bin/sh 2 | 3 | bindir="$(dirname "$0")" 4 | execname="$(basename "$0")" 5 | 6 | libdir="/system/bin/rawlibst:$LD_LIBRARY_PATH" 7 | 8 | exec env LD_LIBRARY_PATH="$libdir" /system/bin/rawst/strace "$@" 9 | -------------------------------------------------------------------------------- /system/bin/strace-log-merge: -------------------------------------------------------------------------------- 1 | #!/system/bin/sh 2 | 3 | bindir="$(dirname "$0")" 4 | execname="$(basename "$0")" 5 | 6 | libdir="/system/bin/rawlibst:$LD_LIBRARY_PATH" 7 | 8 | exec env LD_LIBRARY_PATH="$libdir" /system/bin/rawst/strace-log-merge "$@" 9 | -------------------------------------------------------------------------------- /common/service.sh: -------------------------------------------------------------------------------- 1 | #!/system/bin/sh 2 | # Do NOT assume where your module will be located. 3 | # ALWAYS use $MODDIR if you need to know where this script 4 | # and module is placed. 5 | # This will make sure your module will still work 6 | # if Magisk change its mount point in the future 7 | MODDIR=${0%/*}; 8 | -------------------------------------------------------------------------------- /common/post-fs-data.sh: -------------------------------------------------------------------------------- 1 | #!/system/bin/sh 2 | # Do NOT assume where your module will be located. 3 | # ALWAYS use $MODDIR if you need to know where this script 4 | # and module is placed. 5 | # This will make sure your module will still work 6 | # if Magisk change its mount point in the future 7 | MODDIR=${0%/*} 8 | 9 | # This script will be executed in post-fs-data mode 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # strace for Android (aarch64) 2 | 3 | ## by nelshh @ xda-developers 4 | 5 | This Magisk module installs the latest stable version of the strace tool to the target system 6 | 7 | ## Change Log 8 | 9 | ### v1.2 - 2021-03-04 10 | * Updated strace to v5.11 11 | 12 | ### v1.1 - 2020-10-17 13 | * Updated strace to v5.9 14 | 15 | ### v1.0 - 2020-05-27 16 | * Initial release 17 | 18 | ## Source Code 19 | * Source [GitHub](https://github.com/strace/strace) 20 | 21 | ## Module Source Code 22 | * Module [GitHub](https://github.com/henriknelson/strace-magisk-module) 23 | 24 | ## Contact 25 | * Developer: [henrik@cliffords.nu](mailto:henrik@cliffords.nu) 26 | -------------------------------------------------------------------------------- /META-INF/com/google/android/update-binary: -------------------------------------------------------------------------------- 1 | #!/sbin/sh 2 | 3 | ################# 4 | # Initialization 5 | ################# 6 | 7 | umask 022 8 | 9 | # echo before loading util_functions 10 | ui_print() { echo "$1"; } 11 | 12 | require_new_magisk() { 13 | ui_print "*******************************" 14 | ui_print " Please install Magisk v20.4+! " 15 | ui_print "*******************************" 16 | exit 1 17 | } 18 | 19 | ######################### 20 | # Load util_functions.sh 21 | ######################### 22 | 23 | OUTFD=$2 24 | ZIPFILE=$3 25 | 26 | mount /data 2>/dev/null 27 | 28 | [ -f /data/adb/magisk/util_functions.sh ] || require_new_magisk 29 | . /data/adb/magisk/util_functions.sh 30 | [ $MAGISK_VER_CODE -lt 20400 ] && require_new_magisk 31 | 32 | install_module 33 | exit 0 34 | -------------------------------------------------------------------------------- /system/bin/rawst/strace-log-merge: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # 3 | # This script processes strace -ff -tt output. It merges the contents of all 4 | # STRACE_LOG.PID files and sorts them, printing result on the standard output. 5 | # 6 | # Copyright (c) 2012-2021 The strace developers. 7 | # 8 | # SPDX-License-Identifier: LGPL-2.1-or-later 9 | 10 | show_usage() 11 | { 12 | cat <<__EOF__ 13 | Usage: ${0##*/} STRACE_LOG 14 | 15 | Finds all STRACE_LOG.PID files, adds PID prefix to every line, 16 | then combines and sorts them, and prints result to standard output. 17 | 18 | It is assumed that STRACE_LOGs were produced by strace with -tt[t] 19 | option which prints timestamps (otherwise sorting won't do any good). 20 | __EOF__ 21 | } 22 | 23 | dd='\([0-9][0-9]\)' 24 | ds='\([0-9][0-9]*\)' 25 | 26 | if [ $# -ne 1 ]; then 27 | show_usage >&2 28 | exit 1 29 | elif [ "$1" = '--help' ]; then 30 | show_usage 31 | exit 0 32 | fi 33 | 34 | logfile=$1 35 | 36 | iterate_logfiles() 37 | { 38 | local file suffix 39 | 40 | for file in "$logfile".*; do 41 | [ -f "$file" ] || continue 42 | suffix=${file#"$logfile".} 43 | [ "$suffix" -gt 0 ] 2> /dev/null || 44 | continue 45 | "$@" "$suffix" "$file" 46 | done 47 | } 48 | 49 | max_suffix_length=0 50 | process_suffix() 51 | { 52 | local suffix len 53 | suffix="$1"; shift 54 | 55 | len=${#suffix} 56 | if [ $len -gt $max_suffix_length ]; then 57 | max_suffix_length=$len 58 | fi 59 | } 60 | 61 | process_logfile() 62 | { 63 | local suffix file pid 64 | suffix="$1"; shift 65 | file="$1"; shift 66 | 67 | pid=$(printf "%-*s" $max_suffix_length $suffix) 68 | # Some strace logs have last line which is not '\n' terminated, 69 | # so add extra newline to every file. 70 | # Empty lines are removed later. 71 | sed -n "s/^\($dd:\)\?\($dd:\)\?\($ds\.\)\?$ds /\2\4\6\7 $pid \0/p" < "$file" 72 | echo 73 | } 74 | 75 | iterate_logfiles process_suffix 76 | 77 | [ $max_suffix_length -gt 0 ] || { 78 | echo >&2 "${0##*/}: $logfile: strace output not found" 79 | exit 1 80 | } 81 | 82 | iterate_logfiles process_logfile | 83 | sort -s -n -k1,1 | 84 | sed -n 's/^[0-9][0-9]* //p' | 85 | grep -v '^$' 86 | 87 | rc=$? 88 | [ $rc -eq 1 ] && 89 | echo >&2 "${0##*/}: $logfile: strace output not found" 90 | exit $rc 91 | -------------------------------------------------------------------------------- /custom/man/man1/strace-log-merge.1: -------------------------------------------------------------------------------- 1 | .\" Copyright (c) 2017 The strace developers. 2 | .\" All rights reserved. 3 | .\" 4 | .\" SPDX-License-Identifier: LGPL-2.1-or-later 5 | .\" 6 | .\" Required option. 7 | .de OR 8 | . ie \\n(.$-1 \ 9 | . RI "\fB\\$1\fP" "\ \\$2" 10 | . el \ 11 | . BR "\\$1" 12 | .. 13 | .\" 14 | .TH STRACE-LOG-MERGE 1 "2021-02-07" "strace 5.11" 15 | .\" 16 | .SH NAME 17 | strace-log-merge \- merge strace \-ff \-tt output 18 | .\" 19 | .SH SYNOPSIS 20 | .SY strace\-log\-merge 21 | .IR STRACE_LOG 22 | .YS 23 | .SY strace\-log\-merge 24 | .OR \-\-help 25 | .YS 26 | .\" 27 | .SH DESCRIPTION 28 | .B strace\-log\-merge 29 | merges the output of 30 | .B strace \-ff \-tt[t] 31 | command, prepending PID to each line and sorting the result using time stamp as 32 | a key. 33 | .\" 34 | .SH OPTIONS 35 | .\" 36 | .TP 37 | .B \-\-help 38 | Show program usage and exit. 39 | .TP 40 | .I STRACE_LOG 41 | Output file name prefix of files produced by a 42 | .B strace -ff -tt[t] 43 | command. 44 | .SH EXIT STATUS 45 | .TP 46 | .B 0 47 | Success 48 | .TP 49 | .B Non-zero 50 | Error occurred: either no argument specified (in that case a usage is printed), 51 | or something went wrong during the processing of 52 | .IR STRACE_LOG ".*" 53 | files. 54 | .\" 55 | .SH USAGE EXAMPLE 56 | .sp 57 | .nf 58 | .ft CW 59 | $ strace -o sleepy -ff -tt -e trace=execve,nanosleep \\ 60 | sh -c 'sleep 0.1 & sleep 0.2 & sleep 0.3' 61 | $ strace-log-merge sleepy | fold -w 72 -s 62 | 13475 21:13:52.040837 execve("/bin/sh", ["sh", "-c", "sleep 0.1 & sleep 63 | 0.2 & sleep 0."...], 0x7ffde54b2450 /* 33 vars */) = 0 64 | 13478 21:13:52.044050 execve("/bin/sleep", ["sleep", "0.3"], 65 | 0x5631be4f87a8 /* 33 vars */) = 0 66 | 13476 21:13:52.044269 execve("/bin/sleep", ["sleep", "0.1"], 67 | 0x5631be4f87a8 /* 33 vars */) = 0 68 | 13477 21:13:52.044389 execve("/bin/sleep", ["sleep", "0.2"], 69 | 0x5631be4f87a8 /* 33 vars */) = 0 70 | 13478 21:13:52.046207 nanosleep({tv_sec=0, tv_nsec=300000000}, NULL) = 0 71 | 13476 21:13:52.046303 nanosleep({tv_sec=0, tv_nsec=100000000}, NULL) = 0 72 | 13477 21:13:52.046318 nanosleep({tv_sec=0, tv_nsec=200000000}, NULL) = 0 73 | 13476 21:13:52.146852 +++ exited with 0 +++ 74 | 13475 21:13:52.146942 --- SIGCHLD {si_signo=SIGCHLD, 75 | si_code=CLD_EXITED, si_pid=13476, si_uid=1000, si_status=0, si_utime=0, 76 | si_stime=0} --- 77 | 13477 21:13:52.247782 +++ exited with 0 +++ 78 | 13475 21:13:52.247885 --- SIGCHLD {si_signo=SIGCHLD, 79 | si_code=CLD_EXITED, si_pid=13477, si_uid=1000, si_status=0, si_utime=0, 80 | si_stime=0} --- 81 | 13478 21:13:52.347680 +++ exited with 0 +++ 82 | 13475 21:13:52.347786 --- SIGCHLD {si_signo=SIGCHLD, 83 | si_code=CLD_EXITED, si_pid=13478, si_uid=1000, si_status=0, si_utime=0, 84 | si_stime=0} --- 85 | 13475 21:13:52.348069 +++ exited with 0 +++ 86 | .ft R 87 | .fi 88 | .sp 89 | .\" 90 | .SH NOTES 91 | .I strace-log-merge 92 | does not work well with 93 | .B strace 94 | logs generated by 95 | .B strace -tt 96 | invocation that pass midnight, as those lack the information required 97 | for the proper sorting. 98 | Employing the 99 | .B -ttt 100 | option in the respective 101 | .B strace 102 | invocation should solve the problem. 103 | .\" 104 | .SH BUGS 105 | .I strace-log-merge 106 | does not perform any checks whether the files specified are in the correct 107 | format and implies that only files from a single 108 | .I strace 109 | session match 110 | .IR STRACE_LOG ".*" 111 | glob pattern. 112 | .\" 113 | .SH HISTORY 114 | The initial version of 115 | .I strace-log-merge 116 | was written by Denys Vlasenko in 2012. 117 | .\" 118 | .SH REPORTING BUGS 119 | Problems with 120 | .B strace-log-merge 121 | should be reported to the 122 | .B strace 123 | mailing list at . 124 | .\" 125 | .SH "SEE ALSO" 126 | .BR strace (1) 127 | -------------------------------------------------------------------------------- /install.sh: -------------------------------------------------------------------------------- 1 | ########################################################################################## 2 | # 3 | # Magisk Module Installer Script 4 | # 5 | ########################################################################################## 6 | ########################################################################################## 7 | # 8 | # Instructions: 9 | # 10 | # 1. Place your files into system folder (delete the placeholder file) 11 | # 2. Fill in your module's info into module.prop 12 | # 3. Configure and implement callbacks in this file 13 | # 4. If you need boot scripts, add them into common/post-fs-data.sh or common/service.sh 14 | # 5. Add your additional or modified system properties into common/system.prop 15 | # 16 | ########################################################################################## 17 | 18 | ########################################################################################## 19 | # Config Flags 20 | ########################################################################################## 21 | 22 | # Set to true if you do *NOT* want Magisk to mount 23 | # any files for you. Most modules would NOT want 24 | # to set this flag to true 25 | SKIPMOUNT=false 26 | 27 | # Set to true if you need to load system.prop 28 | PROPFILE=false 29 | 30 | # Set to true if you need post-fs-data script 31 | POSTFSDATA=false 32 | 33 | # Set to true if you need late_start service script 34 | LATESTARTSERVICE=false 35 | 36 | ########################################################################################## 37 | # Replace list 38 | ########################################################################################## 39 | 40 | # List all directories you want to directly replace in the system 41 | # Check the documentations for more info why you would need this 42 | 43 | # Construct your list in the following format 44 | # This is an example 45 | REPLACE_EXAMPLE=" 46 | /system/app/Youtube 47 | /system/priv-app/SystemUI 48 | /system/priv-app/Settings 49 | /system/framework 50 | " 51 | 52 | # Construct your own list here 53 | REPLACE=" 54 | " 55 | 56 | ########################################################################################## 57 | # 58 | # Function Callbacks 59 | # 60 | # The following functions will be called by the installation framework. 61 | # You do not have the ability to modify update-binary, the only way you can customize 62 | # installation is through implementing these functions. 63 | # 64 | # When running your callbacks, the installation framework will make sure the Magisk 65 | # internal busybox path is *PREPENDED* to PATH, so all common commands shall exist. 66 | # Also, it will make sure /data, /system, and /vendor is properly mounted. 67 | # 68 | ########################################################################################## 69 | ########################################################################################## 70 | # 71 | # The installation framework will export some variables and functions. 72 | # You should use these variables and functions for installation. 73 | # 74 | # ! DO NOT use any Magisk internal paths as those are NOT public API. 75 | # ! DO NOT use other functions in util_functions.sh as they are NOT public API. 76 | # ! Non public APIs are not guranteed to maintain compatibility between releases. 77 | # 78 | # Available variables: 79 | # 80 | # MAGISK_VER (string): the version string of current installed Magisk 81 | # MAGISK_VER_CODE (int): the version code of current installed Magisk 82 | # BOOTMODE (bool): true if the module is currently installing in Magisk Manager 83 | # MODPATH (path): the path where your module files should be installed 84 | # TMPDIR (path): a place where you can temporarily store files 85 | # ZIPFILE (path): your module's installation zip 86 | # ARCH (string): the architecture of the device. Value is either arm, arm64, x86, or x64 87 | # IS64BIT (bool): true if $ARCH is either arm64 or x64 88 | # API (int): the API level (Android version) of the device 89 | # 90 | # Availible functions: 91 | # 92 | # ui_print 93 | # print to console 94 | # Avoid using 'echo' as it will not display in custom recovery's console 95 | # 96 | # abort 97 | # print error message to console and terminate installation 98 | # Avoid using 'exit' as it will skip the termination cleanup steps 99 | # 100 | # set_perm [context] 101 | # if [context] is empty, it will default to "u:object_r:system_file:s0" 102 | # this function is a shorthand for the following commands 103 | # chown owner.group target 104 | # chmod permission target 105 | # chcon context target 106 | # 107 | # set_perm_recursive [context] 108 | # if [context] is empty, it will default to "u:object_r:system_file:s0" 109 | # for all files in , it will call: 110 | # set_perm file owner group filepermission context 111 | # for all directories in (including itself), it will call: 112 | # set_perm dir owner group dirpermission context 113 | # 114 | ########################################################################################## 115 | ########################################################################################## 116 | # If you need boot scripts, DO NOT use general boot scripts (post-fs-data.d/service.d) 117 | # ONLY use module scripts as it respects the module status (remove/disable) and is 118 | # guaranteed to maintain the same behavior in future Magisk releases. 119 | # Enable boot scripts by setting the flags in the config section above. 120 | ########################################################################################## 121 | 122 | # Set what you want to display when installing your module 123 | 124 | print_modname() { 125 | ui_print "*********************************************" 126 | ui_print " strace for Android " 127 | ui_print " - v 5.11 " 128 | ui_print " - built by nelshh @ xda-developers " 129 | ui_print "*********************************************" 130 | } 131 | 132 | # Copy/extract your module files into $MODPATH in on_install. 133 | on_install() { 134 | ui_print "[1/7] Extracting files.."; 135 | unzip -o "$ZIPFILE" '*' -d $MODPATH >&2; 136 | ui_print "[2/7] Setting permissions.."; 137 | } 138 | 139 | set_permissions() { 140 | # The following is the default rule, DO NOT remove 141 | set_perm_recursive $MODPATH 0 0 0755 0644; 142 | 143 | ui_print "[3/7] Installing to /system/bin.."; 144 | chown -R 0:0 $MODPATH/system/bin; 145 | chmod -R 755 $MODPATH/system/bin; 146 | find $MODPATH/system/bin -type d -exec chmod 755 {} +; 147 | find $MODPATH/system/bin -type f -exec chmod 755 {} +; 148 | find $MODPATH/system/bin -type l -exec chmod 755 {} +; 149 | 150 | ui_print "[4/7] Installing to /system/bin/rawst.."; 151 | chown -R 0:0 $MODPATH/system/bin/rawst; 152 | chmod -R 755 $MODPATH/system/bin/rawst; 153 | find $MODPATH/system/bin/rawst -type f -exec chmod 755 {} +; 154 | find $MODPATH/system/bin/rawst -type l -exec chmod 755 {} +; 155 | 156 | ui_print "[5/7] Installing to /system/bin/rawlibst.."; 157 | chown -R 0:0 $MODPATH/system/bin/rawlibst; 158 | chmod -R 755 $MODPATH/system/bin/rawlibst; 159 | olddir=$(pwd); 160 | cd $MODPATH/system/bin/rawlibst; 161 | 162 | ln -s libzstd.so.1.4.8 libzstd.so.1 163 | ln -s libzstd.so.1.4.8 libzstd.so 164 | 165 | ln -s libelf-0.182.so libelf.so.1 166 | ln -s libelf.so.1 libelf.so 167 | 168 | ln -s libdw-0.182.so libdw.so.1 169 | ln -s libdw.so.1 libdw.so 170 | 171 | ln -s libbz2.so.1.0.8 libbz2.so.1.0 172 | ln -s libbz2.so.1.0.8 libbz2.so 173 | 174 | cd "$oldddir"; 175 | find $MODPATH/system/bin/rawlibst -type d -exec chmod 755 {} \+; 176 | find $MODPATH/system/bin/rawlibst -type f -exec chmod 755 {} \+; 177 | find $MODPATH/system/bin/rawlibst -type l -exec chmod 755 {} \+; 178 | 179 | ui_print "[6/7] Installing to /data/man.."; 180 | mkdir -p /data/man; 181 | cp -r $MODPATH/custom/man/* /data/man/; 182 | chmod -R 664 /data/man; 183 | chown -R 0:0 /data/man; 184 | find /data/man -type d -exec chmod 755 {} \+; 185 | find /data/man -type f -exec chmod 664 {} \+; 186 | if [[ -s "/system/bin/mandoc" ]]; then 187 | makewhatis /data/man; 188 | fi 189 | 190 | ui_print "[7/7] Installation finished"; 191 | } 192 | -------------------------------------------------------------------------------- /custom/man/man1/strace.1: -------------------------------------------------------------------------------- 1 | .\" Copyright (c) 1991, 1992 Paul Kranenburg 2 | .\" Copyright (c) 1993 Branko Lankester 3 | .\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey 4 | .\" Copyright (c) 1996-2021 The strace developers. 5 | .\" All rights reserved. 6 | .\" 7 | .\" SPDX-License-Identifier: LGPL-2.1-or-later 8 | .de CW 9 | .sp 10 | .in +4n 11 | .nf 12 | .ft CW 13 | .. 14 | .de CE 15 | .ft R 16 | .fi 17 | .in 18 | .sp 19 | .. 20 | .\" Like .OP, but with ellipsis at the end in order to signify that option 21 | .\" can be provided multiple times. Based on .OP definition in groff's 22 | .\" an-ext.tmac. 23 | .de OM 24 | . ie \\n(.$-1 \ 25 | . RI "[\fB\\$1\fP" "\ \\$2" "]...\&" 26 | . el \ 27 | . RB "[" "\\$1" "]...\&" 28 | .. 29 | .\" Required option. 30 | .de OR 31 | . ie \\n(.$-1 \ 32 | . RI "\fB\\$1\fP" "\ \\$2" 33 | . el \ 34 | . BR "\\$1" 35 | .. 36 | .TH STRACE 1 "2021-02-07" "strace 5.11" 37 | .SH NAME 38 | strace \- trace system calls and signals 39 | .SH SYNOPSIS 40 | .SY strace 41 | .if ''#' .OP \-ACdffhikqqrtttTvVwxxyyzZ 42 | .if '#'#' .OP \-ACdffhiqqrtttTvVwxxyyzZ 43 | .OP \-I n 44 | .OP \-b execve 45 | .OM \-e expr 46 | .OP \-O overhead 47 | .OP \-S sortby 48 | .OP \-U columns 49 | .OP \-a column 50 | .OP \-o file 51 | .OP \-s strsize 52 | .OP \-X format 53 | .OM \-P path 54 | .OM \-p pid 55 | .OP \-\-seccomp\-bpf 56 | .BR "" { 57 | .OR \-p pid 58 | .BR "" | 59 | .OP \-DDD 60 | .OM \-E var\fR[=\fIval\fR] 61 | .OP \-u username 62 | .IR command " [" args ] 63 | .BR "" } 64 | .YS 65 | .SY strace 66 | .B \-c 67 | .OP \-dfwzZ 68 | .OP \-I n 69 | .OP \-b execve 70 | .OM \-e expr 71 | .OP \-O overhead 72 | .OP \-S sortby 73 | .OP \-U columns 74 | .OM \-P path 75 | .OM \-p pid 76 | .OP \-\-seccomp\-bpf 77 | .BR "" { 78 | .OR \-p pid 79 | .BR "" | 80 | .OP \-DDD 81 | .OM \-E var\fR[=\fIval\fR] 82 | .OP -u username 83 | .IR command " [" args ] 84 | .BR "" } 85 | .YS 86 | .SH DESCRIPTION 87 | .IX "strace command" "" "\fLstrace\fR command" 88 | .LP 89 | In the simplest case 90 | .B strace 91 | runs the specified 92 | .I command 93 | until it exits. 94 | It intercepts and records the system calls which are called 95 | by a process and the signals which are received by a process. 96 | The name of each system call, its arguments and its return value 97 | are printed on standard error or to the file specified with the 98 | .B \-o 99 | option. 100 | .LP 101 | .B strace 102 | is a useful diagnostic, instructional, and debugging tool. 103 | System administrators, diagnosticians and trouble-shooters will find 104 | it invaluable for solving problems with 105 | programs for which the source is not readily available since 106 | they do not need to be recompiled in order to trace them. 107 | Students, hackers and the overly-curious will find that 108 | a great deal can be learned about a system and its system calls by 109 | tracing even ordinary programs. And programmers will find that 110 | since system calls and signals are events that happen at the user/kernel 111 | interface, a close examination of this boundary is very 112 | useful for bug isolation, sanity checking and 113 | attempting to capture race conditions. 114 | .LP 115 | Each line in the trace contains the system call name, followed 116 | by its arguments in parentheses and its return value. 117 | An example from stracing the command "cat /dev/null" is: 118 | .CW 119 | open("/dev/null", O_RDONLY) = 3 120 | .CE 121 | Errors (typically a return value of \-1) have the errno symbol 122 | and error string appended. 123 | .CW 124 | open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory) 125 | .CE 126 | Signals are printed as signal symbol and decoded siginfo structure. 127 | An excerpt from stracing and interrupting the command "sleep 666" is: 128 | .CW 129 | sigsuspend([] 130 | --- SIGINT {si_signo=SIGINT, si_code=SI_USER, si_pid=...} --- 131 | +++ killed by SIGINT +++ 132 | .CE 133 | If a system call is being executed and meanwhile another one is being called 134 | from a different thread/process then 135 | .B strace 136 | will try to preserve the order of those events and mark the ongoing call as 137 | being 138 | .IR unfinished . 139 | When the call returns it will be marked as 140 | .IR resumed . 141 | .CW 142 | [pid 28772] select(4, [3], NULL, NULL, NULL 143 | [pid 28779] clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0 144 | [pid 28772] <... select resumed> ) = 1 (in [3]) 145 | .CE 146 | Interruption of a (restartable) system call by a signal delivery is processed 147 | differently as kernel terminates the system call and also arranges its 148 | immediate reexecution after the signal handler completes. 149 | .CW 150 | read(0, 0x7ffff72cf5cf, 1) = ? ERESTARTSYS (To be restarted) 151 | --- SIGALRM ... --- 152 | rt_sigreturn(0xe) = 0 153 | read(0, "", 1) = 0 154 | .CE 155 | Arguments are printed in symbolic form with passion. 156 | This example shows the shell performing ">>xyzzy" output redirection: 157 | .CW 158 | open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3 159 | .CE 160 | Here, the second and the third argument of 161 | .BR open (2) 162 | are decoded by breaking down the 163 | flag argument into its three bitwise-OR constituents and printing the 164 | mode value in octal by tradition. Where the traditional or native 165 | usage differs from ANSI or POSIX, the latter forms are preferred. 166 | In some cases, 167 | .B strace 168 | output is proven to be more readable than the source. 169 | .LP 170 | Structure pointers are dereferenced and the members are displayed 171 | as appropriate. In most cases, arguments are formatted in the most C-like 172 | fashion possible. 173 | For example, the essence of the command "ls \-l /dev/null" is captured as: 174 | .CW 175 | lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(0x1, 0x3), ...}) = 0 176 | .CE 177 | Notice how the 'struct stat' argument is dereferenced and how each member is 178 | displayed symbolically. In particular, observe how the 179 | .B st_mode 180 | member is carefully decoded into a bitwise-OR of symbolic and numeric values. 181 | Also notice in this example that the first argument to 182 | .BR lstat (2) 183 | is an input to the system call and the second argument is an output. 184 | Since output arguments are not modified if the system call fails, arguments may 185 | not always be dereferenced. For example, retrying the "ls \-l" example 186 | with a non-existent file produces the following line: 187 | .CW 188 | lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory) 189 | .CE 190 | In this case the porch light is on but nobody is home. 191 | .LP 192 | Syscalls unknown to 193 | .B strace 194 | are printed raw, with the unknown system call number printed in hexadecimal form 195 | and prefixed with "syscall_": 196 | .CW 197 | syscall_0xbad(0x1, 0x2, 0x3, 0x4, 0x5, 0x6) = -1 ENOSYS (Function not implemented) 198 | .CE 199 | .LP 200 | Character pointers are dereferenced and printed as C strings. 201 | Non-printing characters in strings are normally represented by 202 | ordinary C escape codes. 203 | Only the first 204 | .I strsize 205 | (32 by default) bytes of strings are printed; 206 | longer strings have an ellipsis appended following the closing quote. 207 | Here is a line from "ls \-l" where the 208 | .BR getpwuid (3) 209 | library routine is reading the password file: 210 | .CW 211 | read(3, "root::0:0:System Administrator:/"..., 1024) = 422 212 | .CE 213 | While structures are annotated using curly braces, simple pointers 214 | and arrays are printed using square brackets with commas separating 215 | elements. Here is an example from the command 216 | .BR id (1) 217 | on a system with supplementary group ids: 218 | .CW 219 | getgroups(32, [100, 0]) = 2 220 | .CE 221 | On the other hand, bit-sets are also shown using square brackets, 222 | but set elements are separated only by a space. 223 | Here is the shell, preparing to execute an external command: 224 | .CW 225 | sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0 226 | .CE 227 | Here, the second argument is a bit-set of two signals, 228 | .BR SIGCHLD " and " SIGTTOU . 229 | In some cases, the bit-set is so full that printing out the unset 230 | elements is more valuable. In that case, the bit-set is prefixed by 231 | a tilde like this: 232 | .CW 233 | sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0 234 | .CE 235 | Here, the second argument represents the full set of all signals. 236 | .SH OPTIONS 237 | .SS General 238 | .TP 12 239 | .BI "\-e " expr 240 | A qualifying expression which modifies which events to trace 241 | or how to trace them. The format of the expression is: 242 | .RS 15 243 | .IP 244 | [\,\fIqualifier\/\fB=\fR][\fB!\fR]\,\fIvalue\/\fR[\fB,\fR\,\fIvalue\/\fR]... 245 | .RE 246 | .IP 247 | where 248 | .I qualifier 249 | is one of 250 | .BR trace " (or " t ), 251 | .BR abbrev " (or " a ), 252 | .BR verbose " (or " v ), 253 | .BR raw " (or " x ), 254 | .BR signal " (or " signals " or " s ), 255 | .BR read " (or " reads " or " r ), 256 | .BR write " (or " writes " or " w ), 257 | .BR fault , 258 | .BR inject , 259 | .BR status , 260 | .BR quiet " (or " silent " or " silence " or " q ), 261 | .BR decode\-fds " (or " decode\-fd ), 262 | or 263 | .BR kvm , 264 | and 265 | .I value 266 | is a qualifier-dependent symbol or number. The default 267 | qualifier is 268 | .BR trace . 269 | Using an exclamation mark negates the set of values. For example, 270 | .BR \-e "\ " open 271 | means literally 272 | .BR \-e "\ " trace = open 273 | which in turn means trace only the 274 | .B open 275 | system call. By contrast, 276 | .BR \-e "\ " trace "=!" open 277 | means to trace every system call except 278 | .BR open . 279 | In addition, the special values 280 | .B all 281 | and 282 | .B none 283 | have the obvious meanings. 284 | .IP 285 | Note that some shells use the exclamation point for history 286 | expansion even inside quoted arguments. If so, you must escape 287 | the exclamation point with a backslash. 288 | .SS Startup 289 | .TP 12 290 | \fB\-E\ \fIvar\fR=\,\fIval\fR 291 | .TQ 292 | .BR "\-\-env" = \fIvar\fR = \fIval\fR 293 | Run command with 294 | .IR var = val 295 | in its list of environment variables. 296 | .TP 297 | .BI "\-E " var 298 | .TQ 299 | .BR "\-\-env" = \fIvar\fR 300 | Remove 301 | .IR var 302 | from the inherited list of environment variables before passing it on to 303 | the command. 304 | .TP 305 | .BI "\-p " pid 306 | .TQ 307 | .BR "\-\-attach" = \fIpid\fR 308 | Attach to the process with the process 309 | .SM ID 310 | .I pid 311 | and begin tracing. 312 | The trace may be terminated 313 | at any time by a keyboard interrupt signal 314 | .RB ( CTRL\-C ). 315 | .B strace 316 | will respond by detaching itself from the traced process(es) 317 | leaving it (them) to continue running. 318 | Multiple 319 | .B \-p 320 | options can be used to attach to many processes in addition to 321 | .I command 322 | (which is optional if at least one 323 | .B \-p 324 | option is given). 325 | .B \-p 326 | "`pidof PROG`" syntax is supported. 327 | .TP 328 | .BI "\-u " username 329 | .TQ 330 | .BR "\-\-user" = \fIusername\fR 331 | Run command with the user \s-1ID\s0, group \s-2ID\s0, and 332 | supplementary groups of 333 | .IR username . 334 | This option is only useful when running as root and enables the 335 | correct execution of setuid and/or setgid binaries. 336 | Unless this option is used setuid and setgid programs are executed 337 | without effective privileges. 338 | .SS Tracing 339 | .TP 12 340 | .BI "\-b " syscall 341 | .TQ 342 | .BR "\-\-detach\-on" = \fIsyscall\fR 343 | If specified syscall is reached, detach from traced process. 344 | Currently, only 345 | .BR execve (2) 346 | syscall is supported. This option is useful if you want to trace 347 | multi-threaded process and therefore require 348 | .BR \-f , 349 | but don't want to trace its (potentially very complex) children. 350 | .TP 351 | .B \-D 352 | .TQ 353 | .B \-\-daemonize 354 | .TQ 355 | .BR \-\-daemonize = grandchild 356 | Run tracer process as a grandchild, not as the parent of the 357 | tracee. This reduces the visible effect of 358 | .B strace 359 | by keeping the tracee a direct child of the calling process. 360 | .TP 361 | .B \-DD 362 | .TQ 363 | .BR \-\-daemonize = pgroup 364 | .TQ 365 | .BR \-\-daemonize = pgrp 366 | Run tracer process as tracee's grandchild in a separate process group. 367 | In addition to reduction of the visible effect of 368 | .BR strace , 369 | it also avoids killing of 370 | .B strace 371 | with 372 | .BR kill (2) 373 | issued to the whole process group. 374 | .TP 375 | .B \-DDD 376 | .TQ 377 | .BR \-\-daemonize = session 378 | Run tracer process as tracee's grandchild in a separate session 379 | ("true daemonisation"). 380 | In addition to reduction of the visible effect of 381 | .BR strace , 382 | it also avoids killing of 383 | .B strace 384 | upon session termination. 385 | .TP 386 | .B \-f 387 | .TQ 388 | .BR \-\-follow\-forks 389 | Trace child processes as they are created by currently traced 390 | processes as a result of the 391 | .BR fork (2), 392 | .BR vfork (2) 393 | and 394 | .BR clone (2) 395 | system calls. Note that 396 | .B \-p 397 | .I PID 398 | .B \-f 399 | will attach all threads of process 400 | .I PID 401 | if it is multi-threaded, not only thread with 402 | .IR thread_id " = " PID . 403 | .TP 404 | .B \-\-output\-separately 405 | If the 406 | .BR \-\-output = \fIfilename\fR 407 | option is in effect, each processes trace is written to 408 | .IR filename . pid 409 | where 410 | .I pid 411 | is the numeric process id of each process. 412 | .TP 413 | .B \-ff 414 | .TQ 415 | .B \-\-follow\-forks \-\-output\-separately 416 | Combine the effects of 417 | .B \-\-follow\-forks 418 | and 419 | .B \-\-output\-separately 420 | options. 421 | This is incompatible with 422 | .BR \-c , 423 | since no per-process counts are kept. 424 | .IP 425 | One might want to consider using 426 | .BR strace-log-merge (1) 427 | to obtain a combined strace log view. 428 | .TP 429 | .BI "\-I " interruptible 430 | .TQ 431 | .BR "\-\-interruptible" = \fIinterruptible\fR 432 | When 433 | .B strace 434 | can be interrupted by signals (such as pressing 435 | .BR CTRL\-C ). 436 | .RS 437 | .TP 15 438 | .BR 1 ", " anywhere 439 | no signals are blocked; 440 | .TQ 441 | .BR 2 ", " waiting 442 | fatal signals are blocked while decoding syscall (default); 443 | .TQ 444 | .BR 3 ", " never 445 | fatal signals are always blocked (default if 446 | .BR -o " " \fIFILE\fR " " \fIPROG\fR ); 447 | .TQ 448 | .BR 4 ", " never_tstp 449 | fatal signals and 450 | .BR SIGTSTP " (" CTRL\-Z ) 451 | are always blocked (useful to make 452 | .BI "strace -o " "FILE PROG" 453 | not stop on 454 | .BR CTRL\-Z , 455 | default if 456 | .BR \-D ). 457 | .RE 458 | .SS Filtering 459 | .TP 12 460 | \fB\-e\ trace\fR=\,\fIsyscall_set\fR 461 | .TQ 462 | \fB\-\-trace\fR=\,\fIsyscall_set\fR 463 | Trace only the specified set of system calls. 464 | .I syscall_set 465 | is defined as 466 | [\fB!\fR]\,\fIvalue\fR[\fB,\fR\,\fIvalue\/\fR], 467 | and 468 | .I value 469 | can be one of the following: 470 | .RS 471 | .TP 13 472 | .I syscall 473 | Trace specific syscall, specified by its name (but see 474 | .BR NOTES ). 475 | .TP 476 | .BI ? value 477 | Question mark before the syscall qualification allows suppression of error 478 | in case no syscalls matched the qualification provided. 479 | .TP 480 | .BI / regex 481 | Trace only those system calls that match the 482 | .IR regex . 483 | You can use 484 | .B POSIX 485 | Extended Regular Expression syntax (see 486 | .BR regex (7)). 487 | .TP 488 | .IB syscall @64 489 | Trace 490 | .I syscall 491 | only for the 64-bit personality. 492 | .TP 493 | .IB syscall @32 494 | Trace 495 | .I syscall 496 | only for the 32-bit personality. 497 | .TP 498 | .IB syscall @x32 499 | Trace 500 | .I syscall 501 | only for the 32-on-64-bit personality. 502 | .TP 503 | .B %file 504 | .TQ 505 | .BR file 506 | Trace all system calls which take a file name as an argument. You 507 | can think of this as an abbreviation for 508 | .BR "\-e\ trace" = open , stat , chmod , unlink ,... 509 | which is useful to seeing what files the process is referencing. 510 | Furthermore, using the abbreviation will ensure that you don't 511 | accidentally forget to include a call like 512 | .BR lstat (2) 513 | in the list. Betchya woulda forgot that one. 514 | The syntax without a preceding percent sign 515 | .RB (\[dq] "-e trace" = file \[dq]) 516 | is deprecated. 517 | .TP 518 | .B %process 519 | .TQ 520 | .B process 521 | Trace system calls associated with process lifecycle 522 | (creation, exec, termination). 523 | The syntax without a preceding percent sign 524 | .RB (\[dq] "-e trace" = process \[dq]) 525 | is deprecated. 526 | .TP 527 | .B %net 528 | .TQ 529 | .B %network 530 | .TQ 531 | .B network 532 | Trace all the network related system calls. 533 | The syntax without a preceding percent sign 534 | .RB (\[dq] "-e trace" = network \[dq]) 535 | is deprecated. 536 | .TP 537 | .BR %signal 538 | .TQ 539 | .BR signal 540 | Trace all signal related system calls. 541 | The syntax without a preceding percent sign 542 | .RB (\[dq] "-e trace" = signal \[dq]) 543 | is deprecated. 544 | .TP 545 | .BR %ipc 546 | .TQ 547 | .BR ipc 548 | Trace all IPC related system calls. 549 | The syntax without a preceding percent sign 550 | .RB (\[dq] "-e trace" = ipc \[dq]) 551 | is deprecated. 552 | .TP 553 | .BR %desc 554 | .TQ 555 | .BR desc 556 | Trace all file descriptor related system calls. 557 | The syntax without a preceding percent sign 558 | .RB (\[dq] "-e trace" = desc \[dq]) 559 | is deprecated. 560 | .TP 561 | .BR %memory 562 | .TQ 563 | .BR memory 564 | Trace all memory mapping related system calls. 565 | The syntax without a preceding percent sign 566 | .RB (\[dq] "-e trace" = memory \[dq]) 567 | is deprecated. 568 | .TP 569 | .BR %creds 570 | Trace system calls that read or modify user and group identifiers or capability sets. 571 | .TP 572 | .BR %stat 573 | Trace stat syscall variants. 574 | .TP 575 | .BR %lstat 576 | Trace lstat syscall variants. 577 | .TP 578 | .BR %fstat 579 | Trace fstat, fstatat, and statx syscall variants. 580 | .TP 581 | .BR %%stat 582 | Trace syscalls used for requesting file status (stat, lstat, fstat, fstatat, 583 | statx, and their variants). 584 | .TP 585 | .BR %statfs 586 | Trace statfs, statfs64, statvfs, osf_statfs, and osf_statfs64 system calls. 587 | The same effect can be achieved with 588 | .BR "\-e\ trace" = /^(.*_)?statv?fs 589 | regular expression. 590 | .TP 591 | .BR %fstatfs 592 | Trace fstatfs, fstatfs64, fstatvfs, osf_fstatfs, and osf_fstatfs64 system calls. 593 | The same effect can be achieved with 594 | .BR "\-e\ trace" = /fstatv?fs 595 | regular expression. 596 | .TP 597 | .BR %%statfs 598 | Trace syscalls related to file system statistics (statfs-like, fstatfs-like, 599 | and ustat). The same effect can be achieved with 600 | .BR "\-e\ trace" = /statv?fs|fsstat|ustat 601 | regular expression. 602 | .TP 603 | .BR %clock 604 | Trace system calls that read or modify system clocks. 605 | .TP 606 | .BR %pure 607 | Trace syscalls that always succeed and have no arguments. 608 | Currently, this list includes 609 | .BR arc_gettls "(2), " getdtablesize "(2), " getegid "(2), " getegid32 "(2)," 610 | .BR geteuid "(2), " geteuid32 "(2), " getgid "(2), " getgid32 "(2)," 611 | .BR getpagesize "(2), " getpgrp "(2), " getpid "(2), " getppid "(2)," 612 | .BR get_thread_area (2) 613 | (on architectures other than x86), 614 | .BR gettid "(2), " get_tls "(2), " getuid "(2), " getuid32 "(2)," 615 | .BR getxgid "(2), " getxpid "(2), " getxuid "(2), " kern_features "(2), and" 616 | .BR metag_get_tls "(2)" 617 | syscalls. 618 | .RE 619 | .IP 620 | The 621 | .B \-c 622 | option is useful for determining which system calls might be useful 623 | to trace. For example, 624 | .BR trace = open,close,read,write 625 | means to only 626 | trace those four system calls. Be careful when making inferences 627 | about the user/kernel boundary if only a subset of system calls 628 | are being monitored. The default is 629 | .BR trace = all . 630 | .TP 631 | \fB\-e\ signal\fR=\,\fIset\fR 632 | .TQ 633 | \fB\-\-signal\fR=\,\fIset\fR 634 | Trace only the specified subset of signals. The default is 635 | .BR signal = all . 636 | For example, 637 | .BR signal "=!" SIGIO 638 | (or 639 | .BR signal "=!" io ) 640 | causes 641 | .B SIGIO 642 | signals not to be traced. 643 | .TP 644 | \fB\-e\ status\fR=\,\fIset\fR 645 | .TQ 646 | \fB\-\-status\fR=\,\fIset\fR 647 | Print only system calls with the specified return status. The default is 648 | .BR status = all . 649 | When using the 650 | .B status 651 | qualifier, because 652 | .B strace 653 | waits for system calls to return before deciding whether they should be printed 654 | or not, the traditional order of events may not be preserved anymore. If two 655 | system calls are executed by concurrent threads, 656 | .B strace 657 | will first print both the entry and exit of the first system call to exit, 658 | regardless of their respective entry time. The entry and exit of the second 659 | system call to exit will be printed afterwards. Here is an example when 660 | .BR select (2) 661 | is called, but a different thread calls 662 | .BR clock_gettime (2) 663 | before 664 | .BR select (2) 665 | finishes: 666 | .CW 667 | [pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0 668 | [pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3]) 669 | .CE 670 | .I set 671 | can include the following elements: 672 | .RS 673 | .TP 13 674 | .B successful 675 | Trace system calls that returned without an error code. 676 | The 677 | .B -z 678 | option has the effect of 679 | .BR status = successful . 680 | .TQ 681 | .B failed 682 | Trace system calls that returned with an error code. 683 | The 684 | .B -Z 685 | option has the effect of 686 | .BR status = failed . 687 | .TQ 688 | .B unfinished 689 | Trace system calls that did not return. This might happen, for example, due to 690 | an execve call in a neighbour thread. 691 | .TQ 692 | .B unavailable 693 | Trace system calls that returned but strace failed to fetch the error status. 694 | .TQ 695 | .B detached 696 | Trace system calls for which strace detached before the return. 697 | .RE 698 | .TP 699 | .BI "\-P " path 700 | .TQ 701 | .BR "\-\-trace\-path" = \fIpath\fR 702 | Trace only system calls accessing 703 | .IR path . 704 | Multiple 705 | .B \-P 706 | options can be used to specify several paths. 707 | .TP 708 | .B \-z 709 | .TQ 710 | .B \-\-successful\-only 711 | Print only syscalls that returned without an error code. 712 | .TP 713 | .B \-Z 714 | .TQ 715 | .B \-\-failed\-only 716 | Print only syscalls that returned with an error code. 717 | .SS Output format 718 | .TP 12 719 | .BI "\-a " column 720 | .TQ 721 | .BR "\-\-columns" = \fIcolumn\fR 722 | Align return values in a specific column (default column 40). 723 | .TP 724 | \fB\-e\ abbrev\fR=\,\fIsyscall_set\fR 725 | .TQ 726 | \fB\-\-abbrev\fR=\,\fIsyscall_set\fR 727 | Abbreviate the output from printing each member of large structures. 728 | The syntax of the 729 | .I syscall_set 730 | specification is the same as in the 731 | .B "-e trace" 732 | option. 733 | The default is 734 | .BR abbrev = all . 735 | The 736 | .B \-v 737 | option has the effect of 738 | .BR abbrev = none . 739 | .TP 740 | \fB\-e\ verbose\fR=\,\fIsyscall_set\fR 741 | .TQ 742 | \fB\-\-verbose\fR=\,\fIsyscall_set\fR 743 | Dereference structures for the specified set of system calls. 744 | The syntax of the 745 | .I syscall_set 746 | specification is the same as in the 747 | .B "-e trace" 748 | option. 749 | The default is 750 | .BR verbose = all . 751 | .TP 752 | \fB\-e\ raw\fR=\,\fIsyscall_set\fR 753 | .TQ 754 | \fB\-\-raw\fR=\,\fIsyscall_set\fR 755 | Print raw, undecoded arguments for the specified set of system calls. 756 | The syntax of the 757 | .I syscall_set 758 | specification is the same as in the 759 | .B "-e trace" 760 | option. 761 | This option has the effect of causing all arguments to be printed 762 | in hexadecimal. This is mostly useful if you don't trust the 763 | decoding or you need to know the actual numeric value of an 764 | argument. 765 | See also 766 | .B \-X raw 767 | option. 768 | .TP 769 | \fB\-e\ read\fR=\,\fIset\fR 770 | .TQ 771 | \fB\-\-read\fR=\,\fIset\fR 772 | Perform a full hexadecimal and ASCII dump of all the data read from 773 | file descriptors listed in the specified set. For example, to see 774 | all input activity on file descriptors 775 | .I 3 776 | and 777 | .I 5 778 | use 779 | \fB\-e\ read\fR=\,\fI3\fR,\fI5\fR. 780 | Note that this is independent from the normal tracing of the 781 | .BR read (2) 782 | system call which is controlled by the option 783 | .BR -e "\ " trace = read . 784 | .TP 785 | \fB\-e\ write\fR=\,\fIset\fR 786 | .TQ 787 | \fB\-\-write\fR=\,\fIset\fR 788 | Perform a full hexadecimal and ASCII dump of all the data written to 789 | file descriptors listed in the specified set. For example, to see 790 | all output activity on file descriptors 791 | .I 3 792 | and 793 | .I 5 794 | use 795 | \fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR. 796 | Note that this is independent from the normal tracing of the 797 | .BR write (2) 798 | system call which is controlled by the option 799 | .BR -e "\ " trace = write . 800 | .TP 801 | \fB\-e\ quiet\fR=\,\fIset\fR 802 | .TQ 803 | \fB\-\-quiet\fR=\,\fIset\fR 804 | .TQ 805 | \fB\-\-silent\fR=\,\fIset\fR 806 | .TQ 807 | \fB\-\-silence\fR=\,\fIset\fR 808 | Suppress various information messages. The default is 809 | .BR quiet = none . 810 | .I set 811 | can include the following elements: 812 | .RS 813 | .TP 17 814 | .B attach 815 | Suppress messages about attaching and detaching 816 | .RB (\[dq] "[ Process NNNN attached ]" "\[dq]," 817 | .RB "\[dq]" "[ Process NNNN detached ]" "\[dq])." 818 | .TQ 819 | .B exit 820 | Suppress messages about process exits 821 | .RB (\[dq] "+++ exited with SSS +++" \[dq]). 822 | .TQ 823 | .B path-resolution 824 | Suppress messages about resolution of paths provided via the 825 | .B \-P 826 | option 827 | .RB (\[dq] "Requested path \[dq]...\[dq] resolved into \[dq]...\[dq]" \[dq]). 828 | .TQ 829 | .B personality 830 | Suppress messages about process personality changes 831 | .RB (\[dq] "[ Process PID=NNNN runs in PPP mode. ]" \[dq]). 832 | .TQ 833 | .B thread-execve 834 | .TQ 835 | .B superseded 836 | Suppress messages about process being superseded by 837 | .BR execve (2) 838 | in another thread 839 | .RB (\[dq] "+++ superseded by execve in pid NNNN +++" \[dq]). 840 | .RE 841 | .TP 842 | \fB\-e\ decode\-fds\fR=\,\fIset\fR 843 | .TQ 844 | \fB\-\-decode\-fds\fR=\,\fIset\fR 845 | Decode various information associated with file descriptors. The default is 846 | .BR decode\-fds = none . 847 | .I set 848 | can include the following elements: 849 | .RS 850 | .TP 8 851 | .B path 852 | Print file paths. 853 | .TQ 854 | .B socket 855 | Print socket protocol-specific information, 856 | .TQ 857 | .B dev 858 | Print character/block device numbers. 859 | .TQ 860 | .B pidfd 861 | Print PIDs associated with pidfd file descriptors. 862 | .RE 863 | .TP 864 | .BR "\-e\ kvm" = vcpu 865 | .TQ 866 | .BR "\-\-kvm" = vcpu 867 | Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0 868 | or higher. 869 | .TP 870 | .B \-i 871 | .TQ 872 | .B \-\-instruction\-pointer 873 | Print the instruction pointer at the time of the system call. 874 | .TP 875 | .B \-n 876 | .TQ 877 | .B \-\-syscall\-number 878 | Print the syscall number. 879 | .if ''#' .TP 880 | .if ''#' .B \-k 881 | .if ''#' .TQ 882 | .if ''#' .B \-\-stack\-traces 883 | .if ''#' Print the execution stack trace of the traced 884 | .if ''#' processes after each system call. 885 | .TP 886 | .BI "\-o " filename 887 | .TQ 888 | .BR "\-\-output" = \fIfilename\fR 889 | Write the trace output to the file 890 | .I filename 891 | rather than to stderr. 892 | .IR filename . pid 893 | form is used if 894 | .B \-ff 895 | option is supplied. 896 | If the argument begins with '|' or '!', the rest of the 897 | argument is treated as a command and all output is piped to it. 898 | This is convenient for piping the debugging output to a program 899 | without affecting the redirections of executed programs. 900 | The latter is not compatible with 901 | .B \-ff 902 | option currently. 903 | .TP 904 | .B \-A 905 | .TQ 906 | .B \-\-output\-append\-mode 907 | Open the file provided in the 908 | .B \-o 909 | option in append mode. 910 | .TP 911 | .B \-q 912 | .TQ 913 | .B \-\-quiet 914 | .TQ 915 | .BR \-\-quiet = attach , personality 916 | Suppress messages about attaching, detaching, and personality changes. 917 | This happens automatically when output is redirected to a file 918 | and the command is run directly instead of attaching. 919 | .TP 920 | .B \-qq 921 | .TQ 922 | .BR \-\-quiet = attach , personality , exit 923 | Suppress messages attaching, detaching, personality changes, 924 | and about process exit status. 925 | .TP 926 | .B \-qqq 927 | .TQ 928 | .BR \-\-quiet = all 929 | Suppress all suppressible messages (please refer to the 930 | .B -e quiet 931 | option description for the full list of suppressible messages). 932 | .TP 933 | .B \-r 934 | .TQ 935 | .BR \-\-relative\-timestamps [= \fIprecision\fR ] 936 | Print a relative timestamp upon entry to each system call. This 937 | records the time difference between the beginning of successive 938 | system calls. 939 | .I precision 940 | can be one of 941 | .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns 942 | (nanoseconds), and allows setting the precision of time value being printed. 943 | Default is 944 | .B us 945 | (microseconds). 946 | Note that since 947 | .B \-r 948 | option uses the monotonic clock time for measuring time difference and not the 949 | wall clock time, its measurements can differ from the difference in time 950 | reported by the 951 | .B \-t 952 | option. 953 | .TP 954 | .BI "\-s " strsize 955 | .TQ 956 | .BR "\-\-string\-limit" = \fIstrsize\fR 957 | Specify the maximum string size to print (the default is 32). Note 958 | that filenames are not considered strings and are always printed in 959 | full. 960 | .TP 961 | .BR \-\-absolute\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]] 962 | .TQ 963 | .BR \-\-timestamps [=[[ format: ] \fIformat\fR ],[[ precision: ] \fIprecision ]] 964 | Prefix each line of the trace with the wall clock time in the specified 965 | .I format 966 | with the specified 967 | .IR precision . 968 | .I format 969 | can be one of the following: 970 | .RS 971 | .TP 14 972 | .B none 973 | No time stamp is printed. 974 | Can be used to override the previous setting. 975 | .TQ 976 | .B time 977 | Wall clock time 978 | .RB ( strftime (3) 979 | format string is 980 | .BR %T ). 981 | .TQ 982 | .B unix 983 | Number of seconds since the epoch 984 | .RB ( strftime (3) 985 | format string is 986 | .BR %s ). 987 | .RE 988 | .IP 989 | .I precision 990 | can be one of 991 | .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns 992 | (nanoseconds). 993 | Default arguments for the option are 994 | .BR format:time , precision:s . 995 | .TP 996 | .B \-t 997 | .TQ 998 | .B \-\-absolute\-timestamps 999 | Prefix each line of the trace with the wall clock time. 1000 | .TP 1001 | .B \-tt 1002 | .TQ 1003 | .BR \-\-absolute\-timestamps = precision:us 1004 | If given twice, the time printed will include the microseconds. 1005 | .TP 1006 | .B \-ttt 1007 | .TQ 1008 | .BR \-\-absolute\-timestamps = format:unix , precision:us 1009 | If given thrice, the time printed will include the microseconds 1010 | and the leading portion will be printed as the number 1011 | of seconds since the epoch. 1012 | .TP 1013 | .B \-T 1014 | .TQ 1015 | .BR \-\-syscall\-times [= \fIprecision\fR ] 1016 | Show the time spent in system calls. This records the time 1017 | difference between the beginning and the end of each system call. 1018 | .I precision 1019 | can be one of 1020 | .BR s " (for seconds), " ms " (milliseconds), " us " (microseconds), or " ns 1021 | (nanoseconds), and allows setting the precision of time value being printed. 1022 | Default is 1023 | .B us 1024 | (microseconds). 1025 | .TP 1026 | .B \-v 1027 | .TQ 1028 | .B \-\-no\-abbrev 1029 | Print unabbreviated versions of environment, stat, termios, etc. 1030 | calls. These structures are very common in calls and so the default 1031 | behavior displays a reasonable subset of structure members. Use 1032 | this option to get all of the gory details. 1033 | .TP 1034 | .B \-x 1035 | .TQ 1036 | .BR \-\-strings\-in\-hex = \fInon\-ascii\fR 1037 | Print all non-ASCII strings in hexadecimal string format. 1038 | .TP 1039 | .B \-xx 1040 | .TQ 1041 | .B \-\-strings\-in\-hex 1042 | .TQ 1043 | .BR \-\-strings\-in\-hex = \fIall\fR 1044 | Print all strings in hexadecimal string format. 1045 | .TP 1046 | .BI "\-X " format 1047 | .TQ 1048 | .BR "\-\-const\-print\-style" = \fIformat\fR 1049 | Set the format for printing of named constants and flags. 1050 | Supported 1051 | .I format 1052 | values are: 1053 | .RS 1054 | .TP 10 1055 | .B raw 1056 | Raw number output, without decoding. 1057 | .TQ 1058 | .B abbrev 1059 | Output a named constant or a set of flags instead of the raw number if they are 1060 | found. 1061 | This is the default 1062 | .B strace 1063 | behaviour. 1064 | .TQ 1065 | .B verbose 1066 | Output both the raw value and the decoded string (as a comment). 1067 | .RE 1068 | .TP 1069 | .B \-y 1070 | .TQ 1071 | .B \-\-decode\-fds 1072 | .TQ 1073 | .BR \-\-decode\-fds = path 1074 | Print paths associated with file descriptor arguments. 1075 | .TP 1076 | .B \-yy 1077 | .TQ 1078 | .BR \-\-decode\-fds = all 1079 | Print all available information associated with file descriptors: 1080 | protocol-specific information associated with socket file descriptors, 1081 | block/character device number associated with device file descriptors, 1082 | and PIDs associated with pidfd file descriptors. 1083 | .TP 1084 | .B \-\-pidns\-translation 1085 | If strace and tracee are in different PID namespaces, print PIDs in 1086 | strace's namespace, too. 1087 | .SS Statistics 1088 | .TP 12 1089 | .B \-c 1090 | .TQ 1091 | .B \-\-summary\-only 1092 | Count time, calls, and errors for each system call and report a summary on 1093 | program exit, suppressing the regular output. 1094 | This attempts to show system time (CPU time spent running 1095 | in the kernel) independent of wall clock time. If 1096 | .B \-c 1097 | is used with 1098 | .BR \-f , 1099 | only aggregate totals for all traced processes are kept. 1100 | .TP 1101 | .B \-C 1102 | .TQ 1103 | .B \-\-summary 1104 | Like 1105 | .B \-c 1106 | but also print regular output while processes are running. 1107 | .TP 1108 | .BI "\-O " overhead 1109 | .TQ 1110 | .BR "\-\-summary\-syscall\-overhead " = \fIoverhead\fR 1111 | Set the overhead for tracing system calls to 1112 | .IR overhead . 1113 | This is useful for overriding the default heuristic for guessing 1114 | how much time is spent in mere measuring when timing system calls using 1115 | the 1116 | .B \-c 1117 | option. The accuracy of the heuristic can be gauged by timing a given 1118 | program run without tracing (using 1119 | .BR time (1)) 1120 | and comparing the accumulated 1121 | system call time to the total produced using 1122 | .BR \-c . 1123 | .IP 1124 | The format of 1125 | .I overhead 1126 | specification is described in section 1127 | .IR "Time specification format description". 1128 | .TP 1129 | .BI "\-S " sortby 1130 | .TQ 1131 | .BR "\-\-summary\-sort\-by" = \fIsortby\fR 1132 | Sort the output of the histogram printed by the 1133 | .B \-c 1134 | option by the specified criterion. Legal values are 1135 | .BR time " (or " time\-percent " or " time\-total " or " total\-time ), 1136 | .BR min\-time " (or " shortest " or " time\-min ), 1137 | .BR max\-time " (or " longest " or " time\-max ), 1138 | .BR avg\-time " (or " time\-avg ), 1139 | .BR calls " (or " count ), 1140 | .BR errors " (or " error ), 1141 | .BR name " (or " syscall " or " syscall\-name ), 1142 | and 1143 | .BR nothing " (or " none ); 1144 | default is 1145 | .BR time . 1146 | .TP 1147 | .BI "\-U " columns 1148 | .TQ 1149 | .BR "\-\-summary\-columns" = \fIcolumns\fR 1150 | Configure a set (and order) of columns being shown in the call summary. 1151 | The 1152 | .I columns 1153 | argument is a comma-separated list with items being one of the following: 1154 | .RS 1155 | .TP 36 1156 | .BR time\-percent " (or " time ) 1157 | Percentage of cumulative time consumed by a specific system call. 1158 | .TQ 1159 | .BR total\-time " (or " time\-total ) 1160 | Total system (or wall clock, if 1161 | .B \-w 1162 | option is provided) time consumed by a specific system call. 1163 | .TQ 1164 | .BR min\-time " (or " shortest " or " time\-min ) 1165 | Minimum observed call duration. 1166 | .TQ 1167 | .BR max\-time " (or " longest " or " time\-max ) 1168 | Maximum observed call duration. 1169 | .TQ 1170 | .BR avg\-time " (or " time\-avg ) 1171 | Average call duration. 1172 | .TQ 1173 | .BR calls " (or " count ) 1174 | Call count. 1175 | .TQ 1176 | .BR errors " (or " error ) 1177 | Error count. 1178 | .TQ 1179 | .BR name " (or " syscall " or " syscall\-name ) 1180 | Syscall name. 1181 | .RE 1182 | .IP 1183 | The default value is 1184 | .BR time\-percent , total\-time , avg\-time , calls , errors , name . 1185 | If the 1186 | .B name 1187 | field is not supplied explicitly, it is added as the last column. 1188 | .TP 1189 | .B \-w 1190 | .TQ 1191 | .B \-\-summary\-wall\-clock 1192 | Summarise the time difference between the beginning and end of 1193 | each system call. The default is to summarise the system time. 1194 | .SS Tampering 1195 | .TP 12 1196 | \fB\-e\ inject\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\,\fIsyscall\/\fR][:\fBdelay_enter\fR=\,\fIdelay\/\fR][:\fBdelay_exit\fR=\,\fIdelay\/\fR][:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR][:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR] 1197 | .TQ 1198 | \fB\-\-inject\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\,\fIsyscall\/\fR][:\fBdelay_enter\fR=\,\fIdelay\/\fR][:\fBdelay_exit\fR=\,\fIdelay\/\fR][:\fBpoke_enter\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR][:\fBpoke_exit\fR=\,\fI@argN=DATAN,@argM=DATAM...\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR] 1199 | Perform syscall tampering for the specified set of syscalls. 1200 | The syntax of the 1201 | .I syscall_set 1202 | specification is the same as in the 1203 | .B "-e trace" 1204 | option. 1205 | .IP 1206 | At least one of 1207 | .BR error , 1208 | .BR retval , 1209 | .BR signal , 1210 | .BR delay_enter , 1211 | or 1212 | .B delay_exit 1213 | options has to be specified. 1214 | .B error 1215 | and 1216 | .B retval 1217 | are mutually exclusive. 1218 | .IP 1219 | If :\fBerror\fR=\,\fIerrno\/\fR option is specified, 1220 | a fault is injected into a syscall invocation: 1221 | the syscall number is replaced by -1 which corresponds to an invalid syscall 1222 | (unless a syscall is specified with :\fBsyscall=\fR option), 1223 | and the error code is specified using a symbolic 1224 | .I errno 1225 | value like 1226 | .B ENOSYS 1227 | or a numeric value within 1..4095 range. 1228 | .IP 1229 | If :\fBretval\fR=\,\fIvalue\/\fR option is specified, 1230 | success injection is performed: the syscall number is replaced by -1, 1231 | but a bogus success value is returned to the callee. 1232 | .IP 1233 | If :\fBsignal\fR=\,\fIsig\/\fR option is specified with either a symbolic value 1234 | like 1235 | .B SIGSEGV 1236 | or a numeric value within 1..\fBSIGRTMAX\fR range, 1237 | that signal is delivered on entering every syscall specified by the 1238 | .IR set . 1239 | .IP 1240 | If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR 1241 | options are specified, delay injection is performed: the tracee is delayed 1242 | by time period specified by 1243 | .IR delay 1244 | on entering or exiting the syscall, respectively. 1245 | The format of 1246 | .I delay 1247 | specification is described in section 1248 | .IR "Time specification format description". 1249 | .IP 1250 | If :\fBpoke_enter\fR=\fI@argN=DATAN,@argM=DATAM...\fR 1251 | or :\fBpoke_exit\fR=\fI@argN=DATAN,@argM=DATAM...\fR options are specified, 1252 | tracee's memory at locations, pointed to by system call arguments 1253 | .IR argN 1254 | and 1255 | .IR argM 1256 | (going from 1257 | .IR arg1 1258 | to 1259 | .IR arg7 ) 1260 | is overwritten by data 1261 | .IR DATAN 1262 | and 1263 | .IR DATAM 1264 | (specified in hexadecimal format; for example :\fBpoke_enter\fR=\fI@arg1=0000DEAD0000BEEF\fR). 1265 | :\fBpoke_enter\fR modifies memory on syscall enter, and :\fBpoke_exit\fR - on exit. 1266 | .IP 1267 | If :\fBsignal\fR=\,\fIsig\/\fR option is specified without 1268 | :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or 1269 | :\fBdelay_{enter,exit}\fR=\,\fIusecs\/\fR options, 1270 | then only a signal 1271 | .I sig 1272 | is delivered without a syscall fault or delay injection. 1273 | Conversely, :\fBerror\fR=\,\fIerrno\/\fR or 1274 | :\fBretval\fR=\,\fIvalue\/\fR option without 1275 | :\fBdelay_enter\fR=\,\fIdelay\/\fR, 1276 | :\fBdelay_exit\fR=\,\fIdelay\/\fR or 1277 | :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal 1278 | or injecting a delay, etc. 1279 | .IP 1280 | If both :\fBerror\fR=\,\fIerrno\/\fR or :\fBretval\fR=\,\fIvalue\/\fR 1281 | and :\fBsignal\fR=\,\fIsig\/\fR options are specified, then both 1282 | a fault or success is injected and a signal is delivered. 1283 | .IP 1284 | if :\fBsyscall\fR=\fIsyscall\fR option is specified, the corresponding syscall 1285 | with no side effects is injected instead of -1. 1286 | Currently, only "pure" (see 1287 | .BR "-e trace" = "%pure" 1288 | description) syscalls can be specified there. 1289 | .IP 1290 | Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified, 1291 | an injection is being made into every invocation of each syscall from the 1292 | .IR set . 1293 | .IP 1294 | The format of the subexpression is: 1295 | .RS 15 1296 | .IP 1297 | \fIfirst\/\fR[\fB..\fR\,\fIlast\/\fR][\fB+\fR[\,\fIstep\/\fR]] 1298 | .RE 1299 | .IP 1300 | Number 1301 | .I first 1302 | stands for the first invocation number in the range, number 1303 | .I last 1304 | stands for the last invocation number in the range, and 1305 | .I step 1306 | stands for the step between two consecutive invocations. 1307 | The following combinations are useful: 1308 | .RS 1309 | .TP 18 1310 | .I first 1311 | For every syscall from the 1312 | .IR set , 1313 | perform an injection for the syscall invocation number 1314 | .I first 1315 | only. 1316 | .TQ 1317 | \fIfirst\/\fB..\fR\,\fIlast\fR 1318 | For every syscall from the 1319 | .IR set , 1320 | perform an injection for the syscall invocation number 1321 | .I first 1322 | and all subsequent invocations until the invocation number 1323 | .I last 1324 | (inclusive). 1325 | .TQ 1326 | \fIfirst\/\fB+\fR 1327 | For every syscall from the 1328 | .IR set , 1329 | perform injections for the syscall invocation number 1330 | .I first 1331 | and all subsequent invocations. 1332 | .TQ 1333 | \fIfirst\/\fB..\fR\,\fIlast\/\fB+\fR 1334 | For every syscall from the 1335 | .IR set , 1336 | perform injections for the syscall invocation number 1337 | .I first 1338 | and all subsequent invocations until the invocation number 1339 | .I last 1340 | (inclusive). 1341 | .TQ 1342 | \fIfirst\/\fB+\fR\,\fIstep\fR 1343 | For every syscall from the 1344 | .IR set , 1345 | perform injections for syscall invocations number 1346 | .IR first , 1347 | .IR first + step , 1348 | .IR first + step + step , 1349 | and so on. 1350 | .TQ 1351 | \fIfirst\/\fB..\fR\,\fIlast\fB+\fR\,\fIstep\fR 1352 | Same as the previous, but consider only syscall invocations with numbers up to 1353 | .I last 1354 | (inclusive). 1355 | .RE 1356 | .IP 1357 | For example, to fail each third and subsequent chdir syscalls with 1358 | .BR ENOENT , 1359 | use 1360 | \fB\-e\ inject\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR. 1361 | .IP 1362 | The valid range for numbers 1363 | .I first 1364 | and 1365 | .I step 1366 | is 1..65535, and for number 1367 | .I last 1368 | is 1..65534. 1369 | .IP 1370 | An injection expression can contain only one 1371 | .BR error = 1372 | or 1373 | .BR retval = 1374 | specification, and only one 1375 | .BR signal = 1376 | specification. If an injection expression contains multiple 1377 | .BR when = 1378 | specifications, the last one takes precedence. 1379 | .IP 1380 | Accounting of syscalls that are subject to injection 1381 | is done per syscall and per tracee. 1382 | .IP 1383 | Specification of syscall injection can be combined 1384 | with other syscall filtering options, for example, 1385 | \fB\-P \fI/dev/urandom \fB\-e inject\fR=\,\fIfile\/\fR:\fBerror\fR=\,\fIENOENT\fR. 1386 | .TP 1387 | \fB\-e\ fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR] 1388 | .TQ 1389 | \fB\-\-fault\fR=\,\fIsyscall_set\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR] 1390 | Perform syscall fault injection for the specified set of syscalls. 1391 | .IP 1392 | This is equivalent to more generic 1393 | \fB\-e\ inject\fR= expression with default value of 1394 | .I errno 1395 | option set to 1396 | .BR ENOSYS . 1397 | .SS Miscellaneous 1398 | .TP 12 1399 | .B \-d 1400 | .TQ 1401 | .B \-\-debug 1402 | Show some debugging output of 1403 | .B strace 1404 | itself on the standard error. 1405 | .TP 1406 | .B \-F 1407 | This option is deprecated. It is retained for backward compatibility only 1408 | and may be removed in future releases. 1409 | Usage of multiple instances of 1410 | .B \-F 1411 | option is still equivalent to a single 1412 | .BR \-f , 1413 | and it is ignored at all if used along with one or more instances of 1414 | .B \-f 1415 | option. 1416 | .TP 1417 | .B \-h 1418 | .TQ 1419 | .B \-\-help 1420 | Print the help summary. 1421 | .TP 1422 | .B \-\-seccomp\-bpf 1423 | Try to enable use of seccomp-bpf (see 1424 | .BR seccomp (2)) 1425 | to have 1426 | .BR ptrace (2)-stops 1427 | only when system calls that are being traced occur in the traced processes. 1428 | This option has no effect unless 1429 | .BR \-f / \-\-follow\-forks 1430 | is also specified. 1431 | .B \-\-seccomp\-bpf 1432 | is also not applicable to processes attached using 1433 | .BR \-p / \-\-attach 1434 | option. An attempt to enable system calls filtering using seccomp-bpf may 1435 | fail for various reasons, e.g. there are too many system calls to filter, 1436 | the seccomp API is not available, or 1437 | .B strace 1438 | itself is being traced. 1439 | In cases when seccomp-bpf filter setup failed, 1440 | .B strace 1441 | proceeds as usual and stops traced processes on every system call. 1442 | .TP 1443 | .B \-V 1444 | .TQ 1445 | .B \-\-version 1446 | Print the version number of 1447 | .BR strace . 1448 | .SS "Time specification format description" 1449 | .PP 1450 | Time values can be specified as a decimal floating point number 1451 | (in a format accepted by 1452 | .BR strtod (3)), 1453 | optionally followed by one of the following suffices that specify 1454 | the unit of time: 1455 | .B s 1456 | (seconds), 1457 | .B ms 1458 | (milliseconds), 1459 | .B us 1460 | (microseconds), or 1461 | .B ns 1462 | (nanoseconds). 1463 | If no suffix is specified, the value is interpreted as microseconds. 1464 | .PP 1465 | The described format is used for 1466 | .BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit 1467 | options. 1468 | .SH DIAGNOSTICS 1469 | When 1470 | .I command 1471 | exits, 1472 | .B strace 1473 | exits with the same exit status. 1474 | If 1475 | .I command 1476 | is terminated by a signal, 1477 | .B strace 1478 | terminates itself with the same signal, so that 1479 | .B strace 1480 | can be used as a wrapper process transparent to the invoking parent process. 1481 | Note that parent-child relationship (signal stop notifications, 1482 | .BR getppid (2) 1483 | value, etc) between traced process and its parent are not preserved 1484 | unless 1485 | .B \-D 1486 | is used. 1487 | .LP 1488 | When using 1489 | .B \-p 1490 | without a 1491 | .IR command , 1492 | the exit status of 1493 | .B strace 1494 | is zero unless no processes has been attached or there was an unexpected error 1495 | in doing the tracing. 1496 | .SH "SETUID INSTALLATION" 1497 | If 1498 | .B strace 1499 | is installed setuid to root then the invoking user will be able to 1500 | attach to and trace processes owned by any user. 1501 | In addition setuid and setgid programs will be executed and traced 1502 | with the correct effective privileges. 1503 | Since only users trusted with full root privileges should be allowed 1504 | to do these things, 1505 | it only makes sense to install 1506 | .B strace 1507 | as setuid to root when the users who can execute it are restricted 1508 | to those users who have this trust. 1509 | For example, it makes sense to install a special version of 1510 | .B strace 1511 | with mode 'rwsr-xr--', user 1512 | .B root 1513 | and group 1514 | .BR trace , 1515 | where members of the 1516 | .B trace 1517 | group are trusted users. 1518 | If you do use this feature, please remember to install 1519 | a regular non-setuid version of 1520 | .B strace 1521 | for ordinary users to use. 1522 | .SH "MULTIPLE PERSONALITIES SUPPORT" 1523 | On some architectures, 1524 | .B strace 1525 | supports decoding of syscalls for processes that use different ABI rather than 1526 | the one 1527 | .B strace 1528 | uses. 1529 | Specifically, in addition to decoding native ABI, 1530 | .B strace 1531 | can decode the following ABIs on the following architectures: 1532 | .TS H 1533 | allbox; 1534 | lb lb 1535 | l l. 1536 | Architecture ABIs supported 1537 | x86_64 i386, x32 [1]; i386 [2] 1538 | AArch64 ARM 32-bit EABI 1539 | PowerPC 64-bit [3] PowerPC 32-bit 1540 | s390x s390 1541 | SPARC 64-bit SPARC 32-bit 1542 | TILE 64-bit TILE 32-bit 1543 | .TE 1544 | .RS 0 1545 | .TP 5 1546 | [1] 1547 | When 1548 | .B strace 1549 | is built as an x86_64 application 1550 | .TQ 1551 | [2] 1552 | When 1553 | .B strace 1554 | is built as an x32 application 1555 | .TQ 1556 | [3] 1557 | Big endian only 1558 | .RE 1559 | .PP 1560 | This support is optional and relies on ability to generate and parse structure 1561 | definitions during the build time. 1562 | Please refer to the output of the 1563 | .B strace \-V 1564 | command in order to figure out what support is available in your 1565 | .B strace 1566 | build ("non-native" refers to an ABI that differs from the ABI 1567 | .B strace 1568 | has): 1569 | .TP 15 1570 | .B m32-mpers 1571 | .B strace 1572 | can trace and properly decode non-native 32-bit binaries. 1573 | .TQ 1574 | .B no-m32-mpers 1575 | .B strace 1576 | can trace, but cannot properly decode non-native 32-bit binaries. 1577 | .TQ 1578 | .B mx32-mpers 1579 | .B strace 1580 | can trace and properly decode non-native 32-on-64-bit binaries. 1581 | .TQ 1582 | .B no-mx32-mpers 1583 | .B strace 1584 | can trace, but cannot properly decode non-native 32-on-64-bit binaries. 1585 | .PP 1586 | If the output contains neither 1587 | .B m32-mpers 1588 | nor 1589 | .BR no-m32-mpers , 1590 | then decoding of non-native 32-bit binaries is not implemented at all 1591 | or not applicable. 1592 | .PP 1593 | Likewise, if the output contains neither 1594 | .B mx32-mpers 1595 | nor 1596 | .BR no-mx32-mpers , 1597 | then decoding of non-native 32-on-64-bit binaries is not implemented at all 1598 | or not applicable. 1599 | .SH NOTES 1600 | It is a pity that so much tracing clutter is produced by systems 1601 | employing shared libraries. 1602 | .LP 1603 | It is instructive to think about system call inputs and outputs 1604 | as data-flow across the user/kernel boundary. Because user-space 1605 | and kernel-space are separate and address-protected, it is 1606 | sometimes possible to make deductive inferences about process 1607 | behavior using inputs and outputs as propositions. 1608 | .LP 1609 | In some cases, a system call will differ from the documented behavior 1610 | or have a different name. For example, the 1611 | .BR faccessat (2) 1612 | system call does not have 1613 | .I flags 1614 | argument, and the 1615 | .BR setrlimit (2) 1616 | library function uses 1617 | .BR prlimit64 (2) 1618 | system call on modern (2.6.38+) kernels. These 1619 | discrepancies are normal but idiosyncratic characteristics of the 1620 | system call interface and are accounted for by C library wrapper 1621 | functions. 1622 | .LP 1623 | Some system calls have different names in different architectures and 1624 | personalities. In these cases, system call filtering and printing 1625 | uses the names that match corresponding 1626 | .BR __NR_ * 1627 | kernel macros of the tracee's architecture and personality. 1628 | There are two exceptions from this general rule: 1629 | .BR arm_fadvise64_64 (2) 1630 | ARM syscall and 1631 | .BR xtensa_fadvise64_64 (2) 1632 | Xtensa syscall are filtered and printed as 1633 | .BR fadvise64_64 (2). 1634 | .LP 1635 | On x32, syscalls that are intended to be used by 64-bit processes and not x32 1636 | ones (for example, 1637 | .BR readv (2), 1638 | that has syscall number 19 on x86_64, with its x32 counterpart has syscall 1639 | number 515), but called with 1640 | .B __X32_SYSCALL_BIT 1641 | flag being set, are designated with 1642 | .B "#64" 1643 | suffix. 1644 | .LP 1645 | On some platforms a process that is attached to with the 1646 | .B \-p 1647 | option may observe a spurious 1648 | .B EINTR 1649 | return from the current system call that is not restartable. 1650 | (Ideally, all system calls should be restarted on 1651 | .B strace 1652 | attach, making the attach invisible 1653 | to the traced process, but a few system calls aren't. 1654 | Arguably, every instance of such behavior is a kernel bug.) 1655 | This may have an unpredictable effect on the process 1656 | if the process takes no action to restart the system call. 1657 | .LP 1658 | As 1659 | .B strace 1660 | executes the specified 1661 | .I command 1662 | directly and does not employ a shell for that, scripts without shebang 1663 | that usually run just fine when invoked by shell fail to execute with 1664 | .B ENOEXEC 1665 | error. 1666 | It is advisable to manually supply a shell as a 1667 | .I command 1668 | with the script as its argument. 1669 | .SH BUGS 1670 | Programs that use the 1671 | .I setuid 1672 | bit do not have 1673 | effective user 1674 | .SM ID 1675 | privileges while being traced. 1676 | .LP 1677 | A traced process runs slowly (but check out the 1678 | .B \-\-seccomp\-bpf 1679 | option). 1680 | .LP 1681 | Traced processes which are descended from 1682 | .I command 1683 | may be left running after an interrupt signal 1684 | .RB ( CTRL\-C ). 1685 | .SH HISTORY 1686 | The original 1687 | .B strace 1688 | was written by Paul Kranenburg 1689 | for SunOS and was inspired by its 1690 | .B trace 1691 | utility. 1692 | The SunOS version of 1693 | .B strace 1694 | was ported to Linux and enhanced 1695 | by Branko Lankester, who also wrote the Linux kernel support. 1696 | Even though Paul released 1697 | .B strace 1698 | 2.5 in 1992, 1699 | Branko's work was based on Paul's 1700 | .B strace 1701 | 1.5 release from 1991. 1702 | In 1993, Rick Sladkey merged 1703 | .B strace 1704 | 2.5 for SunOS and the second release of 1705 | .B strace 1706 | for Linux, added many of the features of 1707 | .BR truss (1) 1708 | from SVR4, and produced an 1709 | .B strace 1710 | that worked on both platforms. In 1994 Rick ported 1711 | .B strace 1712 | to SVR4 and Solaris and wrote the 1713 | automatic configuration support. In 1995 he ported 1714 | .B strace 1715 | to Irix 1716 | and tired of writing about himself in the third person. 1717 | .PP 1718 | Beginning with 1996, 1719 | .B strace 1720 | was maintained by Wichert Akkerman. 1721 | During his tenure, 1722 | .B strace 1723 | development migrated to CVS; ports to FreeBSD and many architectures on Linux 1724 | (including ARM, IA-64, MIPS, PA-RISC, PowerPC, s390, SPARC) were introduced. 1725 | In 2002, the burden of 1726 | .B strace 1727 | maintainership was transferred to Roland McGrath. 1728 | Since then, 1729 | .B strace 1730 | gained support for several new Linux architectures (AMD64, s390x, SuperH), 1731 | bi-architecture support for some of them, and received numerous additions and 1732 | improvements in syscalls decoders on Linux; 1733 | .B strace 1734 | development migrated to 1735 | .B git 1736 | during that period. 1737 | Since 2009, 1738 | .B strace 1739 | is actively maintained by Dmitry Levin. 1740 | .B strace 1741 | gained support for AArch64, ARC, AVR32, Blackfin, Meta, Nios II, OpenRISC 1000, 1742 | RISC-V, Tile/TileGx, Xtensa architectures since that time. 1743 | In 2012, unmaintained and apparently broken support for non-Linux operating 1744 | systems was removed. 1745 | Also, in 2012 1746 | .B strace 1747 | gained support for path tracing and file descriptor path decoding. 1748 | In 2014, support for stack traces printing was added. 1749 | In 2016, syscall fault injection was implemented. 1750 | .PP 1751 | For the additional information, please refer to the 1752 | .B NEWS 1753 | file and 1754 | .B strace 1755 | repository commit log. 1756 | .SH REPORTING BUGS 1757 | Problems with 1758 | .B strace 1759 | should be reported to the 1760 | .UR mailto:strace\-devel@lists.strace.io 1761 | .B strace 1762 | mailing list 1763 | .UE . 1764 | .SH "SEE ALSO" 1765 | .BR strace-log-merge (1), 1766 | .BR ltrace (1), 1767 | .BR perf-trace (1), 1768 | .BR trace-cmd (1), 1769 | .BR time (1), 1770 | .BR ptrace (2), 1771 | .BR proc (5) 1772 | .PP 1773 | .UR https://strace.io/ 1774 | .B strace 1775 | Home Page 1776 | .UE 1777 | .SH AUTHORS 1778 | The complete list of 1779 | .B strace 1780 | contributors can be found in the 1781 | .B CREDITS 1782 | file. 1783 | --------------------------------------------------------------------------------