MACH-SYMBOL(3)

🦋 MACH-SYMBOL(3) 🦋

okay so real talk, this page is from the Library Functions Manual, and it's literally the whole guide to the symbol-table-access girlies. there are like nineteen functions on here and we're gonna get through all of them together, no skipping, no cap 💖

---

✨ NAME ✨

symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym, flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, pc2file, file2pc, line2pc, fnbound, fileline, pc2line — symbol table access functions 🎀

like, all of them. the whole friend group.

---

🌸 SYNOPSIS 🌸

#include <u.h>
#include <libc.h>
#include <mach.h>

int     symopen(Fhdr *hdr)
void    symclose(Fhdr *hdr)
Fhdr    *findhdr(char *name)
extern  Fhdr* fhdrlist;

int     indexsym(uint n, Symbol *s)
int     lookupsym(char *fn, char *var, Symbol *s)
int     findsym(Loc loc, uint class, Symbol *s)

int     findexsym(Fhdr *hdr, uint n, Symbol *s)
Symbol  *flookupsym(Fhdr *hdr, char *name)
Symbol  *ffindsym(Fhdr *hdr, Loc loc, uint class)

int     indexlsym(Symbol *s1, uint n, Symbol *s2)
int     lookuplsym(Symbol *s1, char *name, Symbol *s2)
int     findlsym(Symbol *s1, Loc loc, Symbol *s2)

int     symoff(char *a, uint n, ulong addr, uint class)

int     pc2file(ulong pc, char *file, uint n, ulong *line)
int     pc2line(ulong pc, ulong *line)
int     fileline(ulong pc, char *buf, uint n)
int     file2pc(char *file, ulong line, ulong *pc)
int     line2pc(ulong basepc, ulong line, ulong *pc)
int     fnbound(ulong pc, ulong bounds[2])

---

💜 DESCRIPTION 💜

okay so these functions give you machine-independent access to the symbol table of an executable file or a currently-executing process. it's giving universal translator energy. and heads up: mach(3), mach-file(3) and mach-map(3) describe even more library functions for getting at executable files and running processes, so if you don't see what you need here, check those 👑

symopen uses the data in the Fhdr structure filled by crackhdr (peep mach-file(3) for that one) to initialize the in-memory structures used to access the symbol tables sitting inside the file. symclose frees those structures. everything else on this page is reading from a composite symbol table made up of all the currently open tables, which is honestly such a slay design decision.

the set of all currently open Fhdrs is maintained as a linked list starting at fhdrlist (chained via Fhdr.next). very main-character linked list, we stan.

findhdr searches the currently open Fhdrs for one whose file name ends with the path name — so like, libc.so matches /usr/lib/libc.so but not mylibc.so. it's a suffix match, bestie, not a substring free-for-all 🫶

---

🎀 the Symbol data structure

this is the icon itself:

typedef struct Symbol Symbol;
struct Symbol
{
        char  *name;
        Loc   loc;
        Loc   hiloc;
        char  class;
        char  type;
        ...
};

it describes a symbol table entry. the value field contains the offset of the symbol within its address space: global variables relative to the beginning of the data segment, text beyond the start of the text segment, and automatic variables and parameters relative to the stack frame. the type field contains the type of the symbol:

• T — text segment symbol
• t — static text segment symbol
• D — data segment symbol
• d — static data segment symbol
• B — bss segment symbol
• b — static bss segment symbol
• a — automatic (local) variable symbol
• p — function parameter symbol
• U — undefined symbol

and the class field assigns the symbol to a general class; CTEXT, CDATA, CAUTO and CPARAM are the most popular 💅

---

🔥 the functions, one by one 🔥

💫 indexsym, lookupsym, findsym

indexsym stores information for the n th symbol into s. the symbols are ordered by increasing address, so it's very "ordered queue" of it.

lookupsym fills a Symbol structure with symbol table information. global variables and functions are represented by a single name; local variables and parameters are uniquely specified by a function-and-variable name pair. arguments fn and var contain the name of a function and variable, respectively:

