1scanmem(1) General Commands Manual scanmem(1)
2
6 scanmem - locate and modify a variable in an executing process.
7
10 scanmem [--version] [--help] target-program-pid
11
15 scanmem is an interactive debugging utility that can be used to isolate
16 the address of a variable in an executing process by successively scan‐
17 ning the process' address space looking for matching values. By inform‐
18 ing scanmem how the value of the variable changes over time, it can
19 determine the actual location (or locations) of the variable by succes‐
20 sively eliminating non-matches. scanmem determines where to look by
21 searching for mappings with read / write permission, these are referred
22 to as regions. Users can eliminate regions they believe are likely
23 unrelated to the target variable (for example, located in a shared
24 library unrelated to the variable in question), this will improve the
25 speed of the scan, which can initially be quite slow in large programs.
26 Once a variable has been found, scanmem can monitor the variable, or
28 change it to a user specified value, either once, or continually over a
29 period of time.
30 scanmem works similarly to the " pokefinders " once commonly used to
32 cheat at video games, this function is a good demonstration of how to
33 use scanmem , and is used in the documentation.
34
37 scanmem should be invoked with the process id of the program you wish
38 to debug as an argument. Once started, scanmem accepts interactive com‐
39 mands. These are described below, however entering help at the > prompt
40 will allow you to access scanmem's online documentation.
41 The target-program-pid can be specified in decimal, hexadecimal, or
43 octal using the standard C language notation (leading 0x for hexadeci‐
44 mal, leading 0 for octal, anything else is assumed to be decimal).
45 --version
47 Print version and exit.
49 --help
51 Print a short description of command line options then exit.
53
56 While in interactive mode, scanmem prints a decimal number followed by
57 > , the number is the current number of possible candidates for the
58 target variable that are known. 0 indicates that no possible variables
59 have been eliminated yet.
60 n
62 Where n represents any number in decimal, octal or hexadecimal, this
64 command tells scanmem that the current value of the target variable is
65 exactly n. scanmem will begin a search of the entire address space, or
66 the existsing known matches (if any), eliminating any variable that
67 does not have this value.
68 set [match-id][,match-id,...]=]value[/delay] [...]
70 Set the value value into the match numbers match-id , or if just value
72 is specified, all known matches. value can be specified in standard C
73 language notation. All known matches, along with their match-id's can
74 be displayed using the list command. Multiple match-id's can be speci‐
75 fied, separated with commas and terminated with an = sign. To set a
76 value continually, suffix the command with / followed by the number of
77 seconds to wait between sets. You can interrupt the set command with ^C
78 to return to the scanmem prompt. This can be used to sustain the value
79 of a variable which decreases overtime, for example a timer that is
80 decremented every second can be set to 100 every 10 seconds to prevent
81 some property from ever changing.
82 This command is used to change the value of the variable(s) once found
84 by elimination. Please note, some applications will store values in
85 multiple locations.
86 >
88 Tells scanmem that it should eliminate all matched variables that have
90 not increased since the last search. For example, if the value of a
91 variable is known to be zero when a program is executed, but increases
92 over time, this command can be used several times to eliminate vari‐
93 ables that have decreased or not changed.
94 <
96 As for > but indicates that the target variable has decreased since the
98 last scan.
99 =
101 As for > but indicates that the target variable has not changed since
103 last scan.
104 snapshot
106 Save a snapshot of existing program state, for use with > , < , and = ,
108 although other commands can still be used.
109 list
111 List all the possible candidates currently known, including their
113 address, last known value and pathname. The value in the first column
114 is the match id, and can be used in conjunction with the delete command
115 to eliminate matches. The flags displayed indicate what is currently
116 known about the variable at that location, a capital letter indicates
117 the property is set, lowercase indicates the property is not set.
118 ┌──┬──────────────────────────────────┐
121 │C │ The value could be a char. │
122 ├──┼──────────────────────────────────┤
123 │S │ The value could be a short. │
124 ├──┼──────────────────────────────────┤
125 │I │ The value could be an int. │
126 ├──┼──────────────────────────────────┤
127 │L │ The value could be a long. │
128 ├──┼──────────────────────────────────┤
129 │F │ The value could be a float. │
130 ├──┼──────────────────────────────────┤
131 │N │ The value is known to be signed. │
132 ├──┼──────────────────────────────────┤
133 │Z │ This flag is not currently used. │
134 └──┴──────────────────────────────────┘
135 delete [match-id]
136 Delete match match-id , which can be found from the output of the list
138 command. To delete all matches, see the reset command, or to delete all
139 matches associated with a particular library, see the dregion command,
140 which also removes any associated matches. Pleae note that match-ids
141 may be recalculated after matches are removed or added.
142 watch [match-id]
144 Monitor the value of match-id , and print its value as it changes.
146 Every change is printed along with a timestamp, you can interrupt this
147 command with ^C to stop monitoring.
148 pid [new-pid]
150 Print out the process id of the current target program, or change the
152 target to new-pid , which will reset existing regions and matches.
153 lregions
155 List all the known regions, this can be used in combination with the
157 dregion command to eliminate regions that the user believes are not
158 related to the variable in question, thus reducing the address space
159 required to search. The value in the first column is the region-id
160 which must be passed to the dregion command. The size and path (if
161 applicable) is also printed. This can be used to eliminate regions
162 located in shared libraries that are unlikely to be relevant to the
163 variable required.
164 dregion [!][region-id][,region-id][,...]
166 Delete the region region-id , along with any matches from the match
168 list. The region-id can be found in the output of the lregions command.
169 A leading ! indicates the list should be inverted.
170 reset
172 Forget all known matches and start again.
174 shell [shell-command]
176 Execute shell-command using /bin/sh, then return.
178 version
180 Print the version of scanmem in use.
182 help
184 Print a short summary of available commands.
186 exit
188 Detach from the target program and exit immediately.
190
193 Cheat at nethack, on systems where nethack is not installed sgid.
194 $ scanmem `pidof nethack`
196 info: attaching to pid 13070.
197 info: maps file located at /proc/13070/maps opened.
198 info: 17 suitable regions found.
199 Please enter current value, or "help" for other commands.
200 0>
201 The 0 in the scanmem prompt indicates we currently have no candidates,
203 so I enter how much gold I currently have (91 pieces) and let scanmem
204 find the potential candidates.
205 0> 91
208 info: searching 0xbfffa000 - 0xc0000000...........ok
209 info: searching 0x401c2000 - 0x401e3000...........ok
210 info: searching 0x401c1000 - 0x401c2000...........ok
211 info: searching 0x401b6000 - 0x401b8000...........ok
212 info: searching 0x401b5000 - 0x401b6000...........ok
213 info: searching 0x40189000 - 0x4018a000...........ok
214 info: searching 0x40188000 - 0x40189000...........ok
215 info: searching 0x40181000 - 0x40183000...........ok
216 info: searching 0x4017f000 - 0x40181000...........ok
217 info: searching 0x40070000 - 0x40071000...........ok
218 info: searching 0x40068000 - 0x40070000...........ok
219 info: searching 0x40030000 - 0x40031000...........ok
220 info: searching 0x40029000 - 0x4002a000...........ok
221 info: searching 0x4001f000 - 0x40020000...........ok
222 info: searching 0x40016000 - 0x40017000...........ok
223 info: searching 0x081d4000 - 0x0820a000...........ok
224 info: searching 0x081b7000 - 0x081d4000...........ok
225 info: we currently have 16 matches.
226 16> list
227 [ 0] 0x081c1f34 { 91} (/usr/share/games/nethack/nethack)
228 [ 1] 0x081c1780 { 91} (/usr/share/games/nethack/nethack)
229 [ 2] 0x081be436 { 91} (/usr/share/games/nethack/nethack)
230 [ 3] 0x081eeffc { 91} (unassociated, typically .bss)
231 [ 4] 0x081ee0c0 { 91} (unassociated, typically .bss)
232 [ 5] 0x081eddb8 { 91} (unassociated, typically .bss)
233 [ 6] 0x081d6d88 { 91} (unassociated, typically .bss)
234 [ 7] 0x4001fcd3 { 91} (/lib/libnss_compat-2.3.5.so)
235 [ 8] 0x40029fe3 { 91} (/lib/libnss_nis-2.3.5.so)
236 [ 9] 0x40029f8b { 91} (/lib/libnss_nis-2.3.5.so)
237 [10] 0x40029efb { 91} (/lib/libnss_nis-2.3.5.so)
238 [11] 0x40029bff { 91} (/lib/libnss_nis-2.3.5.so)
239 [12] 0x401d18d3 { 91} (unassociated, typically .bss)
240 [13] 0x401d156f { 91} (unassociated, typically .bss)
241 [14] 0x401d120b { 91} (unassociated, typically .bss)
242 [15] 0xbfffd76c { 91} (unassociated, typically .bss)
243 16>
244 16 potential matches were found, many of them are clearly unrelated, as
246 they're part of unrelated libraries (libnss_nis.so). We could make
247 scanmem eliminate these manually using the delete command, however just
248 waiting until the amount of gold changes and telling scanmem the new
249 value should be enough. I find some more gold, and tell scanmem the new
250 value, 112.
251 16> 112
253 info: we currently have 1 matches.
254 info: match identified, use "set" to modify value.
255 info: enter "help" for other commands.
256 1> list
257 [ 0] 0x081d6d88 { 112} (unassociated, typically .bss)
258 Only one of the 16 original candidates now have the value 112, so this
260 must be where the amount of gold is stored. I'll try setting it to
261 10,000 pieces.
262 1> set 10000
264 info: setting *0x081d6d88 to 10000...
265 1>
266 The resulting nethack status:
268 Dlvl:1 $:10000 HP:15(15) Pw:2(2) AC:7 Exp:1
270
273 scanmem has been tested on multiple large programs, including the 3d
274 shoot-em-up quake3 linux.
275 Obviously, scanmem can crash your program if used incorrectly.
277 Some programs store values in multiple locations, this is why set will
279 change all known matches.
280
283 The first scan can be very slow on large programs, this is not a prob‐
284 lem for subsequent scans as huge portions of the address space are usu‐
285 ally eliminated. This could be improved in future, perhaps by assuming
286 all integers are aligned by default. Suggestions welcome.
287 The snapshot command uses memory inefficiently, and should probably not
289 be used on large programs. In future this will use a more intelligent
290 format.
291
294 Tavis Ormandy <taviso@sdf.lonestar.org>
295 http://taviso.decsystem.org/
297 All bug reports, suggestions or feedback welcome.
299
302 gdb(1) ptrace(2) nethack(6) pidof(8)
303version 0.07 June 05, 2007 scanmem(1)