1 //! "Nlist" style symbols in this binary - beware, like most symbol tables in most binary formats, they are strippable, and should not be relied upon, see the imports and exports modules for something more permanent.
2 //!
3 //! Symbols are essentially a type, offset, and the symbol name
4
5 use scroll::ctx;
6 use scroll::ctx::SizeWith;
7 use scroll::{Pread, Pwrite, SizeWith, IOread, IOwrite};
8 use crate::error;
9 use crate::container::{self, Container};
10 use crate::mach::load_command;
11 use core::fmt::{self, Debug};
12
13 // The n_type field really contains four fields which are used via the following masks.
14 /// if any of these bits set, a symbolic debugging entry
15 pub const N_STAB: u8 = 0xe0;
16 /// private external symbol bit
17 pub const N_PEXT: u8 = 0x10;
18 /// mask for the type bits
19 pub const N_TYPE: u8 = 0x0e;
20 /// external symbol bit, set for external symbols
21 pub const N_EXT: u8 = 0x01;
22
23 // If the type is N_SECT then the n_sect field contains an ordinal of the
24 // section the symbol is defined in. The sections are numbered from 1 and
25 // refer to sections in order they appear in the load commands for the file
26 // they are in. This means the same ordinal may very well refer to different
27 // sections in different files.
28
29 // The n_value field for all symbol table entries (including N_STAB's) gets
30 // updated by the link editor based on the value of it's n_sect field and where
31 // the section n_sect references gets relocated. If the value of the n_sect
32 // field is NO_SECT then it's n_value field is not changed by the link editor.
33 /// symbol is not in any section
34 pub const NO_SECT: u8 = 0;
35 /// 1 thru 255 inclusive
36 pub const MAX_SECT: u8 = 255;
37
38 /// undefined, n_sect == NO_SECT
39 pub const N_UNDF: u8 = 0x0;
40 /// absolute, n_sect == NO_SECT
41 pub const N_ABS: u8 = 0x2;
42 /// defined in section number n_sect
43 pub const N_SECT: u8 = 0xe;
44 /// prebound undefined (defined in a dylib)
45 pub const N_PBUD: u8 = 0xc;
46 /// indirect
47 pub const N_INDR: u8 = 0xa;
48
49 // n_types when N_STAB
50 pub const N_GSYM: u8 = 0x20;
51 pub const N_FNAME: u8 = 0x22;
52 pub const N_FUN: u8 = 0x24;
53 pub const N_STSYM: u8 = 0x26;
54 pub const N_LCSYM: u8 = 0x28;
55 pub const N_BNSYM: u8 = 0x2e;
56 pub const N_PC: u8 = 0x30;
57 pub const N_AST: u8 = 0x32;
58 pub const N_OPT: u8 = 0x3c;
59 pub const N_RSYM: u8 = 0x40;
60 pub const N_SLINE: u8 = 0x44;
61 pub const N_ENSYM: u8 = 0x4e;
62 pub const N_SSYM: u8 = 0x60;
63 pub const N_SO: u8 = 0x64;
64 pub const N_OSO: u8 = 0x66;
65 pub const N_LSYM: u8 = 0x80;
66 pub const N_BINCL: u8 = 0x82;
67 pub const N_SOL: u8 = 0x84;
68 pub const N_PARAMS: u8 = 0x86;
69 pub const N_VERSION: u8 = 0x88;
70 pub const N_OLEVEL: u8 = 0x8a;
71 pub const N_PSYM: u8 = 0xa0;
72 pub const N_EINCL: u8 = 0xa2;
73 pub const N_ENTRY: u8 = 0xa4;
74 pub const N_LBRAC: u8 = 0xc0;
75 pub const N_EXCL: u8 = 0xc2;
76 pub const N_RBRAC: u8 = 0xe0;
77 pub const N_BCOMM: u8 = 0xe2;
78 pub const N_ECOMM: u8 = 0xe4;
79 pub const N_ECOML: u8 = 0xe8;
80 pub const N_LENG: u8 = 0xfe;
81
82 pub const NLIST_TYPE_MASK: u8 = 0xe;
83 pub const NLIST_TYPE_GLOBAL: u8 = 0x1;
84 pub const NLIST_TYPE_LOCAL: u8 = 0x0;
85
86 /// Mask for reference flags of `n_desc` field.
87 pub const REFERENCE_TYPE: u16 = 0xf;
88 /// This symbol is a reference to an external non-lazy (data) symbol.
89 pub const REFERENCE_FLAG_UNDEFINED_NON_LAZY: u16 = 0x0;
90 /// This symbol is a reference to an external lazy symbol—that is, to a function call.
91 pub const REFERENCE_FLAG_UNDEFINED_LAZY: u16 = 0x1;
92 /// This symbol is defined in this module.
93 pub const REFERENCE_FLAG_DEFINED: u16 = 0x2;
94 /// This symbol is defined in this module and is visible only to modules within this
95 /// shared library.
96 pub const REFERENCE_FLAG_PRIVATE_DEFINED: u16 = 0x3;
97 /// This symbol is defined in another module in this file, is a non-lazy (data) symbol,
98 /// and is visible only to modules within this shared library.
99 pub const REFERENCE_FLAG_PRIVATE_UNDEFINED_NON_LAZY: u16 = 0x4;
100 /// This symbol is defined in another module in this file, is a lazy (function) symbol,
101 /// and is visible only to modules within this shared library.
102 pub const REFERENCE_FLAG_PRIVATE_UNDEFINED_LAZY: u16 = 0x5;
103
104 // Additional flags of n_desc field.
105
106 /// Must be set for any defined symbol that is referenced by dynamic-loader APIs
107 /// (such as dlsym and NSLookupSymbolInImage) and not ordinary undefined symbol
108 /// references. The `strip` tool uses this bit to avoid removing symbols that must
109 /// exist: If the symbol has this bit set, `strip` does not strip it.
110 pub const REFERENCED_DYNAMICALLY: u16 = 0x10;
111 /// Sometimes used by the dynamic linker at runtime in a fully linked image. Do not
112 /// set this bit in a fully linked image.
113 pub const N_DESC_DISCARDED: u16 = 0x20;
114 /// When set in a relocatable object file (file type MH_OBJECT) on a defined symbol,
115 /// indicates to the static linker to never dead-strip the symbol.
116 // (Note that the same bit (0x20) is used for two nonoverlapping purposes.)
117 pub const N_NO_DEAD_STRIP: u16 = 0x20;
118 /// Indicates that this undefined symbol is a weak reference. If the dynamic linker
119 /// cannot find a definition for this symbol, it sets the address of this symbol to 0.
120 /// The static linker sets this symbol given the appropriate weak-linking flags.
121 pub const N_WEAK_REF: u16 = 0x40;
122 /// Indicates that this symbol is a weak definition. If the static linker or the
123 /// dynamic linker finds another (non-weak) definition for this symbol, the weak
124 /// definition is ignored. Only symbols in a coalesced section can be marked as a
125 /// weak definition.
126 pub const N_WEAK_DEF: u16 = 0x80;
127
n_type_to_str(n_type: u8) -> &'static str128 pub fn n_type_to_str(n_type: u8) -> &'static str {
129 match n_type {
130 N_UNDF => "N_UNDF",
131 N_ABS => "N_ABS",
132 N_SECT => "N_SECT",
133 N_PBUD => "N_PBUD",
134 N_INDR => "N_INDR",
135 _ => "UNKNOWN_N_TYPE"
136 }
137 }
138
139 #[repr(C)]
140 #[derive(Clone, Copy, Pread, Pwrite, SizeWith, IOread, IOwrite)]
141 pub struct Nlist32 {
142 /// index into the string table
143 pub n_strx: u32,
144 /// type flag, see below
145 pub n_type: u8,
146 /// section number or NO_SECT
147 pub n_sect: u8,
148 /// see <mach-o/stab.h>
149 pub n_desc: u16,
150 /// value of this symbol (or stab offset)
151 pub n_value: u32,
152 }
153
154 pub const SIZEOF_NLIST_32: usize = 12;
155
156 impl Debug for Nlist32 {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result157 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
158 fmt.debug_struct("Nlist32")
159 .field("n_strx", &format_args!("{:04}", self.n_strx))
160 .field("n_type", &format_args!("{:#02x}", self.n_type))
161 .field("n_sect", &format_args!("{:#x}", self.n_sect))
162 .field("n_desc", &format_args!("{:#03x}", self.n_desc))
163 .field("n_value", &format_args!("{:#x}", self.n_value))
164 .finish()
165 }
166 }
167
168 #[repr(C)]
169 #[derive(Clone, Copy, Pread, Pwrite, SizeWith, IOread, IOwrite)]
170 pub struct Nlist64 {
171 /// index into the string table
172 pub n_strx: u32,
173 /// type flag, see below
174 pub n_type: u8,
175 /// section number or NO_SECT
176 pub n_sect: u8,
177 /// see <mach-o/stab.h>
178 pub n_desc: u16,
179 /// value of this symbol (or stab offset)
180 pub n_value: u64,
181 }
182
183 pub const SIZEOF_NLIST_64: usize = 16;
184
185 impl Debug for Nlist64 {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result186 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
187 fmt.debug_struct("Nlist64")
188 .field("n_strx", &format_args!("{:04}", self.n_strx))
189 .field("n_type", &format_args!("{:#02x}", self.n_type))
190 .field("n_sect", &format_args!("{:#x}", self.n_sect))
191 .field("n_desc", &format_args!("{:#03x}", self.n_desc))
192 .field("n_value", &format_args!("{:#x}", self.n_value))
193 .finish()
194 }
195 }
196
197 #[derive(Debug, Clone,)]
198 pub struct Nlist {
199 /// index into the string table
200 pub n_strx: usize,
201 /// type flag, see below
202 pub n_type: u8,
203 /// section number or NO_SECT
204 pub n_sect: usize,
205 /// see <mach-o/stab.h>
206 pub n_desc: u16,
207 /// value of this symbol (or stab offset)
208 pub n_value: u64,
209 }
210
211 impl Nlist {
212 /// Gets this symbol's type in bits 0xe
get_type(&self) -> u8213 pub fn get_type(&self) -> u8 {
214 self.n_type & N_TYPE
215 }
216 /// Gets the str representation of the type of this symbol
type_str(&self) -> &'static str217 pub fn type_str(&self) -> &'static str {
218 n_type_to_str(self.get_type())
219 }
220 /// Whether this symbol is global or not
is_global(&self) -> bool221 pub fn is_global(&self) -> bool {
222 self.n_type & N_EXT != 0
223 }
224 /// Whether this symbol is weak or not
is_weak(&self) -> bool225 pub fn is_weak(&self) -> bool {
226 self.n_desc & (N_WEAK_REF | N_WEAK_DEF) != 0
227 }
228 /// Whether this symbol is undefined or not
is_undefined(&self) -> bool229 pub fn is_undefined(&self) -> bool {
230 self.n_sect == 0 && self.n_type & N_TYPE == N_UNDF
231 }
232 /// Whether this symbol is a symbolic debugging entry
is_stab(&self) -> bool233 pub fn is_stab(&self) -> bool {
234 self.n_type & N_STAB != 0
235 }
236 }
237
238 impl ctx::SizeWith<container::Ctx> for Nlist {
size_with(ctx: &container::Ctx) -> usize239 fn size_with(ctx: &container::Ctx) -> usize {
240 match ctx.container {
241 Container::Little => {
242 SIZEOF_NLIST_32
243 },
244 Container::Big => {
245 SIZEOF_NLIST_64
246 },
247 }
248 }
249 }
250
251 impl From<Nlist32> for Nlist {
from(nlist: Nlist32) -> Self252 fn from(nlist: Nlist32) -> Self {
253 Nlist {
254 n_strx: nlist.n_strx as usize,
255 n_type: nlist.n_type,
256 n_sect: nlist.n_sect as usize,
257 n_desc: nlist.n_desc,
258 n_value: u64::from(nlist.n_value),
259 }
260 }
261 }
262
263 impl From<Nlist64> for Nlist {
from(nlist: Nlist64) -> Self264 fn from(nlist: Nlist64) -> Self {
265 Nlist {
266 n_strx: nlist.n_strx as usize,
267 n_type: nlist.n_type,
268 n_sect: nlist.n_sect as usize,
269 n_desc: nlist.n_desc,
270 n_value: nlist.n_value,
271 }
272 }
273 }
274
275 impl From<Nlist> for Nlist32 {
from(nlist: Nlist) -> Self276 fn from(nlist: Nlist) -> Self {
277 Nlist32 {
278 n_strx: nlist.n_strx as u32,
279 n_type: nlist.n_type,
280 n_sect: nlist.n_sect as u8,
281 n_desc: nlist.n_desc,
282 n_value: nlist.n_value as u32,
283 }
284 }
285 }
286
287 impl From<Nlist> for Nlist64 {
from(nlist: Nlist) -> Self288 fn from(nlist: Nlist) -> Self {
289 Nlist64 {
290 n_strx: nlist.n_strx as u32,
291 n_type: nlist.n_type,
292 n_sect: nlist.n_sect as u8,
293 n_desc: nlist.n_desc,
294 n_value: nlist.n_value,
295 }
296 }
297 }
298
299 impl<'a> ctx::TryFromCtx<'a, container::Ctx> for Nlist {
300 type Error = crate::error::Error;
301 fn try_from_ctx(bytes: &'a [u8], container::Ctx { container, le }: container::Ctx) -> crate::error::Result<(Self, usize)> {
302 let nlist = match container {
303 Container::Little => {
304 (bytes.pread_with::<Nlist32>(0, le)?.into(), SIZEOF_NLIST_32)
305 },
306 Container::Big => {
307 (bytes.pread_with::<Nlist64>(0, le)?.into(), SIZEOF_NLIST_64)
308 },
309 };
310 Ok(nlist)
311 }
312 }
313
314 impl ctx::TryIntoCtx<container::Ctx> for Nlist {
315 type Error = crate::error::Error;
316 fn try_into_ctx(self, bytes: &mut [u8], container::Ctx { container, le }: container::Ctx) -> Result<usize, Self::Error> {
317 let size = match container {
318 Container::Little => {
319 (bytes.pwrite_with::<Nlist32>(self.into(), 0, le)?)
320 },
321 Container::Big => {
322 (bytes.pwrite_with::<Nlist64>(self.into(), 0, le)?)
323 },
324 };
325 Ok(size)
326 }
327 }
328
329 impl ctx::IntoCtx<container::Ctx> for Nlist {
into_ctx(self, bytes: &mut [u8], ctx: container::Ctx)330 fn into_ctx(self, bytes: &mut [u8], ctx: container::Ctx) {
331 bytes.pwrite_with(self, 0, ctx).unwrap();
332 }
333 }
334
335 #[derive(Debug, Clone, Copy, Default)]
336 pub struct SymbolsCtx {
337 pub nsyms: usize,
338 pub strtab: usize,
339 pub ctx: container::Ctx,
340 }
341
342 impl<'a, T: ?Sized> ctx::TryFromCtx<'a, SymbolsCtx, T> for Symbols<'a> where T: AsRef<[u8]> {
343 type Error = crate::error::Error;
344 fn try_from_ctx(bytes: &'a T, SymbolsCtx {
345 nsyms, strtab, ctx
346 }: SymbolsCtx) -> crate::error::Result<(Self, usize)> {
347 let data = bytes.as_ref();
348 Ok ((Symbols {
349 data,
350 start: 0,
351 nsyms,
352 strtab,
353 ctx,
354 }, data.len()))
355 }
356 }
357
358 #[derive(Default)]
359 pub struct SymbolIterator<'a> {
360 data: &'a [u8],
361 nsyms: usize,
362 offset: usize,
363 count: usize,
364 ctx: container::Ctx,
365 strtab: usize,
366 }
367
368 impl<'a> Iterator for SymbolIterator<'a> {
369 type Item = error::Result<(&'a str, Nlist)>;
next(&mut self) -> Option<Self::Item>370 fn next(&mut self) -> Option<Self::Item> {
371 if self.count >= self.nsyms {
372 None
373 } else {
374 self.count += 1;
375 match self.data.gread_with::<Nlist>(&mut self.offset, self.ctx) {
376 Ok(symbol) => {
377 match self.data.pread(self.strtab + symbol.n_strx) {
378 Ok(name) => {
379 Some(Ok((name, symbol)))
380 },
381 Err(e) => Some(Err(e.into()))
382 }
383 },
384 Err(e) => Some(Err(e))
385 }
386 }
387 }
388 }
389
390 /// A zero-copy "nlist" style symbol table ("stab"), including the string table
391 pub struct Symbols<'a> {
392 data: &'a [u8],
393 start: usize,
394 nsyms: usize,
395 // TODO: we can use an actual strtab here and tie it to symbols lifetime
396 strtab: usize,
397 ctx: container::Ctx,
398 }
399
400 impl<'a, 'b> IntoIterator for &'b Symbols<'a> {
401 type Item = <SymbolIterator<'a> as Iterator>::Item;
402 type IntoIter = SymbolIterator<'a>;
into_iter(self) -> Self::IntoIter403 fn into_iter(self) -> Self::IntoIter {
404 self.iter()
405 }
406 }
407
408 impl<'a> Symbols<'a> {
409 /// Creates a new symbol table with `count` elements, from the `start` offset, using the string table at `strtab`, with a _default_ ctx.
410 ////
411 /// **Beware**, this will provide incorrect results if you construct this on a 32-bit mach binary, using a 64-bit machine; use `parse` instead if you want 32/64 bit support
new(bytes: &'a [u8], start: usize, count: usize, strtab: usize) -> error::Result<Symbols<'a>>412 pub fn new(bytes: &'a [u8], start: usize, count: usize, strtab: usize) -> error::Result<Symbols<'a>> {
413 let nsyms = count;
414 Ok (Symbols {
415 data: bytes,
416 start,
417 nsyms,
418 strtab,
419 ctx: container::Ctx::default(),
420 })
421 }
parse(bytes: &'a [u8], symtab: &load_command::SymtabCommand, ctx: container::Ctx) -> error::Result<Symbols<'a>>422 pub fn parse(bytes: &'a [u8], symtab: &load_command::SymtabCommand, ctx: container::Ctx) -> error::Result<Symbols<'a>> {
423 // we need to normalize the strtab offset before we receive the truncated bytes in pread_with
424 let strtab = symtab.stroff - symtab.symoff;
425 Ok(bytes.pread_with(symtab.symoff as usize, SymbolsCtx { nsyms: symtab.nsyms as usize, strtab: strtab as usize, ctx })?)
426 }
427
iter(&self) -> SymbolIterator<'a>428 pub fn iter(&self) -> SymbolIterator<'a> {
429 SymbolIterator {
430 offset: self.start as usize,
431 nsyms: self.nsyms as usize,
432 count: 0,
433 data: self.data,
434 ctx: self.ctx,
435 strtab: self.strtab,
436 }
437 }
438
439 /// Parses a single Nlist symbol from the binary, with its accompanying name
get(&self, index: usize) -> crate::error::Result<(&'a str, Nlist)>440 pub fn get(&self, index: usize) -> crate::error::Result<(&'a str, Nlist)> {
441 let sym: Nlist = self.data.pread_with(self.start + (index * Nlist::size_with(&self.ctx)), self.ctx)?;
442 let name = self.data.pread(self.strtab + sym.n_strx)?;
443 Ok((name, sym))
444 }
445 }
446
447 impl<'a> Debug for Symbols<'a> {
fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result448 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
449 fmt.debug_struct("Symbols")
450 .field("data", &self.data.len())
451 .field("start", &format_args!("{:#?}", self.start))
452 .field("nsyms", &self.nsyms)
453 .field("strtab", &format_args!("{:#x}", self.strtab))
454 .finish()?;
455
456 writeln!(fmt, "Symbol List {{")?;
457 for (i, res) in self.iter().enumerate() {
458 match res {
459 Ok((name, nlist)) => writeln!(
460 fmt,
461 "{: >10x} {} sect: {:#x} type: {:#02x} desc: {:#03x}",
462 nlist.n_value, name, nlist.n_sect, nlist.n_type, nlist.n_desc
463 )?,
464 Err(error) => writeln!(fmt, " Bad symbol, index: {}, sym: {:?}", i, error)?,
465 }
466 }
467 writeln!(fmt, "}}")
468 }
469 }
470