Introduction

This document describes various libraries provided with the L1 implementation of Cinquecento. It is not complete. See the L1 Manual for more details on Cinquecento and L1.

Standard Libraries

The L1 implementation of Cinquecento comes with several standard libraries stored in the lib/ subdirectory. Since they are included in l1's load path, these libraries are loaded via the form:

This section gives non-exhaustive describions for several of the provided libraries.

asutil.cqct

asutil.cqct provides code for loading, saving, and copying address spaces.

core.cqct

core.cqct provides functionality for loading a core file as an address space.

dump.cqct

dump.cqct provides code for printing out namespaces and the values associated with typed pointers.

dynamictypes.cqct

This file provides the ability to create dynamic types, or types that change based on their content. For example, consider the following vector type:

struct Vector {
        unsigned int size;
        int data[];
};

stuct Vector {
        unsigned int size;
	int data[p->size];
};

elf.cqct

elf.cqct contains code for handling elf files. Much of this function provides machinery to keep the client code unaware of whether or not the elf file underconsideration contains a 32 or 64 bit address space. The recode bd type, which is instantiated through mkelfrec, is where the elf domain is contained. The elfsym types, which are created via getcqctelfsym contain information about specific elf symbols.

nsgraph.cqct

nsgraph.cqct provides code for creating and analyzing graphs of types inferred from a namespace.

nsutil.cqct

nsutil.cqct provides code for checking type equality, printing namespaces, and iterating over types in namespaces.

rangeset.cqct

rangeset.cqct provides a data structure that stores a set of ranges in a minimal way. The rangeset structure is implemented with a red black tree, and allows one to add and remove ranges with the guarantee that (1) a minimal number of ranges will be stored and (2) checking if a value is contained in a given rangeset will take O(log(n)) time (where n is the number of ranges stored). Example usage:

@include <rangeset.cqct>
rs = rangeset_create();
rangeset_insert(rs,mkrange(50,100));
rangeset_delete(rs,mkrange(60,5));
rangeset_contains(rs,53); //returns 1
rangeset_contains(rs,61); //returns 0
rangeset_enumerate(rs); //returns [ range(50,10), range(65,85) ]

re.cqct

re.cqct provides an API for using regular expressions in CQCT. Currently, regular expressions containing [], *, ., (), and ? are all supported with the same meanings as in PERL (run "man perlre" for more details), with the following exceptions:

• () does not enable back references as in PERL.
• [] does not allow for ranges or for negated classes (i.e. ^ does not create a negated class, and - does not create a spanned class).

@include <re.cqct>
re_match("abc*d","abccccd"); //returns 1
re_match("abc*d","accccd"); //returns 0
re_match("abc*d","xxxabccccd"); //returns 0
re_find("abc*d","xxxabccccd"); //returns 3 
comp = re_create("abc*d"); //pre-compile the re
re_match(comp,"abccccd"); //returns 1
re_match(comp,"accccd"); //returns 0
re_match(comp,"xxxabccccd"); //returns 0
re_find(comp,"xxxabccccd"); //returns 3 

rbtree.cqct

rbtree.cqct provides an API for red black trees. Red black trees are balanced and provide O(n) insertion, deletion, and querying.

snames.cqct

snames.cqct is a server intended to serve Cinquecento name spaces across a network using the sctl protocol. It supports two modes of operation: in names mode, name spaces are drawn from a "names files" stored in the local file system; in sctl mode, name spaces are drawn from new invocations of the sctl server (which must be in the path).

The usage is:

Port is the port on which the server accepts connections (from any available network interface).

Rootns is the name of the root name space (e.g., c32le) from which all served name spaces are extended. It is meaningful only in names mode.

Mode is either names or sctl.

Prefix is the path to the directory tree in which the served names files are accessed. To resolve a name space name, the path argument provided by the client snamesns operation is appended to prefix. (If Prefix does not end with the character "/", it is added.) Prefix is meaningful only in names mode.

The remaining optional arguments var ... are each the name of a variable that will be bound, with value 0, in the scope of the @names evaluation that is performed for each served name space. This allows the serving of names files that contain references to variables, but it does not offer any control over their values. These arguments are meaningful only in names mode.

In the event of an error, the snames server automatically restarts. Some diagnostics are printed to standard output.

This command-line synopsis should be revised to not require meaningless arguments in sctl mode.

gdb.cqct

gdb.cqct provides access to an execution target over the GDB remote serial protocol ("GDB stubs").

The library provides a set of functions for directly speaking various messages of the GDB protocol: gdbbrk, gdbc, gdbg, gdbm, gdbM, gdbs, gdbS, gdbz, gdbZ, gdbrecvpkt. This set is likely to grow, and is not documented.

Most users should use the high-level client interface, mkgdbctl:

The following example constructs a gdb control object to the GDB server at TCP port 10000 on the local host, and causes the target to single step ten times:

; @include <gdb.cqct>
; ctl = mkgdbctl(tcpopen("localhost:10000"));
; for(i = 0; i < 10; i++) ctl.step();

This example constructs a domain dom from the control object, using a separately provided name space:

; ns = @names c32le { @include "my.names" };
; dom = mkdom(ns, ctl.mem());