Clang

Overview

The clang parser is IDA's default type parser. It is based on the clang compiler and can handle a wide variety of C/C++/Obj-C header files, including those with complex preprocessor directives and macros. It replaces both the legacy parser and IDAClang.

Config file

Note that cfg/idaclang.cfg is used as the config file for the clang parser as well, so that the new parser automatically picks up the settings you may have already configured for IDAClang.

Security

Some compiler command-line options may be dangerous, so only a small subset is accepted by default, and the rest are ignored. If you want to use additional options, you can add them to the CLANG_ARGV_PERMITTED_OPTIONS setting in idaclang.cfg.

LLVM

It is based on the LLVM project (21.1.5) and uses the clang compiler to parse header files and extract type information.

Motivation

Legacy parser

The built-in legacy parser is a simple yet efficient parser that can handle C header files. However, it is not very good at handling C++ header files.

IDAClang parser (removed)

The IDAClang parser (removed in 9.5) could handle C++ header files, but was purely based on the clang compiler and did not handle IDA-specific keywords, such as _BYTE or _QWORD.

clang parser

The official clang parser bridges the gap between the legacy parser and the now-removed IDAClang, being able to handle both C and C++ header files, while also supporting IDA-specific keywords. On top of that, it adds support for Objective-C and Objective-C++ header files. It is the default Source parser, as shown in Options → Compiler.

There are three ways of importing types using the clang parser:

1. Using the Add type option in Local Types window.

2. Using the File → Load file → Parse C header file... option in the menu bar.

3. Scripting the parsing process using IDAPython.

Examples

VTables

class C
{
  virtual void func(void);
};

The following types will be generated in the database:

00000000 struct __cppobj C // sizeof=0x4
00000000 {
00000000     C_vtbl *__vftable;
00000004 };

00000000 struct C_vtbl_layout // sizeof=0xC
00000000 {
00000000     __int32 thisOffset;                 // offset_to_top (0)
00000004     void *rtti;                         // C
00000008     void (*func)(C *__hidden this);
0000000C };

00000000 struct /*VFT*/ C_vtbl // sizeof=0x4
00000000 {
00000000     void (*func)(C *__hidden this);
00000004 };

IDA-specific keywords

The following code will be correctly parsed by the clang parser:

struct foo
{
    _DWORD bar;
    __usercall void do_something();
};

It will be added to the database as:

00000000 struct foo // sizeof=0x4
00000000 {
00000000     _DWORD bar;
00000004 };

C++ templates

template <typename T, typename V> struct S
{
  T x;
  V y;
};

typedef S<int, void *> instance_t;

To parse this code:

1. Go to Options → Compiler → Parser specific options and mark "No IDA specific extensions".

2. Put it in an include file and select File → Load file → Parse C header file... from the menu bar.

The parsed result will be:

00000000 struct __cppobj S<int, void *> // sizeof=0x8
00000000 {                                       // XREF: instance_t/r
00000000     int x;
00000004     void *y;
00000008 };

00000008 typedef S<int, void *> instance_t;

C++20

In order to parse C++20 code, make sure your Include directories and Arguments options are set up correctly. For example, You can use the following commands to figure out the correct include paths and arguments for your system:

xcrun --show-sdk-path  # get the SDK path (-isysroot)
xcrun clang++ -std=c++20 -v -E -x c++ /dev/null  # get the include paths and arguments for C++20

The Arguments option should include the -std=c++20 flag:

-x c++ -std=c++20 -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

Here's an example of C++20 code that can be parsed by the clang parser:

#include <concepts>
#include <compare>
#include <cstdint>
#include <span>
#include <string_view>

template <typename T>
concept Addable = requires(T a, T b) {
  { a + b } -> std::same_as<T>;
};

struct Record {
  std::uint32_t id;
  std::string_view name;

  auto operator <=> (const Record &) const = default;
};

Final result:

00000000 struct __cppobj Record // sizeof=0x18
00000000 {
00000000     uint32_t id;
00000004     // padding byte
00000005     // padding byte
00000006     // padding byte
00000007     // padding byte
00000008     std::string_view name;
00000018 };

Objective-C

#import <Foundation/Foundation.h>

@interface MyClass : NSObject
{
    int _counter;
    NSString *_name;
}

@property(nonatomic, strong) NSString *title;
@property(nonatomic, assign) NSInteger value;

- (instancetype)init;
- (void)reset;
- (int)add:(int)a to:(int)b;

+ (BOOL)isValid:(NSString *)string;
+ (MyClass *)sharedInstance;

@end

Before parsing, make sure to set the right language in Options → Compiler → Parser specific options (Objective-C or Objective-C++), and to have the right include paths set in Options → Compiler → Include directories.

To see what these are, for example on a macOS system, you can run the following command in the terminal:

xcrun clang -v -E -x objective-c /dev/null

You might also have to include the proper presets, for example:

-target arm64-apple-darwin -framework Foundation -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

