atosl 0.1.14

A partial replacement for Apple's atos tool for converting binary addresses to symbols.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# atosl-rs

<div align="center">

[![Crates.io](https://img.shields.io/crates/v/atosl.svg?style=flat-square&color=EA5312)](https://crates.io/crates/atosl)
[![Docs.rs](https://img.shields.io/docsrs/atosl?style=flat-square&color=2E8555)](https://docs.rs/crate/atosl)
[![GitHub Stars](https://img.shields.io/github/stars/everettjf/atosl-rs?style=flat-square&color=FF6B6B)](https://github.com/everettjf/atosl-rs/stargazers)
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-1.60+-orange?style=flat-square&logo=rust)](https://www.rust-lang.org)

A practical Rust CLI for symbolication.  
`atosl` resolves memory addresses to function names and source locations from binaries with symbols/DWARF.

</div>

## Why atosl

Apple's `atos` is handy, but not always available or convenient in cross-platform workflows.  
`atosl` provides a lightweight alternative for address-to-symbol resolution with a simple CLI.

## Features

- Resolve one or more addresses to symbols
- Use Mach-O symbol table and DWARF debug info
- Support file-offset mode (`-f`)
- Select architecture/UUID for fat Mach-O binaries
- Verbose mode for debugging symbolication failures
- Works with Rust-supported platforms (tooling/build environment dependent)

## Installation

### From crates.io

```bash
cargo install atosl
```

### From source

```bash
git clone https://github.com/everettjf/atosl-rs.git
cd atosl-rs
cargo build --release
```

Binary path:

```bash
./target/release/atosl
```

## Quick Start

```bash
atosl -o MyApp.app/MyApp -l 0x100000000 0x100001234
```

Output shape:

```text
<symbol> (in <binary>) (<file>:<line>)
```

## Usage

```bash
atosl [OPTIONS] -o <OBJECT_PATH> -l <LOAD_ADDRESS> [ADDRESSES]...
```

Required arguments:

- `-o <OBJECT_PATH>`: binary or symbol file path
- `-l <LOAD_ADDRESS>`: load address (`0x...` hex or decimal)
- `[ADDRESSES]...`: one or more addresses to symbolize

Options:

- `-f`: treat addresses as file offsets
- `-v`: verbose diagnostics
- `-a, --arch <ARCH>`: choose architecture in fat Mach-O (`arm64`, `arm64e`, `armv7`, `x86_64`, `i386`, ...)
- `--uuid <UUID>`: choose Mach-O slice by UUID (with or without hyphens)

## Examples

Resolve multiple addresses:

```bash
atosl -o MyApp.app/MyApp -l 0x100000000 0x100001234 0x100005678
```

Use file-offset mode:

```bash
atosl -f -o MyApp.app/MyApp -l 0x0 0x1234
```

Select a fat Mach-O slice by architecture:

```bash
atosl -o Flutter -l 0x100000000 -a arm64 0x100001234
```

Select a fat Mach-O slice by UUID:

```bash
atosl -o Flutter -l 0x100000000 --uuid 34FBD46D-4A1F-3B41-A0F1-4E57D7E25B04 0x100001234
```

## Troubleshooting

- `N/A - no symbols`: binary may be stripped or missing debug sections
- Unexpected source location: verify the load address is correct for the running image
- Wrong symbol on fat binaries: specify `--arch` or `--uuid` explicitly

## Development

```bash
cargo check
cargo build
cargo build --release
cargo fmt
cargo clippy -- -D warnings
```

## Known Limitations

- Not a full 1:1 clone of Apple's `atos`
- Final accuracy depends on symbol and DWARF quality in the input binary

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/atosl-rs&type=Date)](https://star-history.com/#everettjf/atosl-rs&Date)

## Contributing

Issues and pull requests are welcome.

## License

MIT. See `LICENSE`.