1## Command pcustom ##
2
3`gef` provides a way to create and apply to the currently debugged environment, any new structure (in the C-struct way). On top of simply displaying known and user-defined structures, it also allows to apply those structures to the current context. It intends to mimic the very useful [WinDBG `dt`](https://msdn.microsoft.com/en-us/library/windows/hardware/ff542772(v=vs.85).aspx) command.
4
5This is achieved via the command `pcustom` (for `print custom`), or you can use its alias, `dt` (in reference to the WinDBG command) as provided by the [`WinDbg compatibility extension`](https://github.com/hugsy/gef-extras/blob/master/scripts/windbg.py)
6
7
8### Configuration
9
10New structures can be stored in the location given by the configuration setting:
11```
12gef➤ gef config pcustom.struct_path
13```
14By default, this location is in `$TEMP/gef/structs` (e.g. `/tmp/user/1000/gef/structs`). The structure can be created as a simple `ctypes` structure, in a file called `<struct_name>.py`.
15
16You can naturally set this path to a new location
17```
18gef➤ gef config pcustom.struct_path /my/new/location
19```
20And save this change so you can re-use it directly next time you use `gdb`
21```
22gef➤ gef save
23[+] Configuration saved to '~/.gef.rc'
24```
25
26
27### Using user-defined structures
28
29You can list existing custom structures via
30```
31gef➤  pcustom list
32[+] Listing custom structures from '/tmp/structs'
33 →  /tmp/structs/A.py (A, B)
34 →  /tmp/structs/elf32_t.py (elf32_t)
35 →  /tmp/structs/elf64_t.py (elf64_t)
36[...]
37```
38
39To create or edit a structure, use `pcustom edit <struct_name>` to spawn your EDITOR with the targeted structure. If the file does not exist, `gef` will nicely create the tree and file, and fill it with a `ctypes` template that you can use straight away!
40
41```
42gef➤  pcustom new mystruct_t
43[+] Creating '/tmp/gef/structs/mystruct_t.py' from template
44```
45
46If the structure already exists, GEF will open the text editor to edit the known structure. This is equivalent to:
47
48```
49gef➤  pcustom edit elf32_t
50[+] Editing '/home/hugsy/code/gef-extras/structs/elf32_t.py'
51```
52
53
54
55The code can be defined just as any Python (using `ctypes`) code.
56
57```
58from ctypes import *
59
60'''
61typedef struct {
62  int age;
63  char name[256];
64  int id;
65} person_t;
66'''
67
68class person_t(Structure):
69    _fields_ = [
70        ("age",  c_int),
71        ("name", c_char * 256),
72        ("id", c_int),
73    ]
74
75    _values_ = [
76    	# You can define a function to substitute the value
77    	("age", lambda age: "Old" if age > 40 else "Young"),
78    	# Or alternatively a list of 2-tuples
79    	("id", [
80    		(0, "root"),
81    		(1, "normal user"),
82    		(None, "Invalid person")
83    	])
84    ]
85```
86
87`pcustom` requires at least one argument, which is the name of the structure. With only one argument, `pcustom` will dump all the fields of this structure.
88
89```
90gef➤  dt person_t
91+0000   age          c_int   /* size=0x4 */
92+0004   name         c_char_Array_256   /* size=0x100 */
93+0104   id           c_int   /* size=0x4 */
94```
95
96
97
98By providing an address or a GDB symbol, `gef` will apply this user-defined structure to the specified address:
99
100![gef-pcustom-with-address](https://i.imgur.com/vWGnu5g.png)
101
102This means that we can now create very easily new user-defined structures
103
104For a full demo, watch the following tutorial:
105
106[![yt-gef-pcustom](https://img.youtube.com/vi/pid2aW7Bt_w/0.jpg)](https://www.youtube.com/watch?v=pid2aW7Bt_w)
107
108Additionally, if you have successfully configured your IDA settings (see command `ida-interact`), you can also directly import the structure(s) that was(were) reverse-engineered in IDA directly in your GDB session:
109![ida-structure-examples](https://i.imgur.com/Tnsf6nt.png)
110
111And then use the command `ida ImportStructs` to import all the structures, or `ida ImportStruct <StructName>` to only import a specific one:
112
113```
114gef➤  ida ImportStructs
115[+] Success
116```
117
118Which will become:
119
120![ida-structure-imported](https://i.imgur.com/KVhyopO.png)
121
122
123### Public repository of structures
124
125A community contributed repository of structures can be found in [`gef-extras`](https://github.com/hugsy/gef-extras). To deploy it:
126
127In bash:
128```
129$ git clone https://github.com/hugsy/gef-extras
130```
131
132In GEF:
133```
134gef➤ gef config pcustom.struct_path /path/to/gef-extras/structs
135gef➤ gef save
136```
137
138Then either close GDB or `gef reload`. You can confirm the structures were correctly loaded in GEF's prompt:
139
140```
141gef➤ pcustom list
142```
143
144Should return several entries.
145
146And remember this is collaborative repository, so feel free to contribute too!
147