man(1) Manual page archive

     MACHINES(2X)                                         MACHINES(2X)

          crackhdr, syminit, getsym, symbase, pc2sp, pc2line,
          line2addr, lookup, findlocal, getauto, findsym, localsym,
          globalsym, textsym, file2pc, fileelem, fileline, newmap,
          setmap, unusemap, freemap, loadmap, mget, mput, beswab,
          beswal, leswab, leswal - machine dependent library

          #include <mach.h>

          int  crackhdr(int fd, Fhdr *fp)

          int  syminit(int fd, Fhdr *fp)

          Sym  *getsym(int index)

          Sym  *symbase(long *nsyms)

          int  fileelem(Sym **fp, uchar *encname, char *buf, int n)

          long pc2sp(ulong pc)

          long pc2line(ulong pc)

          long line2addr(ulong line, ulong basepc)

          int  lookup(char *fn, char *var, Symbol *s)

          int  findlocal(Symbol *s1, char *name, Symbol *s2)

          int  getauto(Symbol *s1, int off, int class, Symbol *s2)

          int  findsym(long addr, int class, Symbol *s)

          int  localsym(Symbol *s, int index)

          int  globalsym(Symbol *s, int index)

          int  textsym(Symbol *s, int index)

          long file2pc(char *file, ulong line)

          int fileline(char *str, int n, ulong addr)

          Map  *newmap(Map *map, int fd)

          int  setmap(Map *map, int seg, ulong base, ulong end, ulong

          void unusemap(Map *map, int seg)

     MACHINES(2X)                                         MACHINES(2X)

          Map  *loadmap(Map *map, int fd, Fhdr *fp)

          int  mget(Map *map, int seg, ulong addr, char *buf, int

          int mput(Map *map, int seg, ulong addr, char *buf, int size)

          ushort beswab(ushort s)

          long beswal(long l)

          ushort leswab(ushort s)

          long leswal(long l)

          The functions in this library provide machine-independent
          interpretation of executable and object files and executing
          process images.

          Crackhdr loads data structure fp with a machine-independent
          description of the header of the executable file or image
          associated with the open file descriptor fd. It also sets
          global variable mach pointing to the Mach data structure
          containing the machine-dependent parameters of the target

          Syminit, getsym, symbase, fileelem, pc2sp, pc2line, and
          line2addr process the symbol table contained in an exe-
          cutable file.  The symbol table is stored internally as an
          array of Sym structures as defined in a.out(6).

          Syminit uses the Fhdr structure filled by crackhdr to load
          the raw symbol tables from the open file descriptor fd. It
          returns the count of the number of symbols in the symbol
          table or -1 if an error occurs.

          Getsym returns the address of the ith Sym structure or zero
          if index is out of range.

          Symbase returns the address of the first element of the vec-
          tor of Sym structures comprising the symbol table.  The
          argument is the address of a long that is loaded with the
          number of entries in the symbol table.

          Fileelem converts a file name, encoded as described in
          a.out(6), to a character string. Fp is the base of an array
          of pointers to file path components ordered by path index.
          Encname is the address of an array of file path components
          in the form of a z symbol table entry. Buf and n specify the
          address of a character buffer and its length.  Fileelem
          returns the length of the null-terminated string that is at

     MACHINES(2X)                                         MACHINES(2X)

          most n-1 bytes long.

          Pc2sp returns an offset associated with a given value of the
          program counter.  Adding this offset to the current value of
          the stack pointer gives the address of the current stack
          frame.  This algorithm is only valid for the 386 and 68020
          architectures; other architectures use a fixed frame acces-
          sible through a dummy local variable.

          Pc2line returns the line number of the statement associated
          with the instruction address pc. The line number returned is
          the absolute line number in the file as seen by the compiler
          after pre-processing; the original line number in the source
          file may derived from this value using the history stacks
          contained in the symbol table.

          Line2addr converts a line number to an instruction address.
          The first argument is the absolute line number in a file.
          Since a line number does not uniquely identify an instruc-
          tion location (every source file has line 1), a second argu-
          ment specifies a text address from which the search begins.
          Usually this is the address of the first function in the
          file of interest.  Pc2sp, pc2line, and line2addr return -1
          in the case of an error.

          Lookup, findlocal, getauto, findsym, localsym, globalsym,
          textsym, file2pc, and fileline operate on data structures
          riding above the raw symbol table.  These data structures
          occupy memory and impose a startup penalty but speed
          retrievals and provide higher-level access to the basic sym-
          bol table.  Syminit must be called prior to invoking these
          functions.  The Symbol data structure:

               typedef struct {
                        void *handle;     /* private */
                        struct {
                            char  *name;
                            long   value;
                            char   type;
                            char   class;
               } Symbol;

          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 that start of the text segment, and automatic
          variables and parameters relative to the stack frame.  The
          type field contains the type of the symbol as defined in
          a.out(6). The class field assigns the symbol to a general
          class; CTEXT, CDATA, CAUTO, and CPARAM are the most popular.

     MACHINES(2X)                                         MACHINES(2X)

          Lookup fills a Symbol structure with symbol table informa-
          tion.  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
          fnandvar 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.

          Findlocal fills s2 with the symbol table data of the auto-
          matic variable or parameter matching name. S1 is a Symbol
          data structure describing a function or a local variable;
          the latter resolves to its owning function.

          Getauto searches the local symbols associated with function
          s1 for an automatic variable or parameter located at stack
          offset off . Class selects the class of variable: CAUTO or
          CPARAM.  S2 is the address of a Symbol data structure to
          receive the symbol table information of the desired symbol.

          Findsym returns the symbol table entry of type class stored
          near addr. The selected symbol is a global variable or func-
          tion 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 sym-
          bol table.  Class specification CANY searches the text table
          first, then the global table.

          Localsym returns the ith local variable associated with the
          function indicated by s. S may reference a function or a
          local variable; the latter resolves to its owning function.
          If the ith local symbol exists, s is filled with the data
          describing it.

          Globalsym loads s with the symbol table information of the
          ith global variable.

          Textsym loads s with the symbol table information of the ith
          text symbol.  The text symbols are ordered by increasing

          File2pc returns a text address associated with line in file

          Fileline converts text address addr to its equivalent line
          number in a source file.  The result, a null terminated
          character string of the form file:line is placed in buffer
          str of n bytes.  Up to n-1 characters are copied to the

     MACHINES(2X)                                         MACHINES(2X)

          Functions file2pc and fileline may produce inaccurate
          results when applied to optimized code.

          A Map is a data structure used to transform an address in
          the logical address space of an executable to an offset in a
          file or executing image.  Each map comprises up to four log-
          ical segments, named SEGDATA, SEGTEXT, SEGUBLK, and SEGREGS,
          that map the data, text, `u block', and register segments,
          respectively.  A section of the physical address space may
          be mapped by multiple segments.  A segment contains the low
          and high addresses of the logical address space of the seg-
          ment and the physical offset in the file or executing image
          to the base of the address space.

          Newmap creates a new map or recycles one currently in use.
          If map is zero, a new map is dynamically allocated, other-
          wise it is assumed to point to an existing map.  The map is
          marked empty and attached to the open file descriptor fd.
          The address of the map is returned.

          Setmap loads segment seg of map with the segment mapping
          parameters.  Base and end contain the lowest and highest
          virtual addresses mapped by the segment, respectively.
          Foffset contains the offset in the file or executable image
          to the start of the segment.

          Unusemap marks segment seg in map map empty.  Other segments
          in the map remain unaffected.

          Loadmap uses the Fhdr data structure filled by crackhdr to
          initialize a map for an executable file or executing image.
          If map is zero, a new map is dynamically allocated; other-
          wise, map is initialized with the appropriate values.  This
          function returns the address of the map if successful or
          zero on failure.

          Mget reads size bytes into buf from the file associated with
          map. The data is read from logical address addr in segment
          seg. Fput is similar except it writes to the executable file
          or executing image associated with map. Both functions
          return -1 if they are unable to calculate a physical
          address, 0 if the read or write operation fails, and 1 on
          success.  The segment may be one of SEGTEXT, SEGDATA,
          SEGUBLK, or SEGREGS, or the special segment, SEGANY.  If
          SEGANY is specified, the address translation is performed
          using the text, data, and u-block maps, in that order.
          Accesses to SEGDATA first attempt a translation using the
          data map then the u-block map.  The read or write operation
          takes place at the address produced by the first valid

          Beswab, and beswal convert a big-endian ushort and long

     MACHINES(2X)                                         MACHINES(2X)

          respectively, to the target processor's native representa-
          tion.  Leswab, and leswal perform the same conversion for a
          little-endian ushort and long respectively.

          Unless otherwise specified, all functions return 1 on suc-
          cess, or 0 on error.