Decompiler Window

The main window maintains a map between the individual variable and operator tokens displayed in the window and the machine instructions which correspond to them. Disassembled machine instructions are displayed by any Listing window, and having both a Listing and Decompiler window side by side lets the user see this correspondence between the decompiled and disassembled views of the function. Clicking on tokens in the Decompiler window causes the Listing window to navigate to the corresponding instruction, and clicking instructions in the Listing window causes the Decompiler window to navigate to the corresponding line. Highlighting a region of code in either window causes the corresponding region in the other window to be highlighted.

Variable Name and Variable Sub-field Name tokens map to the machine instruction which wrote to the variable at that point in function.

Operator tokens map to the machine instruction which performed that operation.

Function Name tokens, if they represent a call to another function, map to the machine instruction executing the call.

Comment tokens map to the machine address associated with the comment.

In general, the map between machine instructions and tokens is not one-to-one because the Decompiler transforms its underlying representation of the function. An instruction may no longer have any operator that corresponds to it in the decompiled result. Tokens may be transformed from the natural operation of the machine instruction they are associated with or may represent the effect of multiple instructions.

 - button

Exports the decompiled result of the current function to a file. A file chooser dialog is displayed to select the name of the output file. If a file extension is not specified, a ".c" is appended to the filename. If the file already exists, a final dialog is presented to confirm that the file should be overwritten.

This action exports a single function at a time. The user can export all functions simultaneously from the Code Browser, by selecting the menu File -> Export Program... and then choosing C/C++ from the drop-down menu. See the full documentation for the Export dialog.

 - button

Creates a new Snapshot window. The Snapshot window displays the same function as the Decompiler window on which the action was triggered, and if that window navigates to other functions, the Snapshot does not follow but continues to display the original function (see Snapshot Windows).

 - button

Triggers a re-decompilation of the current function displayed in the window. Any cached results are discarded, and a full decompile is performed.

	This action is not necessary for normal reverse engineering tasks. Re-decompilation is automatically triggered for all Decompiler windows by any change to the Program, so the most up-to-date decompilation is always available to the user without this action. This action is primarily a debugging aid for plug-in developers.

 - toggle button

Quickly turn off the Eliminate unreachable code decompiler setting.

 - toggle button

Quickly turn off the Respect read-only flags decompiler setting.

 - button

Copies the currently selected text in the Decompiler window to the clipboard.

This action is located in the drop-down menu on the right side of the Decompiler window tool/title bar.

Information suitable for debugging the decompilation process for the current function is collected and saved to an output file in XML format. A file chooser dialog is presented to the user to choose the output file. The file is useful when submitting bug reports about the Decompiler as it is generally much smaller than the entire Program and only contains information specific to the function. Information is generated by performing the full decompilation of the function and collecting all the data and annotations required during the process, including instruction bytes, symbols, data-types, and other settings affecting decompilation.

This action is located in the drop-down menu on the right side of the Decompiler window tool/title bar.

Generate a data flow graph based upon the results in the active Decompiler window, and render it using the current Graph Service.

This action is located in the drop-down menu on the right side of the Decompiler window tool/title bar.

Generate a control flow graph based upon the results in the active Decompiler window, and render it using the current Graph Service.

Moves the Decompiler window cursor and highlights the token. Within the main window, if a token has a machine address associated with it, a left-click generates a navigation event to that address, which may cause other windows to display code near that address (see Cross-Highlighting).

Selecting a '(' or ')' token causes it and its matching parenthesis to be highlighted along with the entire expression they surround.

Selecting a '{' or '}' token causes it and its matching brace to be highlighted.

Moves the Decompiler window cursor, highlights the token, and brings up the menu of context-sensitive actions. Any highlighting and navigation is identical to a left-click. The menu actions presented depend primarily on the token type and are tailored to the context at that point in the code.

Navigates based on the selected symbol or other token (see below). If the selected token represents a formal symbol, such as a function name or a global variable, double-clicking causes a navigation event to the address associated with the symbol.

This action is performed by clicking twice on the desired token with the left mouse button.

Opens a new Snapshot window, navigating it to the selected symbol. This is a convenience for immediately decompiling and displaying a called function in a new window, without disturbing the active window. The behavior is similar to the Double-Click action, the selected token must represent a function name symbol or possibly a constant address, but the navigation occurs in the new Snapshot window.

This action is performed by clicking twice on the desired token with the left mouse button, while holding down the Ctrl key.

