Snippets

For the good and lazy programmers, this section documents the library following the approach "a function - an example".

For every features exposed by the library you will find a brief explanation and an example of how to use it. Let's start.

read_string(address, count)

This function try to read from the process memory an ascii string, no longer than count bytes. So you can provide a large count value since the function recognizes the NULL terminating character.

Example:

rax_address = gdb.parse_and_eval("$rax")
string = gdb_utils.read_string(rax_address, 1024)
print string

In the example we first read the address of the string pointed by RAX register, and then read the actual string passing the numeric address to the function. The result can be safely printed.

execute_output(command)

This is perhaps the most important function of the library, on which the majority of the other functions are built.

Its behavior is very similar to gdb.execute(), since both functions allow to execute a GDB command, but execute_output also returns the output of the command.

This is extremely important because it permits to exploit many GDB features, which are not exported in the standard gdb python library.

Example:

output = gdb_utils.execute_output('info registers')
print output

The result will be:

rax            0x610	1552
rbx            0x8000	32768
rcx            0x60f020	6352928
rdx            0x8000	32768
rsi            0x610000	6356992
rdi            0x10000	0
...

You can use this function to examine process status, control its execution or set GDB options: the possibilities are endless...

execute_external(command), execute_external_output(command)

These functions are just utilities, since they do not use GDB. They simply execute an external shell command with the possibility to capture its output.

They can be useful if you want to call an external program to analyze system status, or other useful things that help the debugging activity.

Example:

execute_external('kill -9 <pid>')

output = execute_external('free')
print output

For the second call the result will be similar to:

             total       used       free     shared    buffers     cached
Mem:       4062352     819340    3243012          0      36244     336448
-/+ buffers/cache:     446648    3615704
Swap:            0          0          0

search_functions(regex='')

This function search program functions and return their names and addresses. It's possible to specify a regular expression to exclude unwanted results.

The return value is a python dictionary, where the key is the name and the item is the address of the function.

Example:

functions = gdb_utils.search_functions('@plt$')
print functions

The output (a bit reformatted...):

{
  'open@plt': 4200224,
  'fwrite@plt': 4200112,
  'fclose@plt': 4200080,
  'mbrtowc@plt': 4199328,
  '__cxa_atexit@plt': 4199616,
  'malloc@plt': 4199536,
  'realloc@plt': 4200128,
  'strlen@plt': 4199712,
  ...
}

In this case we only searched for functions contained in the Procedure Linkage Table, but the regular expression is totally arbitrary.

search_processes(regex='')

This functions returns a list of the current running processes, optionally filtered by the provided regular expression.

It's based on the external ps command, whose output is parsed into a (little complex) data structure. The data structure is essentially a list of dictionaries: every dictionary contains informations about a process.

The available informations are (snippet of code from the library):

# add process info to the list
processes.append({
    'user': field[0],
    'pid': int(field[1]),
    'percentage_cpu': eval(field[2]),
    'percentage_mem': eval(field[3]),
    'vsz': int(field[4]),
    'rss': int(field[5]),
    'tty': field[6],
    'stat': field[7],
    'start': field[8],
    'time': field[9],
    'command': field[10],
    'args': field[11:] if len(field) > 11 else ''
})

Example:

processes = gdb_utils.search_processes('^g')
print processes

The output (slightly reformatted...):

[
  {
   'tty': '?',
   'pid': 3453,
   'vsz': 280220,
   'args': '',
   'percentage_mem': 0.29999999999999999,
   'stat': 'Ssl',
   'start': '08:37',
   'command': 'gnome-settings-daemon',
   'user': 'geek',
   'time': '0:00',
   'percentage_cpu': 0.0,
   'rss': 13636
  },
  {
   'tty': '?',
   'pid': 3473,
   'vsz': 168484,
   'args': '',
   'percentage_mem': 0.0,
   'stat': 'Ss',
   'start': '08:37',
   'command': 'gnome-screensaver',
   'user': 'geek',
   'time': '0:00',
   'percentage_cpu': 0.0,
   'rss': 2816
  },
  ...
]

The regular expression is applied only to the process command field.