In the end, the parsed result looks like this:

00000000 __objc_interface __cppobj MyClass : NSObject // sizeof=0x18
00000000 {
00000004     int _counter;
00000008     NSString *_name;
0000000C     NSString *_title;
00000010     NSInteger _value;
00000018 };

All the dependent types, such as NSString and NSInteger, will also be added to the database.

Fixed structs

Fixed layout structures can be created or edited directly in Local Types using the Declaration tab. Make sure that IDA specific extensions are not disabled in Options → Compiler → Parser specific options. By default they are enabled, so you should be good to go.

struct __fixed(0x48) x64_prologue_frame
{
  __at(0x0000) void *return_addr;
  __at(0x0008) void *saved_rbp;
  __at(0x0010) void *saved_rbx;
  __at(0x0038) int local_var1;
  __at(0x003C) int local_var2;
};

The parser UI

The Source parser setting

The clang parser is the default Source parser, as shown in the Options → Compiler dialog:

The parser can be fine-tuned using the Parser specific options button.

Apply tinfo to demangled names

If enabled, the parser will look for mangled names in the database as types are being parsed, and automatically apply the type info to the address where the name was found.

For example, if this type is parsed:

class MyService : public IOService
{
public:
  virtual IOService *probe(IOService *provider, SInt32 *score) APPLE_KEXT_OVERRIDE;
};

And the function MyService::probe() is present in the database, a more precise prototype will automatically be applied to the function:

; =============== S U B R O U T I N E =======================================
; IOService *__cdecl MyService::probe(MyService *__hidden this, IOService *provider, SInt32 *score)
                public __ZN7MyClass5probeEP9IOServicePi
__ZN7MyClass5probeEP9IOServicePi proc near

No IDA specific extensions

If enabled, the parser will not recognize IDA-specific keywords, such as _BYTE or _QWORD. This is useful if you want to parse code that uses these keywords for other purposes, such as Windows driver code.

Smart pointers

A semicolon-separated list of smart pointer template names. The parser will simplify instances of such templates to simple pointers when they are encountered in the input source.

For example, consider the OSSharedPtr template class from the XNU kernel source code:

template <typename T>
class __attribute__((trivial_abi)) OSSharedPtr: public libkern::intrusive_shared_ptr<T, intrusive_osobject_retainer> {
  using libkern::intrusive_shared_ptr<T, intrusive_osobject_retainer>::intrusive_shared_ptr;
};

Now let's say the clang parser finds an instance of this template class in the input source:

typedef OSSharedPtr<OSString> OSStringPtr;

Previously, to describe this type, the parser had to create 4 different types:

typedef OSSharedPtr<OSString> OSStringPtr;`
struct __cppobj OSSharedPtr<OSString> : libkern::intrusive_shared_ptr<OSString, intrusive_osobject_retainer> {};
struct __cppobj libkern::intrusive_shared_ptr<OSString, intrusive_osobject_retainer>
{
  libkern::intrusive_shared_ptr<OSString, intrusive_osobject_retainer>::pointer ptr_;
};
typedef OSString *libkern::intrusive_shared_ptr<OSString, intrusive_osobject_retainer>::pointer;

To avoid all that noise, you can add OSSharedPtr to the Smart pointers list, which will instruct the parser to reduce the template instances to simple pointers, simplifying the analysis:

typedef OSString *OSStringPtr;

For example, this is the configuration we use when generating the type libraries for xnu_7195_x64.til: OSPtr;OSSharedPtr;OSTaggedPtr;OSTaggedSharedPtr

Language

The language to use for parsing. This can be set to C, C++, Objective-C, or Objective-C++. Make sure to set the right flags in the Options → Compiler → Arguments field as well, for example -std=c++20 for C++20 code.

Print/Dump AST

If enabled, the parser will print the abstract syntax tree (AST) of the parsed code in the output window. This is useful for debugging purposes. Slows down the parsing process significantly.

Adding types

Go to Local Types window, right-click and select Add type. Paste the code you want to parse in the editor and click OK.

Alternatively, you can use the File → Load file → Parse C header file... option in the menu bar to parse an entire header file. Using the parser in this way is generally faster and more robust than using the Add type option, which is meant for quick parsing of small code snippets.

The parser API

It is possible to invoke the parser from IDAPython. You may want to take a look at the ida_srclang package.

Here's a simple example of how one can use the API to parse an Objective-C header file:

import ida_srclang
import idaapi
 
ida_srclang.set_parser_argv(
    "clang",
    "-x objective-c -target arm64-apple-darwin -framework Foundation -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk -ILibrary/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include"
)

idaapi.parse_decls(
    None,
    "/path/to/header.h",
    None,
    idaapi.HTI_FIL | idaapi.HTI_NWR | idaapi.HTI_LOWER | idaapi.HTI_NDC
)

TILIB

The same clang parser backend is used by TILIB, a command-line utility that generates type libraries from C/C++/Objective-C header files. See more details in the TILIB documentation.