Generates a navigation event to the address, within the current function, associated with the clicked token. This allows Snapshot windows to do basic cross-highlighting in the same way as the main Decompiler window. A ctrl-shift-click causes Listing and other windows to navigate to and display the same portion of code currently being displayed in the Snapshot window (see Cross-Highlighting).

This action is performed by clicking on the desired token with the left mouse button, while holding down both the Ctrl and Shift keys.

Highlights every occurrence of a variable, constant, or operator represented by the selected token, within the Decompiler window. There are actions available from the popup menu and from the keyboard to navigate to each highlighted token.

Create a pointer with an offset into its underlying data-type and apply it to the selected variable.

The action is available on variable tokens that the Decompiler has already determined are pointers, and is designed to create an offset pointer, which is a typedef with its component offset attribute set (See Offset Pointers). It brings up a dialog that allows the user to select:

If the Decompiler determines that the selected variable points into a known structure, this information is used to prepopulate the dialog, with the structure used as the underlying data-type.

Clicking OK in the dialog immediately creates the new pointer data-type and attaches it to the selected variable, triggering a new decompilation. The annotation may reveal new field accesses or other markup associated with the underlying data-type, which will be immediately visible once decompilation completes.

If the user selects the name of an offset pointer that already exists and its other properties match the dialog, the existing pointer will be used to complete the action, rather than creating a new data-type. If an unrelated data-type already exists with the selected name, the action cannot be completed and the dialog will display a warning.

	If the offset pointer already exists but its offset does not match the value specified in the dialog, the user is given the option of changing the existing data-type's offset. Confirming this change alters the existing data-type, which may affect analysis of other unrelated parts of the program that use it.

Once an offset pointer exists, either by invoking this action or by creating it manually (see Pointer-Typedef Settings), it can be applied to variables like any other data-type, either through the Listing window or using the Retype Variable action in the Decompiler window.

Automatically create a structure data-type for a selected variable based on its use within the current function and possibly child functions.

The structure definition is filled in by examining how the variable is used, assuming it is a pointer to the structure, tracing data flow to all the expressions the variable is used in. LOAD and STORE operations trigger new fields and additive offsets are traced to calculate the offset of the fields within the structure definition.

Once the new structure is created, the selected variable is retyped to be a pointer to the structure. Within the window, the function is decompiled again and references to new fields in the structure should be immediately apparent. These can be renamed or retyped from the window to further refine the new structure definition (see Rename Variable).

Set or change a comment at the address of the selected token.

These actions bring up the general Comment dialog (see Comments), which associates the comment with a specific address in the Program. For comment actions in the Decompiler, this address is of the machine instruction most closely linked to the selected token. Any comments generated from a Decompiler window will be visible in Listing and other windows viewing the same section of code.

A Decompiler window can display all comment types, but this may be affected by the Display options (see Comments).

Commit the names of any local variables discovered during the Decompiler's analysis to the Program database as new Variable Annotations. The recovered data-type is not committed as part of the annotation, only the name and storage location.

Parameters are not affected by this command (see Commit Params/Return). The purpose of the command is to synchronize the local variables in the Decompiler's view of a function with the formal Variable Annotations in the disassembly view, without otherwise affecting the decompilation. After executing this command, additional changes to local variables can be performed directly on the corresponding annotations displayed in Listing windows, using various methods (see Variable Annotations). Data-types are not forced for new annotations, they are created with an undefined data-type, which allows the Decompiler to refine its view of the variable's data-type as new information becomes available (see Forcing Data-types).

Commit the Decompiler's analysis of the input parameters and return value of the current function as annotations to the Program database.

In the absence of either imported or user-defined information about a function's prototype, the Decompiler performs its own analysis of what the prototype is, determining the storage location and data-type of all parameters and the return value. This action commits this analysis permanently for the current function displayed in the window, creating a matching Variable Annotation for each input parameter and the return value. The new annotations will be displayed in a Listing window as part of the function header, and the action effectively synchronizes the disassembly view and Decompiler's view of the function prototype.

Committed prototype information is used both when decompiling the function itself and when decompiling other functions that call it. The committed annotations are forcing on the Decompiler (see Forcing Data-types), and it will no longer perform prototype recovery analysis for that function. The Decompiler assumes the committed parameters, and only the committed parameters, exist and will not modify their data-types, with the exception of parameters that are explicitly marked as having an undefined data-type. The user must manually modify individual variables or clear the entire prototype if they want a change (see Variable Annotations).

Change the displayed encoding for the integer or character constant under the cursor.

Various encodings are possible.

