mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
170 lines
3.7 KiB
Groff
170 lines
3.7 KiB
Groff
.TH MACH-FILE 3
|
|
.SH NAME
|
|
crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc,
|
|
procnotes \- machine-independent access to exectuable files and running processes
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <mach.h>
|
|
.PP
|
|
.ft B
|
|
.ta \w'\fBxxxxxx'u +\w'xxxxxx'u
|
|
int crackhdr(int fd, Fhdr *hdr)
|
|
.br
|
|
void uncrackhdr(Fhdr *hdr)
|
|
.PP
|
|
.ft B
|
|
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)
|
|
.SH DESCRIPTION
|
|
These functions parse executable files and
|
|
provide access to those files and to running processes.
|
|
.PP
|
|
.I Crackhdr
|
|
opens and parses the named executable file.
|
|
The returned data structure
|
|
.I hdr
|
|
is initialized with a machine-independent description
|
|
of the header information. The following fields are the
|
|
most commonly used:
|
|
.TP
|
|
.B mach
|
|
a pointer to the
|
|
.B Mach
|
|
structure for the target architecture
|
|
.TP
|
|
.B mname
|
|
the name of the target architecture
|
|
.TP
|
|
.B fname
|
|
a description of the kind of file
|
|
(e.g., executable, core dump)
|
|
.TP
|
|
.B aname
|
|
a description of the application binary interface
|
|
this file uses; typically it is the name of an operating system
|
|
.PD
|
|
If the global variable
|
|
.I mach
|
|
is nil,
|
|
.I crackhdr
|
|
points it to the same
|
|
.B Mach
|
|
structure.
|
|
.PP
|
|
.I Mapfile
|
|
adds the segments found in
|
|
.I hdr
|
|
to
|
|
.IR map .
|
|
If
|
|
.I hdr
|
|
is an executable file, there are typically three segments:
|
|
.IR text ,
|
|
.IR data ,
|
|
and a zero-backed
|
|
.IR bss .
|
|
If
|
|
.I hdr
|
|
is a dynamic shared library, its segments are relocated by
|
|
.I base
|
|
before being mapping.
|
|
.PP
|
|
If
|
|
.I hdr
|
|
is a core file, there is one segment named
|
|
.I 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
|
|
.I 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.
|
|
.PP
|
|
.I Unmapfile
|
|
removes the mappings in
|
|
.I map
|
|
corresponding to
|
|
.IR hdr .
|
|
.PP
|
|
.I 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.
|
|
.PP
|
|
.I Unmapproc
|
|
removes the mappings in
|
|
.I map
|
|
corresponding to
|
|
.IR pid .
|
|
.I Detachproc
|
|
detaches from all previously attached processes.
|
|
.PP
|
|
.I Ctlproc
|
|
manipulates the process with id
|
|
.I pid
|
|
according to the message
|
|
.IR msg .
|
|
Valid messages include:
|
|
.TP
|
|
.B kill
|
|
terminate the process
|
|
.TP
|
|
.B startstop
|
|
start the process and wait for it to stop
|
|
.TP
|
|
.B sysstop
|
|
arrange for the process to stop at its next system call,
|
|
start the process, and then wait for it to stop
|
|
.TP
|
|
.B waitstop
|
|
wait for the process to stop
|
|
.TP
|
|
.B start
|
|
start the process
|
|
.PD
|
|
.PP
|
|
.I Procnotes
|
|
fills
|
|
.BI * 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.)
|
|
.I Procnotes
|
|
returns the number of pending notes.
|
|
The memory at
|
|
.BI * notes
|
|
should be freed via
|
|
.I free
|
|
(see
|
|
.MR malloc (3) )
|
|
when no longer needed.
|
|
.SH SOURCE
|
|
.B \*9/src/libmach
|
|
.SH "SEE ALSO"
|
|
.MR mach (3) ,
|
|
.MR mach-map (3)
|