• if both are non-zero → the symbol table is searched for a parameter or automatic variable
• if only var is zero → the text symbol table is searched for function fn
• if only fn is zero → the global variable table is searched for var

findsym returns the symbol table entry of type class stored near addr. the selected symbol is a global variable or function with address nearest to and less than or equal to addr. class specification CDATA searches only the global variable symbol table; class CTEXT limits the search to the text symbol table; class CANY searches the text table first, then the global table. so CANY is the "try both, bestie" option 🌈

🧚 the f-prefixed girlies

findexsym, flookupsym and ffindsym are similar to indexsym, lookupsym and findsym, but they operate only on the symbols from hdr. and sorry to be the bearer of bad news: flookupsym and ffindsym return pointers to data stored in the hdr, which must not be modified or freed. like, don't touch. hands off. 💀

🍓 the lsym trio

indexlsym, lookuplsym and findlsym are similar to indexsym, lookupsym and findsym, but they operate on the smaller symbol table of parameters and variables local to the function represented by symbol s1.

• indexlsym writes symbol information for the nth local symbol of function s1 to s2. function parameters appear first in the ordering, followed by local symbols.
• lookuplsym writes symbol information for the symbol named name in function s1 to s2.
• findlsym searches for a symbol local to the function s1 whose location is exactly loc, writing its symbol information to s2. Loc is almost always an indirection through a frame pointer register; the details vary from architecture to architecture, so like, ask your architecture, iykyk.

⭐ symoff

symoff converts a location to a symbol reference. the string containing that reference is of the form name+offset, where name is the name of the nearest symbol with an address less than or equal to the target address, and offset is the hexadecimal offset beyond that symbol. if offset is zero, only the name of the symbol is printed. if no symbol is found within 4096 bytes of the address, the address is formatted as a hexadecimal address.

Buf is the address of a buffer of n bytes to receive the formatted string. Addr is the address to be converted. Type is the type code of the search space: CTEXT, CDATA, or CANY. symoff returns the length of the formatted string contained in buf. it's giving "here's your receipt" 🧾

ngl, the naming here is a little chaotic — the synopsis has symoff(char *a, uint n, ulong addr, uint class) but the description says Buf, Addr and Type. that's just how the page reads, bestie. not me fixing it 🙈

🌺 the source-line mapping squad

pc2file searches the symbol table to find the file and line number corresponding to the instruction at program counter pc. File is the address of a buffer of n bytes to receive the file name. Line receives the line number.

pc2line is like pc2file but neglects to return information about the source file. (yes, it literally says "neglects". she's doing her best 😭)

fileline is also like pc2file, but returns the file and line number in the n-byte text buffer buf, formatted as file:line. cute, compact, iconic.

file2pc performs the opposite mapping: it stores in pc a text address associated with line line in file file.

line2pc is similar: it converts a line number to an instruction address, storing it in pc. since a line number does not uniquely identify an instruction (e.g., every source file has line 1), basepc specifies a text address from which the search begins. usually this is the address of the first function in the file of interest. lowkey the most important detail on this whole page, don't forget basepc 💖

fnbound returns the start and end addresses of the function containing the text address supplied as the first argument. the second argument is an array of two unsigned longs; fnbound places the bounding addresses of the function in the first and second elements of this array. the start address is the address of the first instruction of the function; the end address is the first address beyond the end of the target function. so bounds[0] is the beginning and bounds[1] is the exclusive end — periodt ✨

---

💀 errors 💀

all functions return 0 on success and -1 on error. when an error occurs, a message describing it is stored in the system error buffer where it's available via errstr. so if something goes sideways, call errstr and she'll tell you what's up 🫶

---

🌈 SOURCE 🌈

/src/libmach

---

👑 SEE ALSO 👑

mach(3), mach-file(3), mach-map(3)

---

and that's the page, bestie!! 🎀 go forth and index those symbols. this was MACH-SYMBOL(3) from the Library Functions Manual, and the footer says hi with its own little MACH-SYMBOL(3) tag on the right side — so if you ever need her again, that's the name to look up 💅✨🦋