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 following fields are the most commonly used:

mach
    a pointer to the Mach structure for the target architecture

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 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 systems 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 necessary 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.

SOURCE
/usr/local/plan9/src/libmach

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