MACH-FILE(3)                                         MACH-FILE(3)

     NAME
          crackhdr, uncrackhdr, mapfile, unmapfile, mapproc,
          unmapproc, detachproc, ctlproc, procnotes - machine-
          independent access to exectuable files and running processes

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

          int   crackhdr(int fd, Fhdr *hdr)
          void  uncrackhdr(Fhdr *hdr)

          int   mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)
          void  unmapfile(Fhdr *hdr, Map *map)
          int   mapproc(int pid, Map *map, Regs **regs)
          void  unmapproc(Map *map)
          int   detachproc(int pid)
          int   ctlproc(int pid, char *msg)
          int   procnotes(int pid, char ***notes)

     DESCRIPTION
          These functions parse executable files and provide access to
          those files and to running processes.

          Crackhdr opens and parses the named executable file.  The
          returned data structure hdr is initialized with a machine-
          independent description of the header information.  The fol-
          lowing fields are the most commonly used:

          mach a pointer to the Mach structure for the target archi-
               tecture

          mname
               the name of the target architecture

          fname
               a description of the kind of file (e.g., executable,
               core dump)

          aname
               a description of the application binary interface this
               file uses; typically it is the name of an operating
               system If the global variable mach is nil, crackhdr
               points it to the same Mach structure.

          Mapfile adds the segments found in hdr to map. If hdr is an
          executable file, there are typically three segments: text,
          data, and a zero-backed bss. If hdr is a dynamic shared
          library, its segments are relocated by base before being

     MACH-FILE(3)                                         MACH-FILE(3)

          mapping.

          If hdr is a core file, there is one segment named core for
          each contiguous section of memory recorded in the core file.
          There are often quite a few of these, as most operating sys-
          tems omit clean memory pages when writing core files (Mac OS
          X is the only exception among the supported systems).
          Because core files have such holes, it is typically neces-
          sary to construct the core map by calling mapfile on the
          executable and then calling it again on the core file.
          Newly-added segments are mapped on top of existing segments,
          so this arrangement will use the core file for the segments
          it contains but fall back to the executable for the rest.

          Unmapfile removes the mappings in map corresponding to hdr.

          Mapproc attaches to a running program and adds its segments
          to the given map.  It adds one segment for each contiguous
          section of mapped memory.  On systems where this information
          cannot be determined, it adds a single segment covering the
          entire address space.  Accessing areas of this segment that
          are actually not mapped in the process address space will
          cause the get/put routines to return errors.

          Unmapproc removes the mappings in map corresponding to pid.
          Detachproc detaches from all previously attached processes.

          Ctlproc manipulates the process with id pid according to the
          message msg. Valid messages include:

          kill terminate the process

          startstop
               start the process and wait for it to stop

          sysstop
               arrange for the process to stop at its next system
               call, start the process, and then wait for it to stop

          waitstop
               wait for the process to stop

          start
               start the process

          Procnotes fills *notes with a pointer to an array of strings
          representing pending notes waiting for the process.  (On
          Unix, these notes are textual descriptions of any pending
          signals.)  Procnotes returns the number of pending notes.
          The memory at *notes should be freed via free (see
          malloc(3)) when no longer needed.

     MACH-FILE(3)                                         MACH-FILE(3)

     SOURCE
          /src/libmach

     SEE ALSO
          mach(3), mach-map(3)