| <head> |
| <title>mach-file(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>MACH-FILE(3)</b><td align=right><b>MACH-FILE(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, |
| detachproc, ctlproc, procnotes – machine-independent access to |
| exectuable files and running processes<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h><br> |
| #include <mach.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| int crackhdr(int fd, Fhdr *hdr)<br> |
| void uncrackhdr(Fhdr *hdr) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)<br> |
| void unmapfile(Fhdr *hdr, Map *map)<br> |
| int mapproc(int pid, Map *map, Regs **regs)<br> |
| void unmapproc(Map *map)<br> |
| int detachproc(int pid)<br> |
| int ctlproc(int pid, char *msg)<br> |
| int procnotes(int pid, char ***notes)<br> |
| |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| These functions parse executable files and provide access to those |
| files and to running processes. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Crackhdr</i> opens and parses the named executable file. The returned |
| data structure <i>hdr</i> is initialized with a machine-independent description |
| of the header information. The following fields are the most commonly |
| used:<br> |
| <tt><font size=+1>mach</font></tt>a pointer to the <tt><font size=+1>Mach</font></tt> structure for the target architecture<br> |
| <tt><font size=+1>mname<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| the name of the target architecture<br> |
| |
| </table> |
| <tt><font size=+1>fname<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| a description of the kind of file (e.g., executable, core dump)<br> |
| |
| </table> |
| <tt><font size=+1>aname<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| a description of the application binary interface this file uses; |
| typically it is the name of an operating system If the global |
| variable <i>mach</i> is nil, <i>crackhdr</i> points it to the same <tt><font size=+1>Mach</font></tt> structure. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| </table> |
| <i>Mapfile</i> adds the segments found in <i>hdr</i> to <i>map</i>. If <i>hdr</i> is an executable |
| file, there are typically three segments: <i>text</i>, <i>data</i>, and a zero-backed |
| <i>bss</i>. If <i>hdr</i> is a dynamic shared library, its segments are relocated |
| by <i>base</i> before being mapping. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| If <i>hdr</i> is a core file, there is one segment named <i>core</i> 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 <i>mapfile</i> 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Unmapfile</i> removes the mappings in <i>map</i> corresponding to <i>hdr</i>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Mapproc</i> 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Unmapproc</i> removes the mappings in <i>map</i> corresponding to <i>pid</i>. <i>Detachproc</i> |
| detaches from all previously attached processes. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Ctlproc</i> manipulates the process with id <i>pid</i> according to the message |
| <i>msg</i>. Valid messages include:<br> |
| <tt><font size=+1>kill</font></tt>terminate the process<br> |
| <tt><font size=+1>startstop<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| start the process and wait for it to stop<br> |
| |
| </table> |
| <tt><font size=+1>sysstop<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| arrange for the process to stop at its next system call, start |
| the process, and then wait for it to stop<br> |
| |
| </table> |
| <tt><font size=+1>waitstop<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| wait for the process to stop<br> |
| |
| </table> |
| <tt><font size=+1>start<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| start the process |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| </table> |
| <i>Procnotes</i> fills <tt><font size=+1>*</font></tt><i>notes</i> 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.) <i>Procnotes</i> returns |
| the number of pending notes. The memory at <tt><font size=+1>*</font></tt><i>notes</i> should be freed |
| via <i>free</i> (see <a href="../man3/malloc.html"><i>malloc</i>(3)</a>) when no longer needed. |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libmach<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/mach.html"><i>mach</i>(3)</a>, <a href="../man3/mach-map.html"><i>mach-map</i>(3)</a><br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