This command primarily targets a constant token in the Decompiler window, but if there is a scalar operand in an instruction that corresponds with the selected constant, the same conversion is also applied to the scalar in any Listing window. This is equivalent to selecting the Convert command from a Listing window. There may not be a scalar operand directly corresponding to the selected constant, in which case the conversion will be applied only in the Decompiler window.

The data-type of the selected token is not changed by the action, and it retains its meaning in the decompiler output. This slightly limits the possible conversions as signed values cannot be forced into an unsigned representation, and vice versa.

The constant's encoding can be changed by selecting a different Convert command, or it can be returned to its default encoding by selecting the Remove Convert/Equate command.

Copy selected code from the Decompiler window into the clipboard.

This is part of the standard copy capabilities for all Ghidra windows and is suitable for copying (sections of) Decompiler output into other documents.

Bring up a dialog for editing the definition of the data-type under the cursor.

The cursor must be on the data-type name token, not on a variable or other syntax. The action is only available for structures and unions, which will bring up the Structure Editor, and for enumerations, which will bring up the Enum Editor.

Any change to the definition of the data-type is automatically incorporated by the Decompiler into its output (see Variable Data-types).

Bring up a dialog for editing the prototype of a selected function and other details about how it passes parameters.

The action is available from any token in the Decompiler window. Most tokens trigger editing of the current function itself, but a called function can be edited by putting the cursor on its name specifically.

The dialog provides detailed control over elements like

See documentation for the Function Editor Dialog. The Decompiler automatically incorporates any changes into its output.

Search for strings within the active window, in the current Decompiler output.

The command brings up a dialog where a search pattern can be entered as a raw string or regular expression. The search is performed directly on the text of the decompiled function, from the current cursor; forward each time the Next button is hit, or backward for the Previous button. Any match is highlighted in the window, and the cursor is set to the start of the match.

Force the Decompiler to assume a specific read or write to a variable, with a union data-type, is referring to a user selected field.

A union data-type overlays multiple other data-type interpretations (fields) on top of one variable; any one of which may be active at a point where the variable is accessed. The Decompiler automatically selects which field it thinks is being referenced (See Unions). But this action allows the user to force the Decompiler to use a particular field.

The cursor must be on the token currently representing the union field to be changed. The action brings up a dialog with a drop-down menu of the possible fields that can be forced. A field must be compatible with the selected access or it will not be listed in the menu. This usually means that the data-type of the field must be the same size as the read or write being performed. The menu option (no field) may also be available, which if selected, indicates that the Decompiler should treat the read or write as accessing the union as a whole. Its also possible that no other field is possible but the current one. In which case, the dialog will display a warning message and contain no drop-down menu.

Selecting a menu option and clicking OK completes the action. Subsequent decompilation should show the new field at the selected access point, and the data-type associated with the selected field will likely propagate further across the function, possibly triggering substantial changes to the output.

If there is more than one access to the same variable with a union data-type, each representative field token can be forced to a new field individually.

These actions are available from the keyboard, with no equivalent pop-up menu entry. Shift-Open Bracket will go to the previous enclosing open brace. Shift-Close Bracket will go to the next enclosing closing brace. These key bindings can be changed via the Tool Options Dialog.

Paired braces can also be navigated by double-clicking.

These actions are available from the popup menu and keyboard. Only tokens highlighted from the middle-mouse will be navigated. Shift-Comma will go to the previous highlighted token. Shift-Period will go to the next highlighted token. These key bindings can be changed via the Tool Options Dialog.

All these actions highlight a specific set of variable tokens tracing the data flow of the selected variable within the current function, defined as the directed flow of data from input variables through operations that manipulate their value to their output variables. The operations and variables chain together to form data-flow paths.

A secondary highlight is a semi-permanent token highlight in the Decompiler window that, unlike normal highlights, will not go away as the user clicks other tokens. The color and text being highlighted is controlled by the user and will persist for for the duration of the Ghidra session or until the user explicitly removes the highlight.

Override the function prototype corresponding to the function under the cursor.

This action can be triggered at a call site, where the function being decompiled is calling into another function. Users must select either the token representing the called function's name or one of the tokens representing the function pointer at the call site. The action brings up a dialog where the function prototype corresponding to the call site can be edited. The dialog provides fine-grained control of the return data-type along with the name and data-type of each input parameter. The function prototype properties Calling Convention, In Line, and No Return can also be set (see Function Prototypes).

Confirming the dialog forces the new function prototype on the Decompiler's view of the called function, but only for the single selected call site.

This action is suitable for either indirect calls or direct calls to functions taking a variable number of arguments; situations where a complete description of all parameters is not available. For direct calls with a fixed number of arguments, it is almost always better to provide parameter information by setting the function's prototype directly (see the Commit Params/Return command). In this situation, the "Override Signature" command is still possible, but it will bring up a confirmation dialog.

