Interface to the udis86
disassembler.
The goal at this level of wrapping is to provide the maximum feature-set from the underlying C library, with the minimum of C-related headaches. Therefore, this module's API is thoroughly imperative, but uses Haskellish types and automatic resource management.
For a higher-level, IO
-free API, see Hdis86.Pure.
This module is fully thread-safe: any number of threads
may manipulate one or several
objects at the same
time. The individual operations exported by this module
are guaranteed to be atomic.
UD
- data UD
- newUD :: IO UD
- setInputBuffer :: UD -> ByteString -> IO ()
- type InputHook = IO (Maybe Word8)
- setInputHook :: UD -> InputHook -> IO ()
- unsetInput :: UD -> IO ()
- advance :: UD -> IO (Maybe Word)
- skip :: UD -> Word -> IO ()
- setIP :: UD -> Word64 -> IO ()
- run :: UD -> IO a -> IO [a]
- getInstruction :: UD -> IO Instruction
- getLength :: UD -> IO Word
- getOffset :: UD -> IO Word64
- getHex :: UD -> IO String
- getBytes :: UD -> IO ByteString
- getAssembly :: UD -> IO String
- getMetadata :: UD -> IO Metadata
- setConfig :: UD -> Config -> IO ()
- setVendor :: UD -> Vendor -> IO ()
- setCPUMode :: UD -> CPUMode -> IO ()
- setSyntax :: UD -> Syntax -> IO ()
- setCallback :: UD -> IO () -> IO ()
- unsafeSetInputPtr :: UD -> Ptr Word8 -> Word -> IO ()
- unsafeRunLazy :: UD -> IO a -> IO [a]
Instances
Create a new disassembler instance.
There is no deleteUD
. Associated resources will be freed automatically
after this
value becomes unreachable.
UD
Input sources
setInputBuffer :: UD -> ByteString -> IO ()Source
Set up the
instance to read machine code from a UD
.
ByteString
This library does not copy the contents of the
.
It will hold onto the value until another input source is selected,
or until the ByteString
value becomes unreachable.
UD
This means that
is both safe and efficient, but it
may inhibit garbage collection of a larger setInputBuffer
containing
the input. To prevent this, use ByteString
ByteString.
.
copy
type InputHook = IO (Maybe Word8)Source
A custom input source.
Each time this action is executed, it should return a single byte of
input, or
if there are no more bytes to read.
Nothing
setInputHook :: UD -> InputHook -> IO ()Source
Register an
to provide machine code to disassemble.
InputHook
unsetInput :: UD -> IO ()Source
Clear any previous input source setting.
This allows the
instance to free any resources associated with
the input source. Those resources would be freed automatically after
the UD
value becomes unreachable, but you can use UD
to force this to happen earlier.
unsetInput
Disassembly
advance :: UD -> IO (Maybe Word)Source
Disassemble the next instruction and return its length in bytes, or
if there are no more instructions.
Nothing
setIP :: UD -> Word64 -> IO ()Source
Set the instruction pointer, i.e. the disassembler's idea of where the current instruction would live in memory.
Inspecting the output
getInstruction :: UD -> IO InstructionSource
Get the current instruction.
getOffset :: UD -> IO Word64Source
Get the offset of the current instruction. This value is set
by
and updated after each call to getIP
.
advance
getBytes :: UD -> IO ByteStringSource
Get the current instruction's machine code as a
.
ByteString
The bytes are copied out of internal state.
getAssembly :: UD -> IO StringSource
Get the assembly syntax for the current instruction.
See also
.
setSyntax
getMetadata :: UD -> IO MetadataSource
Get all metadata about the current instruction, along with the instruction itself.
Configuration
setConfig :: UD -> Config -> IO ()Source
Set an overall configuration.
Calls each of
, setVendor
, setCPUMode
, setSyntax
.
setIP
setSyntax :: UD -> Syntax -> IO ()Source
Set the assembly syntax to be used by
.
getAssembly
This takes effect after the next call to
.
disassemble
Callbacks
setCallback :: UD -> IO () -> IO ()Source
Register an action to be performed after each instruction is disassembled.
This is not necessary for using the library. An alternative is to perform
the action in a loop which also calls
.
advance
This disables updating of the string returned by
.
getAssembly
Unsafe operations
unsafeSetInputPtr :: UD -> Ptr Word8 -> Word -> IO ()Source
Set up the
instance to read directly from memory.
UD
Given are a pointer to a memory region, and the length of that region.
This is an unsafe operation because the contents of the memory region might change, especially if it's part of the heap managed by GHC's garbage collector.
You are responsible for ensuring that the memory pointed to does not
change or become invalid until another input source is selected.
You cannot rely on garbage collection of the
value, because
finalization may be delayed arbitrarily long after the value becomes
unreachable.
UD
It should be safe to use this on the static code segment of your process, which is useful when your Haskell program needs to disassemble itself.
unsafeRunLazy :: UD -> IO a -> IO [a]Source
Lazy version of
; calls into the C library as
elements of its result list are forced.
run
This has roughly the same caveats as
.
unsafeInterleaveIO