1use alloc::vec::Vec;
2use core::fmt::Debug;
3use core::{fmt, slice, str};
4
5use crate::endian::{self, Endianness};
6use crate::macho;
7use crate::pod::Pod;
8use crate::read::util::StringTable;
9use crate::read::{
10 self, ObjectMap, ObjectMapEntry, ObjectMapFile, ObjectSymbol, ObjectSymbolTable, ReadError,
11 ReadRef, Result, SectionIndex, SectionKind, SymbolFlags, SymbolIndex, SymbolKind, SymbolMap,
12 SymbolMapEntry, SymbolScope, SymbolSection,
13};
14
15use super::{MachHeader, MachOFile};
16
17/// A table of symbol entries in a Mach-O file.
18///
19/// Also includes the string table used for the symbol names.
20///
21/// Returned by [`macho::SymtabCommand::symbols`].
22#[derive(Debug, Clone, Copy)]
23pub struct SymbolTable<'data, Mach: MachHeader, R = &'data [u8]>
24where
25 R: ReadRef<'data>,
26{
27 symbols: &'data [Mach::Nlist],
28 strings: StringTable<'data, R>,
29}
30
31impl<'data, Mach: MachHeader, R: ReadRef<'data>> Default for SymbolTable<'data, Mach, R> {
32 fn default() -> Self {
33 SymbolTable {
34 symbols: &[],
35 strings: Default::default(),
36 }
37 }
38}
39
40impl<'data, Mach: MachHeader, R: ReadRef<'data>> SymbolTable<'data, Mach, R> {
41 #[inline]
42 pub(super) fn new(symbols: &'data [Mach::Nlist], strings: StringTable<'data, R>) -> Self {
43 SymbolTable { symbols, strings }
44 }
45
46 /// Return the string table used for the symbol names.
47 #[inline]
48 pub fn strings(&self) -> StringTable<'data, R> {
49 self.strings
50 }
51
52 /// Iterate over the symbols.
53 #[inline]
54 pub fn iter(&self) -> slice::Iter<'data, Mach::Nlist> {
55 self.symbols.iter()
56 }
57
58 /// Return true if the symbol table is empty.
59 #[inline]
60 pub fn is_empty(&self) -> bool {
61 self.symbols.is_empty()
62 }
63
64 /// The number of symbols.
65 #[inline]
66 pub fn len(&self) -> usize {
67 self.symbols.len()
68 }
69
70 /// Return the symbol at the given index.
71 pub fn symbol(&self, index: SymbolIndex) -> Result<&'data Mach::Nlist> {
72 self.symbols
73 .get(index.0)
74 .read_error("Invalid Mach-O symbol index")
75 }
76
77 /// Construct a map from addresses to a user-defined map entry.
78 pub fn map<Entry: SymbolMapEntry, F: Fn(&'data Mach::Nlist) -> Option<Entry>>(
79 &self,
80 f: F,
81 ) -> SymbolMap<Entry> {
82 let mut symbols = Vec::new();
83 for nlist in self.symbols {
84 if !nlist.is_definition() {
85 continue;
86 }
87 if let Some(entry) = f(nlist) {
88 symbols.push(entry);
89 }
90 }
91 SymbolMap::new(symbols)
92 }
93
94 /// Construct a map from addresses to symbol names and object file names.
95 pub fn object_map(&self, endian: Mach::Endian) -> ObjectMap<'data> {
96 let mut symbols = Vec::new();
97 let mut objects = Vec::new();
98 let mut object = None;
99 let mut current_function = None;
100 // Each module starts with one or two N_SO symbols (path, or directory + filename)
101 // and one N_OSO symbol. The module is terminated by an empty N_SO symbol.
102 for nlist in self.symbols {
103 let n_type = nlist.n_type();
104 if n_type & macho::N_STAB == 0 {
105 continue;
106 }
107 // TODO: includes variables too (N_GSYM, N_STSYM). These may need to get their
108 // address from regular symbols though.
109 match n_type {
110 macho::N_SO => {
111 object = None;
112 }
113 macho::N_OSO => {
114 object = None;
115 if let Ok(name) = nlist.name(endian, self.strings) {
116 if !name.is_empty() {
117 object = Some(objects.len());
118 // `N_OSO` symbol names can be either `/path/to/object.o`
119 // or `/path/to/archive.a(object.o)`.
120 let (path, member) = name
121 .split_last()
122 .and_then(|(last, head)| {
123 if *last != b')' {
124 return None;
125 }
126 let index = head.iter().position(|&x| x == b'(')?;
127 let (archive, rest) = head.split_at(index);
128 Some((archive, Some(&rest[1..])))
129 })
130 .unwrap_or((name, None));
131 objects.push(ObjectMapFile::new(path, member));
132 }
133 }
134 }
135 macho::N_FUN => {
136 if let Ok(name) = nlist.name(endian, self.strings) {
137 if !name.is_empty() {
138 current_function = Some((name, nlist.n_value(endian).into()))
139 } else if let Some((name, address)) = current_function.take() {
140 if let Some(object) = object {
141 symbols.push(ObjectMapEntry {
142 address,
143 size: nlist.n_value(endian).into(),
144 name,
145 object,
146 });
147 }
148 }
149 }
150 }
151 _ => {}
152 }
153 }
154 ObjectMap {
155 symbols: SymbolMap::new(symbols),
156 objects,
157 }
158 }
159}
160
161/// A symbol table in a [`MachOFile32`](super::MachOFile32).
162pub type MachOSymbolTable32<'data, 'file, Endian = Endianness, R = &'data [u8]> =
163 MachOSymbolTable<'data, 'file, macho::MachHeader32<Endian>, R>;
164/// A symbol table in a [`MachOFile64`](super::MachOFile64).
165pub type MachOSymbolTable64<'data, 'file, Endian = Endianness, R = &'data [u8]> =
166 MachOSymbolTable<'data, 'file, macho::MachHeader64<Endian>, R>;
167
168/// A symbol table in a [`MachOFile`].
169#[derive(Debug, Clone, Copy)]
170pub struct MachOSymbolTable<'data, 'file, Mach, R = &'data [u8]>
171where
172 Mach: MachHeader,
173 R: ReadRef<'data>,
174{
175 pub(super) file: &'file MachOFile<'data, Mach, R>,
176}
177
178impl<'data, 'file, Mach, R> read::private::Sealed for MachOSymbolTable<'data, 'file, Mach, R>
179where
180 Mach: MachHeader,
181 R: ReadRef<'data>,
182{
183}
184
185impl<'data, 'file, Mach, R> ObjectSymbolTable<'data> for MachOSymbolTable<'data, 'file, Mach, R>
186where
187 Mach: MachHeader,
188 R: ReadRef<'data>,
189{
190 type Symbol = MachOSymbol<'data, 'file, Mach, R>;
191 type SymbolIterator = MachOSymbolIterator<'data, 'file, Mach, R>;
192
193 fn symbols(&self) -> Self::SymbolIterator {
194 MachOSymbolIterator::new(self.file)
195 }
196
197 fn symbol_by_index(&self, index: SymbolIndex) -> Result<Self::Symbol> {
198 let nlist: &'data ::Nlist = self.file.symbols.symbol(index)?;
199 MachOSymbol::new(self.file, index, nlist).read_error("Unsupported Mach-O symbol index")
200 }
201}
202
203/// An iterator for the symbols in a [`MachOFile32`](super::MachOFile32).
204pub type MachOSymbolIterator32<'data, 'file, Endian = Endianness, R = &'data [u8]> =
205 MachOSymbolIterator<'data, 'file, macho::MachHeader32<Endian>, R>;
206/// An iterator for the symbols in a [`MachOFile64`](super::MachOFile64).
207pub type MachOSymbolIterator64<'data, 'file, Endian = Endianness, R = &'data [u8]> =
208 MachOSymbolIterator<'data, 'file, macho::MachHeader64<Endian>, R>;
209
210/// An iterator for the symbols in a [`MachOFile`].
211pub struct MachOSymbolIterator<'data, 'file, Mach, R = &'data [u8]>
212where
213 Mach: MachHeader,
214 R: ReadRef<'data>,
215{
216 file: &'file MachOFile<'data, Mach, R>,
217 index: SymbolIndex,
218}
219
220impl<'data, 'file, Mach, R> MachOSymbolIterator<'data, 'file, Mach, R>
221where
222 Mach: MachHeader,
223 R: ReadRef<'data>,
224{
225 pub(super) fn new(file: &'file MachOFile<'data, Mach, R>) -> Self {
226 MachOSymbolIterator {
227 file,
228 index: SymbolIndex(0),
229 }
230 }
231
232 pub(super) fn empty(file: &'file MachOFile<'data, Mach, R>) -> Self {
233 MachOSymbolIterator {
234 file,
235 index: SymbolIndex(file.symbols.len()),
236 }
237 }
238}
239
240impl<'data, 'file, Mach, R> fmt::Debug for MachOSymbolIterator<'data, 'file, Mach, R>
241where
242 Mach: MachHeader,
243 R: ReadRef<'data>,
244{
245 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
246 f.debug_struct(name:"MachOSymbolIterator").finish()
247 }
248}
249
250impl<'data, 'file, Mach, R> Iterator for MachOSymbolIterator<'data, 'file, Mach, R>
251where
252 Mach: MachHeader,
253 R: ReadRef<'data>,
254{
255 type Item = MachOSymbol<'data, 'file, Mach, R>;
256
257 fn next(&mut self) -> Option<Self::Item> {
258 loop {
259 let index: SymbolIndex = self.index;
260 let nlist: &::Nlist = self.file.symbols.symbols.get(index.0)?;
261 self.index.0 += 1;
262 if let Some(symbol: MachOSymbol<'_, '_, Mach, …>) = MachOSymbol::new(self.file, index, nlist) {
263 return Some(symbol);
264 }
265 }
266 }
267}
268
269/// A symbol in a [`MachOFile32`](super::MachOFile32).
270pub type MachOSymbol32<'data, 'file, Endian = Endianness, R = &'data [u8]> =
271 MachOSymbol<'data, 'file, macho::MachHeader32<Endian>, R>;
272/// A symbol in a [`MachOFile64`](super::MachOFile64).
273pub type MachOSymbol64<'data, 'file, Endian = Endianness, R = &'data [u8]> =
274 MachOSymbol<'data, 'file, macho::MachHeader64<Endian>, R>;
275
276/// A symbol in a [`MachOFile`].
277///
278/// Most functionality is provided by the [`ObjectSymbol`] trait implementation.
279#[derive(Debug, Clone, Copy)]
280pub struct MachOSymbol<'data, 'file, Mach, R = &'data [u8]>
281where
282 Mach: MachHeader,
283 R: ReadRef<'data>,
284{
285 file: &'file MachOFile<'data, Mach, R>,
286 index: SymbolIndex,
287 nlist: &'data Mach::Nlist,
288}
289
290impl<'data, 'file, Mach, R> MachOSymbol<'data, 'file, Mach, R>
291where
292 Mach: MachHeader,
293 R: ReadRef<'data>,
294{
295 pub(super) fn new(
296 file: &'file MachOFile<'data, Mach, R>,
297 index: SymbolIndex,
298 nlist: &'data Mach::Nlist,
299 ) -> Option<Self> {
300 if nlist.n_type() & macho::N_STAB != 0 {
301 return None;
302 }
303 Some(MachOSymbol { file, index, nlist })
304 }
305
306 /// Get the Mach-O file containing this symbol.
307 pub fn macho_file(&self) -> &'file MachOFile<'data, Mach, R> {
308 self.file
309 }
310
311 /// Get the raw Mach-O symbol structure.
312 pub fn macho_symbol(&self) -> &'data Mach::Nlist {
313 self.nlist
314 }
315}
316
317impl<'data, 'file, Mach, R> read::private::Sealed for MachOSymbol<'data, 'file, Mach, R>
318where
319 Mach: MachHeader,
320 R: ReadRef<'data>,
321{
322}
323
324impl<'data, 'file, Mach, R> ObjectSymbol<'data> for MachOSymbol<'data, 'file, Mach, R>
325where
326 Mach: MachHeader,
327 R: ReadRef<'data>,
328{
329 #[inline]
330 fn index(&self) -> SymbolIndex {
331 self.index
332 }
333
334 fn name_bytes(&self) -> Result<&'data [u8]> {
335 self.nlist.name(self.file.endian, self.file.symbols.strings)
336 }
337
338 fn name(&self) -> Result<&'data str> {
339 let name = self.name_bytes()?;
340 str::from_utf8(name)
341 .ok()
342 .read_error("Non UTF-8 Mach-O symbol name")
343 }
344
345 #[inline]
346 fn address(&self) -> u64 {
347 self.nlist.n_value(self.file.endian).into()
348 }
349
350 #[inline]
351 fn size(&self) -> u64 {
352 0
353 }
354
355 fn kind(&self) -> SymbolKind {
356 self.section()
357 .index()
358 .and_then(|index| self.file.section_internal(index).ok())
359 .map(|section| match section.kind {
360 SectionKind::Text => SymbolKind::Text,
361 SectionKind::Data
362 | SectionKind::ReadOnlyData
363 | SectionKind::ReadOnlyString
364 | SectionKind::UninitializedData
365 | SectionKind::Common => SymbolKind::Data,
366 SectionKind::Tls | SectionKind::UninitializedTls | SectionKind::TlsVariables => {
367 SymbolKind::Tls
368 }
369 _ => SymbolKind::Unknown,
370 })
371 .unwrap_or(SymbolKind::Unknown)
372 }
373
374 fn section(&self) -> SymbolSection {
375 match self.nlist.n_type() & macho::N_TYPE {
376 macho::N_UNDF => SymbolSection::Undefined,
377 macho::N_ABS => SymbolSection::Absolute,
378 macho::N_SECT => {
379 let n_sect = self.nlist.n_sect();
380 if n_sect != 0 {
381 SymbolSection::Section(SectionIndex(n_sect as usize))
382 } else {
383 SymbolSection::Unknown
384 }
385 }
386 _ => SymbolSection::Unknown,
387 }
388 }
389
390 #[inline]
391 fn is_undefined(&self) -> bool {
392 self.nlist.n_type() & macho::N_TYPE == macho::N_UNDF
393 }
394
395 #[inline]
396 fn is_definition(&self) -> bool {
397 self.nlist.is_definition()
398 }
399
400 #[inline]
401 fn is_common(&self) -> bool {
402 // Mach-O common symbols are based on section, not symbol
403 false
404 }
405
406 #[inline]
407 fn is_weak(&self) -> bool {
408 self.nlist.n_desc(self.file.endian) & (macho::N_WEAK_REF | macho::N_WEAK_DEF) != 0
409 }
410
411 fn scope(&self) -> SymbolScope {
412 let n_type = self.nlist.n_type();
413 if n_type & macho::N_TYPE == macho::N_UNDF {
414 SymbolScope::Unknown
415 } else if n_type & macho::N_EXT == 0 {
416 SymbolScope::Compilation
417 } else if n_type & macho::N_PEXT != 0 {
418 SymbolScope::Linkage
419 } else {
420 SymbolScope::Dynamic
421 }
422 }
423
424 #[inline]
425 fn is_global(&self) -> bool {
426 self.scope() != SymbolScope::Compilation
427 }
428
429 #[inline]
430 fn is_local(&self) -> bool {
431 self.scope() == SymbolScope::Compilation
432 }
433
434 #[inline]
435 fn flags(&self) -> SymbolFlags<SectionIndex, SymbolIndex> {
436 let n_desc = self.nlist.n_desc(self.file.endian);
437 SymbolFlags::MachO { n_desc }
438 }
439}
440
441/// A trait for generic access to [`macho::Nlist32`] and [`macho::Nlist64`].
442#[allow(missing_docs)]
443pub trait Nlist: Debug + Pod {
444 type Word: Into<u64>;
445 type Endian: endian::Endian;
446
447 fn n_strx(&self, endian: Self::Endian) -> u32;
448 fn n_type(&self) -> u8;
449 fn n_sect(&self) -> u8;
450 fn n_desc(&self, endian: Self::Endian) -> u16;
451 fn n_value(&self, endian: Self::Endian) -> Self::Word;
452
453 fn name<'data, R: ReadRef<'data>>(
454 &self,
455 endian: Self::Endian,
456 strings: StringTable<'data, R>,
457 ) -> Result<&'data [u8]> {
458 strings
459 .get(self.n_strx(endian))
460 .read_error("Invalid Mach-O symbol name offset")
461 }
462
463 /// Return true if this is a STAB symbol.
464 ///
465 /// This determines the meaning of the `n_type` field.
466 fn is_stab(&self) -> bool {
467 self.n_type() & macho::N_STAB != 0
468 }
469
470 /// Return true if this is an undefined symbol.
471 fn is_undefined(&self) -> bool {
472 let n_type = self.n_type();
473 n_type & macho::N_STAB == 0 && n_type & macho::N_TYPE == macho::N_UNDF
474 }
475
476 /// Return true if the symbol is a definition of a function or data object.
477 fn is_definition(&self) -> bool {
478 let n_type = self.n_type();
479 n_type & macho::N_STAB == 0 && n_type & macho::N_TYPE == macho::N_SECT
480 }
481
482 /// Return the library ordinal.
483 ///
484 /// This is either a 1-based index into the dylib load commands,
485 /// or a special ordinal.
486 #[inline]
487 fn library_ordinal(&self, endian: Self::Endian) -> u8 {
488 (self.n_desc(endian) >> 8) as u8
489 }
490}
491
492impl<Endian: endian::Endian> Nlist for macho::Nlist32<Endian> {
493 type Word = u32;
494 type Endian = Endian;
495
496 fn n_strx(&self, endian: Self::Endian) -> u32 {
497 self.n_strx.get(endian)
498 }
499 fn n_type(&self) -> u8 {
500 self.n_type
501 }
502 fn n_sect(&self) -> u8 {
503 self.n_sect
504 }
505 fn n_desc(&self, endian: Self::Endian) -> u16 {
506 self.n_desc.get(endian)
507 }
508 fn n_value(&self, endian: Self::Endian) -> Self::Word {
509 self.n_value.get(endian)
510 }
511}
512
513impl<Endian: endian::Endian> Nlist for macho::Nlist64<Endian> {
514 type Word = u64;
515 type Endian = Endian;
516
517 fn n_strx(&self, endian: Self::Endian) -> u32 {
518 self.n_strx.get(endian)
519 }
520 fn n_type(&self) -> u8 {
521 self.n_type
522 }
523 fn n_sect(&self) -> u8 {
524 self.n_sect
525 }
526 fn n_desc(&self, endian: Self::Endian) -> u16 {
527 self.n_desc.get(endian)
528 }
529 fn n_value(&self, endian: Self::Endian) -> Self::Word {
530 self.n_value.get(endian)
531 }
532}
533