nsmap.cqct -- name space maps

A name space map (nsmap) is an object that manages name
spaces for the set of binaries (libraries and
executable) mapped within an address space.

Think of each mapping as a triple <BASE, PATH, NS>,
where BASE is the base address of the mapping, PATH is
the path name for the mapped binary, and NS is the
corresponding name space.

A typical address space consists of several library
mappings and exactly one executable mapping.  An nsmap
defines a distinguished mapping, called the executable,
which is intended to represent the executable mapping.

The methods of an nsmap support dynamic addition and
removal of mappings, query and update of the executable
mapping, name space lookup by address and name, name
space enumeration, and nsmap cloning.

Rather than require the nsmap client to construct
individual name spaces, each nsmap instance
encapsulates a function that maps a path name to a name
space.  Clients add mappings by specifying the binary
path name and base address.

The dwarf library (dwarf.cqct) exports several
functions that take nsmap arguments.

The ctls library (ctls.cqct) uses an nsmap to track the
name space mappings of target address spaces.


nsmap.cqct exports one function:

mknsmap(FN)

  FN:  function:  PATH (string) -> name space

  returns:  nsmap

This is the only constructor for nsmap instances.

FN is a function that encapsulates name space
construction.  PATH is a client-specified path name for
a binary; the result must be a name space for that
binary, mapped at address 0.


Each nsmap implements the following methods:

- add(BASE, PATH)

  BASE:  cvalue
  PATH:  string

  returns:  nil

Adds the name space for binary PATH to the map at
offset BASE.

The name space is obtained by calling the FN passed to
mknsmap.

If BASE is 0 and the nsmap does not have a defined
executable mapping, then the executable mapping is set
to be the name space for PATH.


- del(BASE)

  BASE:  cvalue

  returns:  nil

Removes the name space mapped at offset BASE.

If BASE corresponds to the executable mapping,
then the executable mapping is made undefined.


- exe()

  returns:  name space or nil

Returns the name space of the executable mapping, or
nil if it is undefined.


- setexe(BASE)

  returns:  nil

Defines the executable mapping to be the mapping at
address BASE.  It is error if there is no such mapping.


- byaddr(ADDR)

  ADDR:  cvalue

  returns:  name space or nil

Intuitively, byaddr attempts to return the name space
"containing" ADDR.

Precisely, byaddr returns the name space whose BASE
address is the greatest BASE address less than or
equal to ADDR.

byaddr returns nil if no name space matches.


- byname(PAT)

  PAT:  string

  returns:  name space or nil

Returns the name space whose PATH matches PAT.  A PATH
matches if strstr(PATH, PAT) returns non-nil.  The
search is performed in ascending BASE address order;
the first match is returned.

byname returns nil if no name space matches.


- each(F)

  F:  function:  BASE (cvalue) x PATH (string) x NS (name space) -> any value

  returns:  nil

For each mapping in ascending BASE order, each calls F,
passing the BASE, PATH, and name space of the mapping.

The return value of F is ignored.


- clone()

  returns:  nsmap

Clones the nsmap, returning a new nsmap that
shares the name space map record, but has
a distinct executable.

The result is not particularly useful.