Edit the existing overriding function prototype to the called function under the cursor.

This action can only be triggered at call sites with an existing signature override. As with the Override Signature command, users must select either the token representing the called function's name or the tokens representing the function pointer at the call site. The action brings up a dialog where the user can edit the current overriding function prototype.

Remove the display conversion or equate from the constant under the cursor.

The selected constant must have had either a Convert or a Set Equate... command applied to it. After applying this command, the conversion is no longer applied, and the selected constant will be displayed using the decompiler's default strategy, which depends on the data-type of the constant and other display settings (See Integer format).

Remove the overriding function prototype applied previously to the called function under the cursor.

This action can only be triggered at call sites, where an overriding prototype was previously placed by the Override Signature command. As with this command, users must select either the token representing the called function's name or the tokens representing the function pointer at the call site. The action causes the override to be removed immediately. Parameter information will be drawn from the Decompiler's normal analysis.

Remove the label corresponding to the token under the cursor.

A label can be removed by triggering this action while the corresponding label token is under the cursor. For more on removing labels, see Removing a Label.

The change will be immediately visible across all references to the label (including in any Decompiler, Listing, and Functions windows).

Rename the function corresponding to the token under the cursor.

The current function can be renamed by selecting the name token within the function's declaration at the top of the Decompiler window, or individual called functions can be renamed by selecting their name token within a call expression. This action brings up a dialog containing a text field prepopulated with the name to be changed. The current namespace (and any parent namespaces) is presented in a drop-down menu. Editing the text field changes the base name of the function, and selecting within the drop-down menu allows the function to be moved into a parent namespace.

A new or child namespace can be specified by prepending the base name with the namespace using the C++ "::" delimiter characters. Any namespace path entered this way is considered relative to the namespace set in the drop-down menu, so the Global namespace may need to be selected if the user wants to specify an absolute path. If any path element of the namespace does not exist, it is created.

The change will be immediately visible across all references to the function (including in any Decompiler, Listing, and Functions windows).

Rename the field currently under the cursor within its structure data-type definition.

The action brings up a dialog prepopulated with the current name of the field. Editing and confirming this dialog immediately changes the field's name in its corresponding structure definition. The dialog enforces unique field names.

If the initial name looks like field_0x.., it may be that the field offset was discovered by the Decompiler, and the field does not exist in the structure definition. In this case, a new field is created at that offset, with the new name and a data-type of undefined.

The change to the definition is visible globally throughout the Program, anywhere the data-type is referenced. Decompilation is triggered again to incorporate the new name, but the output is otherwise unaffected.

Within a Decompiler window, field name tokens are presented in context, showing how they are used within the code flow of the current function. Combined with Auto Create Structure and Retype Field, this action allows a structure to be created and filled in based on this context.

Rename the global variable corresponding to the token under the cursor.

This action brings up a dialog containing a text field prepopulated with the current name of the variable. The current namespace (and any parent namespaces) is presented in a drop-down menu. Editing the text field changes the base name of the variable, and selecting within the drop-down menu allows the variable to be moved into a parent namespace.

A new or child namespace can be specified by prepending the base name with the namespace using the C++ "::" delimiter characters. Any namespace path entered this way is considered relative to the namespace set in the drop-down menu, so the Global namespace may need to be selected if the user wants to specify an absolute path. If any path element of the namespace does not exist, it is created.

The change will be immediately visible across all references to the variable, including in Decompiler and Listing windows. A new decompilation is triggered to incorporate the new name, but the output is otherwise unaffected.

Rename the label corresponding to the token under the cursor.

A label can be renamed by triggering this action while the corresponding label token is under the cursor. This action brings up the Edit Label Dialog.

The change will be immediately visible across all references to the label (including in any Decompiler, Listing, and Functions windows).

Rename the local variable or parameter currently under the cursor.

The action brings up a dialog prepopulated with the current name of the variable. Editing and confirming this dialog immediately changes the name, unless there is a conflict with another variable.

Decompilation is triggered again to incorporate the new name, causing local variable declarations to be reordered and line breaks to change, but otherwise the the output is unaffected.

Local variables and parameters presented by the Decompiler may be invented on-the-fly and don't necessarily have a formal annotation in Ghidra (see Variable Annotations). Performing this action on a variable will create an annotation if one didn't exist previously, which will generally be visible as part of the function header in any Listing window. A new annotation will not commit the data-type of the variable, and data-types applied later, and elsewhere in the function, can still propagate into the variable.

