package bap-std

  1. Overview
  2. Docs
package bap-std
Legend:
Library
Module
Module type
Parameter
Class
Class type

Memory region

type t = mem
val sexp_of_t : t -> Sexplib0.Sexp.t
val create : ?pos:int -> ?len:int -> endian -> addr -> Core_kernel.Bigstring.t -> t Core_kernel.Or_error.t

create ?pos ?len endian start data creates a memory region.

Creates a memory view of the provided data using the specified byte order endian and mapping the first (pos) byte to the start address. The pos and len parameters can be used to narrow down the view, and default to 0 and the length of the provided string, correspondingly.

The data may not be copied and the returned memory view may reference the same bigstring object.

val rebase : t -> addr -> t

rebase mem addr returns the same memory but with the new starting address addr.

  • since 2.2.0

memory representation of a program

val of_file : endian -> addr -> string -> t Core_kernel.Or_error.t

of_file endian start name creates a memory region from file. Takes data stored in a file with the given name and maps it to the memory region with the specified starting address start and using the endian for storing and reading words.

val view : ?word_size:size -> ?from:addr -> ?words:int -> t -> t Core_kernel.Or_error.t

view word_size ~from ~words mem returns a new memory that represents the specified region of memory mem. copy function performs deep copy.

  • parameter addr

    defaults min_addr mem

  • parameter words

    defaults to the end of the memory region.

val view_exn : ?word_size:size -> ?from:addr -> ?words:int -> t -> t

view_exn mem is the same as ok_exn @@view_exn mem but is slightly more efficient.

  • raises Invalid_arg

    in case if the arguments are not fitting into the memory.

  • since 2.2.0
val range : t -> addr -> addr -> t Core_kernel.Or_error.t

range mem a0 a1 returns a view on mem starting from address a0 and ending at a1, bounds inclusive

val merge : t -> t -> t Core_kernel.Or_error.t

merge m1 m2 takes two memory regions, that either intersects or share edges (i.e., difference between min_addr of one of the blocks and max_addr of another is less then or equal to one, and returns memory blocks that spans memory starting from the address

min (min_addr m1) (min_addr m2)

and ending with address

max (max_addr m1) (max_addr m2)

.

Will return an error, if either the above state precondition doesn't hold, or if this two memory blocks doesn't share the same underlying memory (i.e., bases), or if they have different endianness.

val first_byte : t -> t

first_byte m returns first byte of m as a memory

val last_byte : t -> t

last_byte m returns last byte of m as a memory

val endian : t -> endian

returns the order of bytes in a word

val get : ?disp:int -> ?index:int -> ?scale:size -> ?addr:addr -> t -> word Core_kernel.Or_error.t

get ?disp ?index ?scale ?addr mem reads a scale sized word from mem.

Parameters mimic the reference syntax in the gas assembler, e.g., dis(base,index,scale) denotes address at base + index * scale + dis.

The size of the returned word is equal to scale, bytes are read in the endian mem order.

  • parameter disp

    is the base offset and defaults to 0

  • parameter index

    defaults to 0

  • parameter scale

    defaults to `r8

m^n dereferences a byte at address n

val (^!) : t -> addr -> word

m^.n dereferences a byte at address n

val max_addr : t -> addr

max_addr m is an address of the last byte of m

val min_addr : t -> addr

min_addr m is an address of the first byte of m

val length : t -> int

length m returns a number of bytes in m

val contains : t -> addr -> bool

contains mem addr returns true if mem contains address addr

val compare_with : t -> addr -> [ `addr_is_inside | `addr_is_below | `addr_is_above ]

compare_with mem addr compares memory with addr

module Input : sig ... end

A set of low level input operations. Note: it is more effective to use above head iterators, instead of this low level interface, since iterators do not need to check every memory access.

Printing and outputting

include Regular.Std.Printable.S with type t := t
val to_string : t -> string

to_string x returns a human-readable representation of x

val str : unit -> t -> string

str () t is formatted output function that matches "%a" conversion format specifier in functions, that prints to string, e.g., sprintf, failwithf, errorf and, surprisingly all Lwt printing function, including Lwt_io.printf and logging (or any other function with type ('a,unit,string,...) formatN`. Example:

Or_error.errorf "type %a is not valid for %a"
  Type.str ty Exp.str exp
val pps : unit -> t -> string

synonym for str

val ppo : Core_kernel.Out_channel.t -> t -> unit

will print to a standard output_channel, useful for using in printf, fprintf, etc.

val pp_seq : Format.formatter -> t Core_kernel.Sequence.t -> unit

prints a sequence of values of type t

this will include pp function from Core that has type t printer, and can be used in Format.printf family of functions

include Core_kernel.Pretty_printer.S with type t := t
val pp : Base.Formatter.t -> t -> unit
val hexdump : t -> string

hexdump t out outputs hexdump (as per hexdump -C) of the memory to formatter out

a set of iterators, with identity monad.

include Memory_iterators with type t := t and type 'a m = 'a
type 'a m = 'a
val fold : ?word_size:size -> t -> init:'b -> f:(word -> 'b -> 'b m) -> 'b m

fold ~word_size ~init ~f t folds over elements of t, so a result is f (... (f (f a elt_1) elt_2) ...) elt_n

val iter : ?word_size:size -> t -> f:(word -> unit m) -> unit m

iter ~word_size ~f t applies f to elements of t

val foldi : ?word_size:size -> t -> init:'b -> f:(addr -> word -> 'b -> 'b m) -> 'b m

foldi ~word_size ~init ~f t is like fold, but also passes an address to the f

val iteri : ?word_size:size -> t -> f:(addr -> word -> unit m) -> unit m

iteri ~word_size ~f t is like iter, but also passes an address to the f

val exists : ?word_size:size -> t -> f:(addr -> word -> bool m) -> bool m

exists ~word_size ~f t checks if at least one element of t satisfies the predicate f

val for_all : ?word_size:size -> t -> f:(addr -> word -> bool m) -> bool m

for_all ~word_size ~f t checks if all elements of t satisfies the predicate f

val count : ?word_size:size -> t -> f:(addr -> word -> bool m) -> int m

count ~word_size ~f t is the number of elements in t that satisfies the predicate f.

val find_if : ?word_size:size -> t -> f:(addr -> word -> bool m) -> word option m

find_if ~word_size ~f t returns the first element of t that satisfies the predicate p or None if no elements satisfied

val find_map : ?word_size:size -> t -> f:(addr -> word -> 'a option m) -> 'a option m

find_map ~word_size ~f t returns the first evaluation of f that returns Some or None if f always returns None

module With_error : Memory_iterators with type t := t and type 'a m = 'a Core_kernel.Or_error.t

iterators lifter to the Or_error monad

module Make_iterators (M : Core_kernel.Monad.S) : Memory_iterators with type t := t and type 'a m = 'a M.t

lifts iterators to monad M

Interfacing with C

The following interfaces is supposed to be used only for the purposes of exposing memory to c programs.

val to_buffer : t -> Core_kernel.Bigsubstring.t

to_buffers mem creates a buffer representing the memory mem. It is not specified whether the returned buffer has some sharing with underlying implementation. In other words the returned buffer shouldn't be modified.

Since it is not guaranteed that memory is contiguous, a sequence of buffers is returned, with each buffer representing a contiguous part of memory.

module Trie : sig ... end

Tries over memory

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct