Skip to content

Commit 3594847

Browse files
Copilotxusheng6
andcommitted
Add headless file and database loading examples to cookbook
Co-authored-by: xusheng6 <[email protected]>
1 parent 09988ea commit 3594847

File tree

1 file changed

+87
-0
lines changed

1 file changed

+87
-0
lines changed

docs/dev/cookbook.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,93 @@ One of the best ways to learn a complicated API is to simply find the right exam
1111

1212
# Recipes
1313

14+
## Loading Files & Databases
15+
16+
### Loading a file headlessly
17+
18+
The `load` function is the recommended way to open a file for analysis in a headless script:
19+
20+
```python
21+
from binaryninja import load
22+
23+
# Basic usage - automatically runs analysis
24+
bv = load('/bin/ls')
25+
if bv is not None:
26+
# Do something with the binary view
27+
print(f"Loaded {bv.file.filename}")
28+
print(f"Architecture: {bv.arch.name}")
29+
print(f"Entry point: {hex(bv.entry_point)}")
30+
31+
# Important: Close the file when done to prevent memory leaks
32+
bv.file.close()
33+
```
34+
35+
### Loading a file with options
36+
37+
You can customize the loading behavior by passing options:
38+
39+
```python
40+
from binaryninja import load
41+
42+
# Load with custom options
43+
bv = load('/bin/ls', options={
44+
'loader.imageBase': 0xfffffff0000,
45+
'loader.macho.processFunctionStarts': False,
46+
'analysis.mode': 'basic',
47+
'analysis.linearSweep.autorun': False
48+
})
49+
50+
if bv is not None:
51+
# Process the binary view
52+
print(f"Loaded at base address: {hex(bv.start)}")
53+
bv.file.close()
54+
```
55+
56+
### Loading a database file
57+
58+
Binary Ninja database files (.bndb) can be loaded the same way as regular binaries:
59+
60+
```python
61+
from binaryninja import load
62+
63+
# Load a saved database
64+
bv = load('/path/to/analysis.bndb')
65+
if bv is not None:
66+
# All previous analysis is preserved
67+
print(f"Loaded database with {len(bv.functions)} functions")
68+
bv.file.close()
69+
```
70+
71+
### Using the context manager pattern
72+
73+
The recommended way to work with Binary Ninja files is using a context manager, which automatically handles cleanup:
74+
75+
```python
76+
from binaryninja import load
77+
78+
# Context manager automatically closes the file
79+
with load('/bin/ls') as bv:
80+
if bv is not None:
81+
for func in bv.functions:
82+
print(f"{hex(func.start)}: {func.name}")
83+
# File is automatically closed here
84+
```
85+
86+
### Controlling analysis behavior
87+
88+
By default, `load()` runs analysis automatically. You can disable this for faster loading:
89+
90+
```python
91+
from binaryninja import load
92+
93+
# Load without running analysis
94+
bv = load('/bin/ls', update_analysis=False)
95+
if bv is not None:
96+
# Manually control when analysis runs
97+
bv.update_analysis_and_wait()
98+
bv.file.close()
99+
```
100+
14101
## Navigation / Search
15102

16103
### Getting all functions in a binary

0 commit comments

Comments
 (0)