Bindings.Bfd

Contents

Description

This is the top-level module containing operations that can be performed on a Binary Format Descriptor (BFD). A BFD is opened on the binary file to be queried/manipulated and serves an opaque pointer.

Synopsis

Types

data Bfd Source

The opaque pointer to the Binary File Descriptor.

Instances

Show Bfd

Initialization

initialize :: IO ()Source

Initialize the library. You need to call initialize once, before using any of the functions in this library.

File Operations

targetsAndFormats Source

Arguments

:: FilePath	file to query
-> IO [(TargetName, Format)]

Returns a list of tuples representing the possible combinations of TargetName and Format that are valid for this file on this platform.

Possible Exceptions: Same as open.

open Source

Arguments

:: FilePath	file to open
-> Maybe TargetName	target
-> String	open mode ("r", "r+", "w", "w+", "a", "a+")
-> IO Bfd

Opens the file FilePath with the given target TargetName and open mode (as defined by the Unix fopen(3) function) and returns a Bfd object on success. FIXME: and marks it cacheable.

If the target is Nothing then the environment variable GNUTARGET is checked for a target name; if this is NULL or not defined then it chooses the the default target if set (see setDefault) and sets an internal flag in the Bfd object indicating that the target was defaulted (see isTargetDefaulted), or if not set, the first entry in the target list for the platform. Passing the string "default" as the TargetName or setting the environment variable to "default" also causes the above behavior.

Important: Before you use the returned Bfd object from a file you have opened, you must call checkFormat to 1) validate that the supplied TargetName is appropriate for the opened file, and 2) set the Format for the Bfd. So for most intents and purposes, opening a file is a two-step process.

Possible Exceptions: NoMemory (if any allocation fails), SystemCall (if open failed), and InvalidTarget (if supplied target is unknown).

close :: Bfd -> IO Bool Source

Close a Bfd and if all went well, return True. If the Bfd was open for writing, then pending operations are completed and the file written out and closed. If the created file is executable, then chmod(3) is called to mark it as such.

closeAllDone :: Bfd -> IO Bool Source

Close a Bfd and if all went well, return True. Differs from close in that it does not complete any pending operations. This function would be used if the application had just used a Bfd for swapping and didn't want to use any of the writing code. If the created file is executable, then chmod(3) is called to mark it as such.

Setting the Format

checkFormat :: Bfd -> Format -> IO Bool Source

The second part of opening a file (see open). Validates that the TargetName is appropriate for the opened file and if not, silently picks a more suitable TargetName, and also sets the Format of the Bfd object representing the opened file.

Important: You must call this function before using the vast majority of these functions operating on the Bfd as it updates critical data structures.

Possible Exceptions: InvalidOperation (if the file was opened write-only),