idalib/
lib.rs

1//! # idalib
2//!
3//! idalib is a Rust library providing idiomatic bindings for the IDA SDK, enabling the development
4//! of standalone analysis tools using IDA v9.x’s idalib.
5//!
6//! ## Usage
7//!
8//! To use idalib, add it as a dependency in your `Cargo.toml` and include a `build.rs` file in
9//! your project to properly link against IDA:
10//!
11//! ```toml
12//! [dependencies]
13//! idalib = "0.10"
14//!
15//! [build-dependencies]
16//! idalib-build = "0.10"
17//! ```
18//!
19//! Here is a basic example of a `build.rs` file:
20//!
21//! ```rust,ignore
22//! fn main() -> Result<(), Box<dyn std::error::Error>> {
23//!     idalib_build::configure_linkage()?;
24//!     Ok(())
25//! }
26//! ```
27//!
28//! This script uses the `idalib-build` crate to automatically configure the linkage against IDA.
29//! If IDA is installed in a non-default location, ensure that `IDADIR` is set to point to your
30//! installation directory, if you are linking against IDA's shared libraries, as opposed to the
31//! stub libraries distributed with the SDK.
32//!
33//! ## Setting Environment Variables
34//!
35//! ### On Linux/macOS
36//!
37//! You can set the environment variables in your terminal session or add them to your shell
38//! configuration file (e.g., `.bashrc`, `.zshrc`):
39//!
40//! ```sh,ignore
41//! export IDADIR=/path/to/ida/installation
42//! ```
43//!
44//! ### On Windows
45//!
46//! Set environment variables using Command Prompt, PowerShell, or System Properties.
47//!
48//! **Command Prompt:**
49//! ```cmd
50//! set IDADIR=C:\path\to\ida\installation
51//! ```
52//!
53//! **PowerShell:**
54//! ```powershell,ignore
55//! $env:IDADIR = "C:\path\to\ida\installation"
56//! ```
57//!
58//! **System Properties:**
59//! Go to "Environment Variables" in System Properties and add `IDADIR`.
60//!
61//! ## Example
62//!
63//! Here's a simple example of how to use idalib:
64//!
65//! ```rust,ignore
66//! use idalib::idb::IDB;
67//!
68//! fn main() -> Result<(), Box<dyn std::error::Error>> {
69//!     let idb = IDB::open("/path/to/binary")?;
70//!     // Perform analysis...
71//!     Ok(())
72//! }
73//! ```
74//!
75#![allow(clippy::needless_lifetimes)]
76
77use std::marker::PhantomData;
78use std::sync::{Mutex, MutexGuard, OnceLock};
79
80pub mod bookmarks;
81pub mod decompiler;
82pub mod func;
83pub mod idb;
84pub mod insn;
85pub mod license;
86pub mod meta;
87pub mod name;
88pub mod plugin;
89pub mod processor;
90pub mod segment;
91pub mod strings;
92pub mod typeinf;
93pub mod xref;
94
95pub use idalib_sys as ffi;
96
97pub use ffi::IDAError;
98pub use idb::IDB;
99#[cfg(not(feature = "plugin"))]
100pub use idb::IDBOpenOptions;
101pub use license::{LicenseId, is_valid_license, license_id};
102#[cfg(feature = "plugin")]
103pub use plugin::{IDAPlugin, PluginFlags};
104
105#[cfg(feature = "plugin")]
106pub use idalib_macros::plugin;
107
108pub type Address = u64;
109pub struct AddressFlags<'a> {
110    flags: ffi::bytes::flags64_t,
111    _marker: PhantomData<&'a IDB>,
112}
113
114impl<'a> AddressFlags<'a> {
115    pub(crate) fn new(flags: ffi::bytes::flags64_t) -> Self {
116        Self {
117            flags,
118            _marker: PhantomData,
119        }
120    }
121
122    pub fn is_code(&self) -> bool {
123        unsafe { ffi::bytes::is_code(self.flags) }
124    }
125
126    pub fn is_data(&self) -> bool {
127        unsafe { ffi::bytes::is_data(self.flags) }
128    }
129}
130
131pub struct IDA;
132
133impl IDA {
134    pub fn new(_: &IDB) -> Self {
135        // NOTE: we take the IDB as an argument to ensure that the caller has access to it,
136        // therefore ensuring the library is correctly initialised.
137        Self
138    }
139
140    pub fn msg(&self, message: impl AsRef<str>) -> Result<(), IDAError> {
141        unsafe { ffi::ida::msg(message) }
142    }
143}
144
145#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
146pub struct IDAVersion {
147    major: i32,
148    minor: i32,
149    build: i32,
150}
151
152impl IDAVersion {
153    pub fn major(&self) -> i32 {
154        self.major
155    }
156
157    pub fn minor(&self) -> i32 {
158        self.minor
159    }
160
161    pub fn build(&self) -> i32 {
162        self.build
163    }
164}
165
166static INIT: OnceLock<Mutex<()>> = OnceLock::new();
167
168#[cfg(not(any(target_os = "windows", feature = "plugin")))]
169unsafe extern "C" {
170    static mut batch: std::ffi::c_char;
171}
172
173pub(crate) type IDARuntimeHandle = MutexGuard<'static, ()>;
174
175#[cfg(not(feature = "plugin"))]
176pub fn force_batch_mode() {
177    #[cfg(not(target_os = "windows"))]
178    unsafe {
179        batch = 1;
180    }
181}
182
183#[cfg(feature = "plugin")]
184pub fn init_library() -> &'static Mutex<()> {
185    INIT.get_or_init(|| Mutex::new(()))
186}
187
188#[cfg(not(feature = "plugin"))]
189pub fn init_library() -> &'static Mutex<()> {
190    INIT.get_or_init(|| {
191        force_batch_mode();
192        ffi::ida::init_library().expect("IDA initialised successfully");
193        Mutex::new(())
194    })
195}
196
197pub(crate) fn prepare_library() -> IDARuntimeHandle {
198    let mutex = init_library();
199    mutex.lock().unwrap()
200}
201
202#[cfg(not(feature = "plugin"))]
203pub fn enable_console_messages(enabled: bool) {
204    init_library();
205    ffi::ida::enable_console_messages(enabled);
206}
207
208pub fn version() -> Result<IDAVersion, IDAError> {
209    ffi::ida::library_version().map(|(major, minor, build)| IDAVersion {
210        major,
211        minor,
212        build,
213    })
214}
idalib/lib.rs

idalib/
lib.rs