Performing this action on a function parameter causes a formal annotation to be created for all parameters, although the names of any other parameters will not be changed.

Change the data-type of the field currently under the cursor within its structure data-type definition.

The action brings up a dialog prepopulated with the current data-type associated with the field. The user can select any fixed length data-type in the Program, although selecting a larger data-type may cause an error if there is not enough room for it with other existing fields. Editing and confirming this dialog immediately changes the corresponding data-type definition.

The change to the definition is visible globally throughout the Program, anywhere the data-type is referenced, and is forcing on the Decompiler (see Forcing Data-types). Decompilation is triggered again, and the new data-type is propagated from the point of the field reference(s). Changes to the output may be large and indirect.

Change the data-type of the global variable currently under the cursor.

This action brings up a dialog prepopulated with the current data-type of the variable. The user can select any fixed length data-type in the Program that matches the size of the variable. Editing and confirming this dialog immediately changes the data-type.

The change is visible globally throughout the Program, anywhere the variable is referenced, and is forcing on the Decompiler (see Forcing Data-types). Decompilation is triggered again, and the new data-type is propagated from the variable reference(s). Changes to the output may be large and indirect.

Change the data-type of the current function's return value.

This action is only available from the data-type token in the function declaration, at the top of the Decompiler's output. It brings up a dialog prepopulated with the current data-type returned by the function. The user can select any fixed length data-type in the Program. Editing and confirming this dialog immediately changes the data-type. If an annotation for the return value (named <RETURN>) did not exist previously, one is created.

As input parameter annotations and the return value annotation must be committed as a whole (see the discussion of function prototype's in Forcing Data-types), if no prototype existed previously, this action also causes variable annotations for all input parameters to be created as well. In this situation, the action is equivalent to Commit Params/Return, and a confirmation dialog comes up to notify the user.

Setting a data-type on the return value using this action affects decompilation for the function itself and, additionally, any function that calls this function. Within a calling function, the Decompiler propagates the data-type into the variable or expression incorporating the return value at each call site.

Change the data-type of the local variable or parameter currently under the cursor.

This action brings up a dialog prepopulated with the current data-type of the variable. The user can select any fixed length data-type in the Program that matches the size of the variable. Editing and confirming this dialog immediately changes the data-type.

The change to the data-type is forcing on the Decompiler (see Forcing Data-types). Decompilation is triggered again, and the new data-type is propagated from the variable reference(s). Changes to the output may be large and indirect.

Local variables and parameters presented by the Decompiler may be invented on-the-fly and don't necessarily have a formal annotation in Ghidra (see Variable Annotations). Performing this action on a variable will create an annotation if one didn't exist previously, which will generally be visible as part of the function header in any Listing window.

Performing this action on a function parameter causes a formal annotation to be created for all parameters to the function, and the number of parameters and their memory locations become fixed. If the annotation of another parameter did not exist previously, then its data-type is not forced by this action.

Data-type information applied to parameters using this action is especially impactful because it affects decompilation for the function owning the parameter and, additionally, any function that calls this owning function.

Change the display of the integer or character constant under the cursor to an equate string.

An equate is a descriptive string associated with a specific constant value, which is managed globally for a Program by the Equate plug-in (See Equates).

The Set Equate command, brings up a dialog listing other equates that have previously been associated with the selected constant. The user can choose an equate from this list or define a new equate for the constant by typing in the text field at the top of the dialog. Alternately, the text field can be used as a filter to narrow down possibilities prior to selecting from the list. Clicking OK, completes the action, and the selected equate is substituted for its constant.

This command primarily targets a constant token in a Decompiler window, but if there is a scalar operand in an instruction that corresponds with the selected constant, the same equate is also applied to the scalar in any Listing window. This is equivalent to selecting the Set Equate command from a Listing window. There may not be a scalar operand directly corresponding to the selected constant, in which case the equate will be applied only in the Decompiler window.

Once an equate is applied, the constant can be returned to its default display by selecting the Remove Convert/Equate command.

Split a high-level variable so that the selected token becomes a new variable with the smallest possible range.

The Decompiler defines high-level variables in terms of varnodes that are merged together to produce the final variable. Some merging is speculative, which reduces the number of variables overall, but is not strictly necessary for valid decompilation. The merged variable can be represented with two or more variables that have a smaller range (see the documentation on HighVariable).

This command is only available if the selected token is part of a high-level variable that has been speculatively merged. The part of the variable that is directly represented by the token is split out as its own variable, retaining the name of the original variable. Any other pieces become a separate variable with a new name.