Package com.ensoftcorp.open.c.commons.analysis

Class CommonQueries

java.lang.Object

com.ensoftcorp.open.c.commons.analysis.CommonQueries

public final class CommonQueries
extends java.lang.Object

Common queries which are useful for writing larger C analysis programs, and for using on the shell.

Author:

Ben Holland, Tom Deering, Jon Mathews, Ahmed Tamrawi

Method Summary

Modifier and Type	Method	Description
static com.ensoftcorp.atlas.core.query.Q	advancedIntersection(com.ensoftcorp.atlas.core.query.Q first, com.ensoftcorp.atlas.core.query.Q second, java.lang.String[] nodeTags, java.lang.String[] edgeTags)	Given two query expressions, intersects the given node and edge kinds to produce a new expression.
static com.ensoftcorp.atlas.core.query.Q	call(com.ensoftcorp.atlas.core.query.Q funcs)	Returns the set of function directly calling a given function(s)
static com.ensoftcorp.atlas.core.query.Q	called(com.ensoftcorp.atlas.core.query.Q origin)	Returns the subset of the given functions which are called.
static com.ensoftcorp.atlas.core.query.Q	called(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the subset of the given functions which are called.
static com.ensoftcorp.atlas.core.query.Q	calledBy(com.ensoftcorp.atlas.core.query.Q funcs)	Returns the set of functions that are directly called by given function(s)
static com.ensoftcorp.atlas.core.query.Q	calledBy(com.ensoftcorp.atlas.core.query.Q callers, com.ensoftcorp.atlas.core.query.Q called)	Returns the given functions which were called by the given callers.
static com.ensoftcorp.atlas.core.query.Q	calledBy(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q callers, com.ensoftcorp.atlas.core.query.Q called)	Returns the given functions which were called by the given callers.
static com.ensoftcorp.atlas.core.query.Q	callers(com.ensoftcorp.atlas.core.query.Q origin)	Returns the direct callers of the given functions.
static com.ensoftcorp.atlas.core.query.Q	callers(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the direct callers of the given functions.
static com.ensoftcorp.atlas.core.query.Q	cfg(com.ensoftcorp.atlas.core.db.graph.Node function)
static com.ensoftcorp.atlas.core.query.Q	cfg(com.ensoftcorp.atlas.core.query.Q functions)
static com.ensoftcorp.atlas.core.query.Q	cfg(java.lang.String funcName)	Returns the control-flow graph (CFG) of the given function name in (funcName)
static com.ensoftcorp.atlas.core.query.Q	cg(com.ensoftcorp.atlas.core.query.Q funcs)	Returns the call graph of the given function(s) in (funcs)
static com.ensoftcorp.atlas.core.query.Q	conditionsAbove(com.ensoftcorp.atlas.core.query.Q origin)	Returns the control flow graph between conditional nodes and the given origin.
static com.ensoftcorp.atlas.core.query.Q	conditionsAbove(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the control flow graph between conditional nodes and the given origin.
static com.ensoftcorp.atlas.core.query.Q	declarations(com.ensoftcorp.atlas.core.query.Q origin)	Produces a declarations (contains) graph.
static com.ensoftcorp.atlas.core.query.Q	declarations(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Produces a declarations (contains) graph.
static com.ensoftcorp.atlas.core.query.Q	dfg(com.ensoftcorp.atlas.core.db.graph.Node function)
static com.ensoftcorp.atlas.core.query.Q	dfg(com.ensoftcorp.atlas.core.query.Q functions)
static com.ensoftcorp.atlas.core.query.Q	dfg(java.lang.String functionContext, java.lang.String functionSource, java.lang.String functionSink)	Returns the forward data-flow graph starting at the return value of Function "functionSource" in the context of Function "functionContext".
static long	edgeSize(com.ensoftcorp.atlas.core.query.Q toCount)	Returns the number of edges contained.
static com.ensoftcorp.atlas.core.query.Q	excfg(com.ensoftcorp.atlas.core.db.graph.Node function)
static com.ensoftcorp.atlas.core.query.Q	excfg(com.ensoftcorp.atlas.core.query.Q functions)
static com.ensoftcorp.atlas.core.query.Q	file(java.lang.String path)	Returns Types, GlobalVariables, Functions, and Macros with source correspondence matching the given path.
static com.ensoftcorp.atlas.core.query.Q	firstDeclarator(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q declared, java.lang.String... declaratorTypes)	Returns the first declaring node of the given Q which is tagged with one of the given types.
static com.ensoftcorp.atlas.core.query.Q	firstDeclarator(com.ensoftcorp.atlas.core.query.Q declared, java.lang.String... declaratorTypes)	Returns the first declaring node of the given Q which is tagged with one of the given types.
static com.ensoftcorp.atlas.core.query.Q	forwardProjection(com.ensoftcorp.atlas.core.query.Q projection, com.ensoftcorp.atlas.core.query.Q node)	Returns the intra-procedural forward data-flow graph starting at the given node within the projection
static com.ensoftcorp.atlas.core.query.Q	functionParameter(com.ensoftcorp.atlas.core.query.Q functions)	Returns the parameters of the given functions.
static com.ensoftcorp.atlas.core.query.Q	functionParameter(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q functions)	Returns the parameters of the given functions.
static com.ensoftcorp.atlas.core.query.Q	functionParameter(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q functions, java.lang.Integer... index)	Returns the parameters of the given functions at the given indices.
static com.ensoftcorp.atlas.core.query.Q	functionParameter(com.ensoftcorp.atlas.core.query.Q functions, java.lang.Integer... index)	Returns the parameters of the given functions at the given indices.
static com.ensoftcorp.atlas.core.query.Q	functionPtr()	Selects all functions, and one step of data flow for the capture of the address of a function.
static com.ensoftcorp.atlas.core.query.Q	functionReturn(com.ensoftcorp.atlas.core.query.Q functions)	Returns the return nodes for the given functions.
static com.ensoftcorp.atlas.core.query.Q	functionReturn(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q functions)	Returns the return nodes for the given functions.
static com.ensoftcorp.atlas.core.query.Q	functions(java.lang.String... functionNames)	Returns the set of functions where their names matches the any of the names given (functionNames) list.
static com.ensoftcorp.atlas.core.query.Q	functionsOf(com.ensoftcorp.atlas.core.query.Q types)	Returns the functions declared by the given types.
static com.ensoftcorp.atlas.core.query.Q	functionsOf(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q types)	Returns the functions declared by the given types.
static com.ensoftcorp.atlas.core.db.graph.Node	getContainingControlFlowNode(com.ensoftcorp.atlas.core.db.graph.Node node)	Returns the nearest parent that is a control flow node
static com.ensoftcorp.atlas.core.db.graph.Node	getContainingFunction(com.ensoftcorp.atlas.core.db.graph.Node node)	Returns the containing function of a given graph element or null if one is not found
static com.ensoftcorp.atlas.core.query.Q	getContainingFunction(com.ensoftcorp.atlas.core.query.Q nodes)	Returns the Functions containing the given nodes (if any).
static com.ensoftcorp.atlas.core.query.Q	getContainingFunctions(com.ensoftcorp.atlas.core.query.Q nodes)	Returns the containing function of a given Q or empty if one is not found
static com.ensoftcorp.atlas.core.db.graph.Node	getContainingNode(com.ensoftcorp.atlas.core.db.graph.Node node, java.lang.String containingTag)	Find the next immediate containing node with the given tag.
static com.ensoftcorp.atlas.core.db.graph.Edge	getEdgeByAddress(java.lang.String address)	Selects the Atlas edge graph element given a serialized graph element address Returns null if the address does not correspond to a edge
static com.ensoftcorp.atlas.core.db.graph.GraphElement	getGraphElementByAddress(java.lang.String address)	Selects the Atlas graph element given a serialized graph element address Returns null if the address does not correspond to a graph element
static com.ensoftcorp.atlas.core.db.graph.Node	getNodeByAddress(java.lang.String address)	Selects the Atlas node graph element given a serialized graph element address Returns null if the address does not correspond to a node
static java.lang.String	getQualifiedFunctionName(com.ensoftcorp.atlas.core.db.graph.Node function)	Helper function to get the stringified qualified name of the function
static java.lang.String	getQualifiedName(com.ensoftcorp.atlas.core.db.graph.Node node)	Helper function to get the stringified qualified name of the function
static java.lang.String	getQualifiedName(com.ensoftcorp.atlas.core.db.graph.Node node, java.lang.String... stopAfterTags)	Helper function to get the stringified qualified name of the class Stop after tags specify parent containers to stop qualifying at (example packages or jars)
static java.lang.String	getQualifiedTypeName(com.ensoftcorp.atlas.core.db.graph.Node type)	Helper function to get the stringified qualified name of the class
static com.ensoftcorp.atlas.core.query.Q	globals(java.lang.String... names)	Returns the nodes representing the global variable(s) given by the parameter list (names).
static com.ensoftcorp.atlas.core.query.Q	graph(com.ensoftcorp.atlas.core.query.Q roots, com.ensoftcorp.atlas.core.query.Q leaves)	Returns the call graph between the functions in (roots) and functions in (leaves)
static com.ensoftcorp.atlas.core.query.Q	induceCFG(com.ensoftcorp.atlas.core.query.Q nodes)	Induces the control-flow edges between the given control-flow blocks in (nodes)
static com.ensoftcorp.atlas.core.query.Q	induceCG(com.ensoftcorp.atlas.core.query.Q functs)	Induces a call edges between the given set of function(s) in (funcs)
static com.ensoftcorp.atlas.core.query.Q	interactions(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q first, com.ensoftcorp.atlas.core.query.Q second, java.lang.String... edgeTags)	Returns direct edges of the given kinds which lay immediately between the first group and second group of nodes.
static com.ensoftcorp.atlas.core.query.Q	interactions(com.ensoftcorp.atlas.core.query.Q first, com.ensoftcorp.atlas.core.query.Q second, java.lang.String... edgeTags)	Returns direct edges of the given kinds which lay immediately between the first group and second group of nodes.
static boolean	isEmpty(com.ensoftcorp.atlas.core.query.Q test)	Returns whether the given Q is empty.
static com.ensoftcorp.atlas.core.db.graph.Node	leastCommonAncestor(com.ensoftcorp.atlas.core.db.graph.Node child1, com.ensoftcorp.atlas.core.db.graph.Node child2, com.ensoftcorp.atlas.core.db.graph.Graph graph)	Returns the least common ancestor of both child1 and child2 within the given graph
static com.ensoftcorp.atlas.core.db.graph.Node	leastCommonAncestor(com.ensoftcorp.atlas.core.db.graph.Node child1, com.ensoftcorp.atlas.core.db.graph.Node child2, com.ensoftcorp.atlas.core.query.Q graph)	Returns the least common ancestor of both child1 and child2 within the given graph
static com.ensoftcorp.atlas.core.query.Q	libraryDeclarations()	Returns those nodes which are declared by a library.
static com.ensoftcorp.atlas.core.query.Q	libraryDeclarations(com.ensoftcorp.atlas.core.query.Q context)	Returns those nodes which are declared by a library.
static com.ensoftcorp.atlas.core.query.Q	libraryDeclarations(com.ensoftcorp.atlas.core.query.Q context, java.lang.String name)	Returns those nodes which are declared by a library with the given name.
static com.ensoftcorp.atlas.core.query.Q	libraryDeclarations(java.lang.String name)	Returns those nodes which are declared by a library with the given name.
static com.ensoftcorp.atlas.core.query.Q	localDeclarations(com.ensoftcorp.atlas.core.query.Q origin)	All nodes declared under the given functions, but NOT declared under additional functions or types.
static com.ensoftcorp.atlas.core.query.Q	localDeclarations(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	All nodes declared under the given functions, but NOT declared under additional functions or types.
static com.ensoftcorp.atlas.core.query.Q	mpg(com.ensoftcorp.atlas.core.query.Q e1Functions, com.ensoftcorp.atlas.core.query.Q e2Functions, com.ensoftcorp.atlas.core.query.Q object)	Returns the Matching Pair Graph for given object and event functions
static com.ensoftcorp.atlas.core.query.Q	mutatedBy(com.ensoftcorp.atlas.core.query.Q mutators, com.ensoftcorp.atlas.core.query.Q origin)	Returns those elements in the origin which were called by or written by elements in the mutators set.
static com.ensoftcorp.atlas.core.query.Q	mutatedBy(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q mutators, com.ensoftcorp.atlas.core.query.Q origin)	Returns those elements in the origin which were called by or written by elements in the mutators set.
static com.ensoftcorp.atlas.core.query.Q	mutators(com.ensoftcorp.atlas.core.query.Q origin)	Given a Q containing functions or data flow nodes, returns a Q of things which write to or call things in the Q.
static com.ensoftcorp.atlas.core.query.Q	mutators(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Given a Q containing functions or data flow nodes, returns a Q of things which write to or call things in the Q.
static com.ensoftcorp.atlas.core.query.Q	nodesContaining(com.ensoftcorp.atlas.core.query.Q context, java.lang.String substring)	Returns the nodes whose names contain the given string within the given context.
static com.ensoftcorp.atlas.core.query.Q	nodesContaining(java.lang.String substring)	Returns the nodes whose names contain the given string.
static com.ensoftcorp.atlas.core.query.Q	nodesEndingWith(com.ensoftcorp.atlas.core.query.Q context, java.lang.String suffix)	Returns the nodes whose names end with the given string within the given context.
static com.ensoftcorp.atlas.core.query.Q	nodesEndingWith(java.lang.String suffix)	Returns the nodes whose names end with the given string.
static long	nodeSize(com.ensoftcorp.atlas.core.query.Q toCount)	Returns the number of nodes contained.
static com.ensoftcorp.atlas.core.query.Q	nodesMatchingRegex(com.ensoftcorp.atlas.core.query.Q context, java.lang.String regex)	Returns the nodes whose names match the given regular expression within the given context.
static com.ensoftcorp.atlas.core.query.Q	nodesMatchingRegex(java.lang.String regex)	Returns the nodes whose names match the given regular expression.
static com.ensoftcorp.atlas.core.query.Q	nodesStartingWith(com.ensoftcorp.atlas.core.query.Q context, java.lang.String prefix)	Returns the nodes whose names start with the given string within the given context.
static com.ensoftcorp.atlas.core.query.Q	nodesStartingWith(java.lang.String prefix)	Returns the nodes whose names start with the given string.
static com.ensoftcorp.atlas.core.query.Q	nodesWithSelfEdges(com.ensoftcorp.atlas.core.query.Q context)	Returns those nodes in the context which have self edges.
static com.ensoftcorp.atlas.core.query.Q	projectDFG(com.ensoftcorp.atlas.core.query.Q dfg, com.ensoftcorp.atlas.core.query.Q func)	Returns the portion of data-flow graph within the given Function
static com.ensoftcorp.atlas.core.query.Q	rcg(com.ensoftcorp.atlas.core.query.Q funcs)	Returns the reverse-call graph of the given function(s) in (funcs)
static com.ensoftcorp.atlas.core.query.Q	readBy(com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes from which nodes in the origin read.
static com.ensoftcorp.atlas.core.query.Q	readBy(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes from which nodes in the origin read.
static com.ensoftcorp.atlas.core.query.Q	readersOf(com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes which directly read from nodes in origin.
static com.ensoftcorp.atlas.core.query.Q	readersOf(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes which directly read from nodes in origin.
static com.ensoftcorp.atlas.core.query.Q	ref(com.ensoftcorp.atlas.core.query.Q object)	Returns the induced call graph of functions referencing (read/write) the given global variables and/or types (structures) given in parameter (object).
static com.ensoftcorp.atlas.core.query.Q	structs(java.lang.String... names)	Returns the nodes representing the structs having the given names.
static com.ensoftcorp.atlas.core.query.Q	typeEdges()	Returns a filter over the edges which describe the type of a Variable or DataFlow_Node.
static com.ensoftcorp.atlas.core.query.Q	typeOf(com.ensoftcorp.atlas.core.query.Q q)	Extends the given graph through the edges describing the type of the nodes.
static com.ensoftcorp.atlas.core.query.Q	types(java.lang.String... names)	Returns the nodes representing the types given by the names.
static com.ensoftcorp.atlas.core.query.Q	writersOf(com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes which directly write to nodes in origin.
static com.ensoftcorp.atlas.core.query.Q	writersOf(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes which directly write to nodes in origin.
static com.ensoftcorp.atlas.core.query.Q	writtenBy(com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes to which nodes in origin write.
static com.ensoftcorp.atlas.core.query.Q	writtenBy(com.ensoftcorp.atlas.core.query.Q context, com.ensoftcorp.atlas.core.query.Q origin)	Returns the nodes to which nodes in origin write.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

declarations

public static com.ensoftcorp.atlas.core.query.Q declarations(com.ensoftcorp.atlas.core.query.Q origin)

Produces a declarations (contains) graph. Equivalent to declarations(index(), origin).

Parameters:

origin -

Returns:

the query expression

declarations

public static com.ensoftcorp.atlas.core.query.Q declarations(com.ensoftcorp.atlas.core.query.Q context,
                                                             com.ensoftcorp.atlas.core.query.Q origin)

Produces a declarations (contains) graph. Uses only the given context for the traversal.

Parameters:

context -

origin -

Returns:

the query expression

interactions

public static com.ensoftcorp.atlas.core.query.Q interactions(com.ensoftcorp.atlas.core.query.Q first,
                                                             com.ensoftcorp.atlas.core.query.Q second,
                                                             java.lang.String... edgeTags)

Returns direct edges of the given kinds which lay immediately between the first group and second group of nodes. In the case that the selected edge kinds have multiple levels of granularity, only the function level of granularity is used.

Parameters:

first -

second -

edgeTags -

Returns:

the query expression

interactions

public static com.ensoftcorp.atlas.core.query.Q interactions(com.ensoftcorp.atlas.core.query.Q context,
                                                             com.ensoftcorp.atlas.core.query.Q first,
                                                             com.ensoftcorp.atlas.core.query.Q second,
                                                             java.lang.String... edgeTags)

Returns direct edges of the given kinds which lay immediately between the first group and second group of nodes. In the case that the selected edge kinds have multiple levels of granularity, only the function level of granularity is used. Uses only the given context for the traversal.

Parameters:

context -

first -

second -

edgeTags -

Returns:

the query expression

libraryDeclarations

public static com.ensoftcorp.atlas.core.query.Q libraryDeclarations()

Returns those nodes which are declared by a library.

Returns:

the query expression

libraryDeclarations

public static com.ensoftcorp.atlas.core.query.Q libraryDeclarations(com.ensoftcorp.atlas.core.query.Q context)

Returns those nodes which are declared by a library. Results are only returned if they are within the given context. Equivalent to libraryDeclarations(index())

Parameters:

context -

Returns:

the query expression

libraryDeclarations

public static com.ensoftcorp.atlas.core.query.Q libraryDeclarations(java.lang.String name)

Returns those nodes which are declared by a library with the given name.

Parameters:

name -

Returns:

the query expression

libraryDeclarations

public static com.ensoftcorp.atlas.core.query.Q libraryDeclarations(com.ensoftcorp.atlas.core.query.Q context,
                                                                    java.lang.String name)

Returns those nodes which are declared by a library with the given name. Results are only returned if they are within the given context. Equivalent to libraryDeclarations(index(), name)

Parameters:

context -

name -

Returns:

the query expression

functionParameter

public static com.ensoftcorp.atlas.core.query.Q functionParameter(com.ensoftcorp.atlas.core.query.Q functions)

Returns the parameters of the given functions. Equivalent to functionParameter(index(), functions)

Parameters:

functions -

Returns:

the query expression

functionParameter

public static com.ensoftcorp.atlas.core.query.Q functionParameter(com.ensoftcorp.atlas.core.query.Q functions,
                                                                  java.lang.Integer... index)

Returns the parameters of the given functions at the given indices. Equivalent to functionParameter(index(), functions, index)

Parameters:

functions -

index -

Returns:

the query expression

functionParameter

public static com.ensoftcorp.atlas.core.query.Q functionParameter(com.ensoftcorp.atlas.core.query.Q context,
                                                                  com.ensoftcorp.atlas.core.query.Q functions)

Returns the parameters of the given functions. Results are only returned if they are within the given context.

Parameters:

context -

functions -

Returns:

the query expression

functionParameter

public static com.ensoftcorp.atlas.core.query.Q functionParameter(com.ensoftcorp.atlas.core.query.Q context,
                                                                  com.ensoftcorp.atlas.core.query.Q functions,
                                                                  java.lang.Integer... index)

Returns the parameters of the given functions at the given indices. Results are only returned if they are within the given context.

Parameters:

context -

functions -

index -

Returns:

the query expression

functionReturn

public static com.ensoftcorp.atlas.core.query.Q functionReturn(com.ensoftcorp.atlas.core.query.Q functions)

Returns the return nodes for the given functions. Equivalent to functionReturn(index(), functions).

Parameters:

functions -

Returns:

the query expression

functionReturn

public static com.ensoftcorp.atlas.core.query.Q functionReturn(com.ensoftcorp.atlas.core.query.Q context,
                                                               com.ensoftcorp.atlas.core.query.Q functions)

Returns the return nodes for the given functions.

Parameters:

context -

functions -

Returns:

the query expression

functionsOf

public static com.ensoftcorp.atlas.core.query.Q functionsOf(com.ensoftcorp.atlas.core.query.Q types)

Returns the functions declared by the given types. Equivalent to functionsOf(index(), types).

Parameters:

params -

Returns:

the query expression

functionsOf

public static com.ensoftcorp.atlas.core.query.Q functionsOf(com.ensoftcorp.atlas.core.query.Q context,
                                                            com.ensoftcorp.atlas.core.query.Q types)

Returns the functions declared by the given types.

Parameters:

context -

types -

Returns:

the query expression

nodesContaining

public static com.ensoftcorp.atlas.core.query.Q nodesContaining(java.lang.String substring)

Returns the nodes whose names contain the given string. Equivalent to nodesContaining(index(), substring).

Parameters:

substring -

Returns:

the query expression

nodesContaining

public static com.ensoftcorp.atlas.core.query.Q nodesContaining(com.ensoftcorp.atlas.core.query.Q context,
                                                                java.lang.String substring)

Returns the nodes whose names contain the given string within the given context.

Parameters:

context -

substring -

Returns:

the query expression

nodesEndingWith

public static com.ensoftcorp.atlas.core.query.Q nodesEndingWith(java.lang.String suffix)

Returns the nodes whose names end with the given string. Equivalent to nodesEndingWith(index(), suffix).

Parameters:

substring -

Returns:

the query expression

nodesEndingWith

public static com.ensoftcorp.atlas.core.query.Q nodesEndingWith(com.ensoftcorp.atlas.core.query.Q context,
                                                                java.lang.String suffix)

Returns the nodes whose names end with the given string within the given context.

Parameters:

context -

substring -

Returns:

the query expression

nodesMatchingRegex

public static com.ensoftcorp.atlas.core.query.Q nodesMatchingRegex(java.lang.String regex)

Returns the nodes whose names match the given regular expression. Equivalent to nodesMatchingRegex(index(), regex).

Parameters:

substring -

Returns:

the query expression

nodesMatchingRegex

public static com.ensoftcorp.atlas.core.query.Q nodesMatchingRegex(com.ensoftcorp.atlas.core.query.Q context,
                                                                   java.lang.String regex)

Returns the nodes whose names match the given regular expression within the given context.

Parameters:

context -

substring -

Returns:

the query expression

nodesStartingWith

public static com.ensoftcorp.atlas.core.query.Q nodesStartingWith(java.lang.String prefix)

Returns the nodes whose names start with the given string. Equivalent to nodesStartingWith(index(), prefix).

Parameters:

substring -

Returns:

the query expression

nodesStartingWith

public static com.ensoftcorp.atlas.core.query.Q nodesStartingWith(com.ensoftcorp.atlas.core.query.Q context,
                                                                  java.lang.String prefix)

Returns the nodes whose names start with the given string within the given context.

Parameters:

context -

substring -

Returns:

the query expression

edgeSize

public static long edgeSize(com.ensoftcorp.atlas.core.query.Q toCount)

Returns the number of edges contained.

Parameters:

toCount -

Returns:

nodeSize

public static long nodeSize(com.ensoftcorp.atlas.core.query.Q toCount)

Returns the number of nodes contained.

Parameters:

toCount -

Returns:

isEmpty

public static boolean isEmpty(com.ensoftcorp.atlas.core.query.Q test)

Returns whether the given Q is empty.

Parameters:

test -

Returns:

getGraphElementByAddress

public static com.ensoftcorp.atlas.core.db.graph.GraphElement getGraphElementByAddress(java.lang.String address)

Selects the Atlas graph element given a serialized graph element address Returns null if the address does not correspond to a graph element

Parameters:

address -

Returns:

getNodeByAddress

public static com.ensoftcorp.atlas.core.db.graph.Node getNodeByAddress(java.lang.String address)

Selects the Atlas node graph element given a serialized graph element address Returns null if the address does not correspond to a node

Parameters:

address -

Returns:

getEdgeByAddress

public static com.ensoftcorp.atlas.core.db.graph.Edge getEdgeByAddress(java.lang.String address)

Selects the Atlas edge graph element given a serialized graph element address Returns null if the address does not correspond to a edge

Parameters:

address -

Returns:

localDeclarations

public static com.ensoftcorp.atlas.core.query.Q localDeclarations(com.ensoftcorp.atlas.core.query.Q origin)

All nodes declared under the given functions, but NOT declared under additional functions or types. Retrieves declarations of only this function. Results are only returned if they are within the given context.

Parameters:

origin -

Returns:

localDeclarations

public static com.ensoftcorp.atlas.core.query.Q localDeclarations(com.ensoftcorp.atlas.core.query.Q context,
                                                                  com.ensoftcorp.atlas.core.query.Q origin)

All nodes declared under the given functions, but NOT declared under additional functions or types. Retrieves declarations of only this function. Results are only returned if they are within the given context.

Parameters:

context -

origin -

Returns:

callers

public static com.ensoftcorp.atlas.core.query.Q callers(com.ensoftcorp.atlas.core.query.Q origin)

Returns the direct callers of the given functions. Operates in the index context.

Parameters:

origin -

Returns:

callers

public static com.ensoftcorp.atlas.core.query.Q callers(com.ensoftcorp.atlas.core.query.Q context,
                                                        com.ensoftcorp.atlas.core.query.Q origin)

Returns the direct callers of the given functions. Operates in the given context.

Parameters:

context -

origin -

Returns:

called

public static com.ensoftcorp.atlas.core.query.Q called(com.ensoftcorp.atlas.core.query.Q origin)

Returns the subset of the given functions which are called. Operates in the index context.

Parameters:

origin -

Returns:

called

public static com.ensoftcorp.atlas.core.query.Q called(com.ensoftcorp.atlas.core.query.Q context,
                                                       com.ensoftcorp.atlas.core.query.Q origin)

Returns the subset of the given functions which are called. Results are only returned if they are within the given context.

Parameters:

context -

origin -

Returns:

calledBy

public static com.ensoftcorp.atlas.core.query.Q calledBy(com.ensoftcorp.atlas.core.query.Q callers,
                                                         com.ensoftcorp.atlas.core.query.Q called)

Returns the given functions which were called by the given callers. Operates in the index context.

Parameters:

callers -

called -

Returns:

calledBy

public static com.ensoftcorp.atlas.core.query.Q calledBy(com.ensoftcorp.atlas.core.query.Q context,
                                                         com.ensoftcorp.atlas.core.query.Q callers,
                                                         com.ensoftcorp.atlas.core.query.Q called)

Returns the given functions which were called by the given callers. Results are only returned if they are within the given context.

Parameters:

context -

callers -

called -

Returns:

dfg

public static com.ensoftcorp.atlas.core.query.Q dfg(com.ensoftcorp.atlas.core.query.Q functions)

Parameters:

functions -

Returns:

the data flow graph under the function

dfg

public static com.ensoftcorp.atlas.core.query.Q dfg(com.ensoftcorp.atlas.core.db.graph.Node function)

Parameters:

function -

Returns:

the data flow graph under the function

cfg

public static com.ensoftcorp.atlas.core.query.Q cfg(com.ensoftcorp.atlas.core.query.Q functions)

Parameters:

functions -

Returns:

the control flow graph under the function

cfg

public static com.ensoftcorp.atlas.core.query.Q cfg(com.ensoftcorp.atlas.core.db.graph.Node function)

Parameters:

function -

Returns:

the control flow graph under the function

excfg

public static com.ensoftcorp.atlas.core.query.Q excfg(com.ensoftcorp.atlas.core.query.Q functions)

Parameters:

functions -

Returns:

the control flow graph (including exceptional control flow) under the function

excfg

public static com.ensoftcorp.atlas.core.query.Q excfg(com.ensoftcorp.atlas.core.db.graph.Node function)

Parameters:

function -

Returns:

the control flow graph (including exceptional control flow) under the function

firstDeclarator

public static com.ensoftcorp.atlas.core.query.Q firstDeclarator(com.ensoftcorp.atlas.core.query.Q declared,
                                                                java.lang.String... declaratorTypes)

Returns the first declaring node of the given Q which is tagged with one of the given types. Operates in the index context.

Parameters:

declared -

declaratorTypes -

Returns:

firstDeclarator

public static com.ensoftcorp.atlas.core.query.Q firstDeclarator(com.ensoftcorp.atlas.core.query.Q context,
                                                                com.ensoftcorp.atlas.core.query.Q declared,
                                                                java.lang.String... declaratorTypes)

Returns the first declaring node of the given Q which is tagged with one of the given types. Results are only returned if they are within the given context.

Parameters:

context -

declared -

declaratorTypes -

Returns:

advancedIntersection

public static com.ensoftcorp.atlas.core.query.Q advancedIntersection(com.ensoftcorp.atlas.core.query.Q first,
                                                                     com.ensoftcorp.atlas.core.query.Q second,
                                                                     java.lang.String[] nodeTags,
                                                                     java.lang.String[] edgeTags)

Given two query expressions, intersects the given node and edge kinds to produce a new expression.

Parameters:

first -

second -

nodeTags -

edgeTags -

Returns:

readersOf

public static com.ensoftcorp.atlas.core.query.Q readersOf(com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes which directly read from nodes in origin. Operates in the index context.

Parameters:

origin -

Returns:

readersOf

public static com.ensoftcorp.atlas.core.query.Q readersOf(com.ensoftcorp.atlas.core.query.Q context,
                                                          com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes which directly read from nodes in origin. Operates in the given context.

Parameters:

context -

origin -

Returns:

writersOf

public static com.ensoftcorp.atlas.core.query.Q writersOf(com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes which directly write to nodes in origin. Operates in the index context.

Parameters:

origin -

Returns:

writersOf

public static com.ensoftcorp.atlas.core.query.Q writersOf(com.ensoftcorp.atlas.core.query.Q context,
                                                          com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes which directly write to nodes in origin. Operates in the given context.

Parameters:

context -

origin -

Returns:

readBy

public static com.ensoftcorp.atlas.core.query.Q readBy(com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes from which nodes in the origin read. Operates in the index context.

Parameters:

origin -

Returns:

readBy

public static com.ensoftcorp.atlas.core.query.Q readBy(com.ensoftcorp.atlas.core.query.Q context,
                                                       com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes from which nodes in the origin read. Operates in the given context.

Parameters:

context -

origin -

Returns:

writtenBy

public static com.ensoftcorp.atlas.core.query.Q writtenBy(com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes to which nodes in origin write. Operates in the index context.

Parameters:

origin -

Returns:

writtenBy

public static com.ensoftcorp.atlas.core.query.Q writtenBy(com.ensoftcorp.atlas.core.query.Q context,
                                                          com.ensoftcorp.atlas.core.query.Q origin)

Returns the nodes to which nodes in origin write. Operates in the given context.

Parameters:

context -

origin -

Returns:

leastCommonAncestor

public static com.ensoftcorp.atlas.core.db.graph.Node leastCommonAncestor(com.ensoftcorp.atlas.core.db.graph.Node child1,
                                                                          com.ensoftcorp.atlas.core.db.graph.Node child2,
                                                                          com.ensoftcorp.atlas.core.db.graph.Graph graph)

Returns the least common ancestor of both child1 and child2 within the given graph

Parameters:

child1 -

child2 -

graph -

Returns:

leastCommonAncestor

public static com.ensoftcorp.atlas.core.db.graph.Node leastCommonAncestor(com.ensoftcorp.atlas.core.db.graph.Node child1,
                                                                          com.ensoftcorp.atlas.core.db.graph.Node child2,
                                                                          com.ensoftcorp.atlas.core.query.Q graph)

Returns the least common ancestor of both child1 and child2 within the given graph

Parameters:

child1 -

child2 -

graph -

Returns:

getContainingFunctions

public static com.ensoftcorp.atlas.core.query.Q getContainingFunctions(com.ensoftcorp.atlas.core.query.Q nodes)

Returns the containing function of a given Q or empty if one is not found

Parameters:

nodes -

Returns:

getContainingControlFlowNode

public static com.ensoftcorp.atlas.core.db.graph.Node getContainingControlFlowNode(com.ensoftcorp.atlas.core.db.graph.Node node)

Returns the nearest parent that is a control flow node

Parameters:

node -

Returns:

getContainingFunction

public static com.ensoftcorp.atlas.core.db.graph.Node getContainingFunction(com.ensoftcorp.atlas.core.db.graph.Node node)

Returns the containing function of a given graph element or null if one is not found

Parameters:

node -

Returns:

getContainingNode

public static com.ensoftcorp.atlas.core.db.graph.Node getContainingNode(com.ensoftcorp.atlas.core.db.graph.Node node,
                                                                        java.lang.String containingTag)

Find the next immediate containing node with the given tag.

Parameters:

node -

containingTag -

Returns:

the next immediate containing node, or null if none exists; never returns the given node

conditionsAbove

public static com.ensoftcorp.atlas.core.query.Q conditionsAbove(com.ensoftcorp.atlas.core.query.Q origin)

Returns the control flow graph between conditional nodes and the given origin. Operates within the index context.

Parameters:

origin -

Returns:

conditionsAbove

public static com.ensoftcorp.atlas.core.query.Q conditionsAbove(com.ensoftcorp.atlas.core.query.Q context,
                                                                com.ensoftcorp.atlas.core.query.Q origin)

Returns the control flow graph between conditional nodes and the given origin. Operates within the given context.

Parameters:

context -

origin -

Returns:

mutators

public static com.ensoftcorp.atlas.core.query.Q mutators(com.ensoftcorp.atlas.core.query.Q origin)

Given a Q containing functions or data flow nodes, returns a Q of things which write to or call things in the Q. Operates within the index context.

Parameters:

origin -

Returns:

nodesWithSelfEdges

public static com.ensoftcorp.atlas.core.query.Q nodesWithSelfEdges(com.ensoftcorp.atlas.core.query.Q context)

Returns those nodes in the context which have self edges.

Parameters:

context -

Returns:

mutators

public static com.ensoftcorp.atlas.core.query.Q mutators(com.ensoftcorp.atlas.core.query.Q context,
                                                         com.ensoftcorp.atlas.core.query.Q origin)

Given a Q containing functions or data flow nodes, returns a Q of things which write to or call things in the Q. Operates within the index context.

Parameters:

context -

origin -

Returns:

mutatedBy

public static com.ensoftcorp.atlas.core.query.Q mutatedBy(com.ensoftcorp.atlas.core.query.Q mutators,
                                                          com.ensoftcorp.atlas.core.query.Q origin)

Returns those elements in the origin which were called by or written by elements in the mutators set. Operates within the index context.

Parameters:

mutators -

origin -

Returns:

mutatedBy

public static com.ensoftcorp.atlas.core.query.Q mutatedBy(com.ensoftcorp.atlas.core.query.Q context,
                                                          com.ensoftcorp.atlas.core.query.Q mutators,
                                                          com.ensoftcorp.atlas.core.query.Q origin)

Returns those elements in the origin which were called by or written by elements in the mutators set. Operates within the given context.

Parameters:

context -

mutators -

origin -

Returns:

getQualifiedTypeName

public static java.lang.String getQualifiedTypeName(com.ensoftcorp.atlas.core.db.graph.Node type)

Helper function to get the stringified qualified name of the class

Parameters:

function -

Returns:

getQualifiedFunctionName

public static java.lang.String getQualifiedFunctionName(com.ensoftcorp.atlas.core.db.graph.Node function)

Helper function to get the stringified qualified name of the function

Parameters:

function -

Returns:

getQualifiedName

public static java.lang.String getQualifiedName(com.ensoftcorp.atlas.core.db.graph.Node node)

Helper function to get the stringified qualified name of the function

Parameters:

function -

Returns:

getQualifiedName

public static java.lang.String getQualifiedName(com.ensoftcorp.atlas.core.db.graph.Node node,
                                                java.lang.String... stopAfterTags)

Helper function to get the stringified qualified name of the class Stop after tags specify parent containers to stop qualifying at (example packages or jars)

Parameters:

function -

Returns:

typeEdges

public static com.ensoftcorp.atlas.core.query.Q typeEdges()

Returns a filter over the edges which describe the type of a Variable or DataFlow_Node.

Returns:

functions

public static com.ensoftcorp.atlas.core.query.Q functions(java.lang.String... functionNames)

Returns the set of functions where their names matches the any of the names given (functionNames) list. A (*) in (functionNames) represents a wildcard that matches any string.

Parameters:

functionNames - : A list of function names as Strings

Returns:

A set of functions

globals

public static com.ensoftcorp.atlas.core.query.Q globals(java.lang.String... names)

Returns the nodes representing the global variable(s) given by the parameter list (names). A (*) in any string in the list (names) represents a wildcard that matches any string.

Parameters:

names - : A list of global variable names as Strings

Returns:

A set of global variable nodes

types

public static com.ensoftcorp.atlas.core.query.Q types(java.lang.String... names)

Returns the nodes representing the types given by the names. A (*) is a wildcard that matches any string.

Parameters:

names - A list of type names; structs must be prefixed with "struct "

Returns:

A set of global variable nodes

structs

public static com.ensoftcorp.atlas.core.query.Q structs(java.lang.String... names)

Returns the nodes representing the structs having the given names.

The name is automatically prefixed with "struct ". A (*) in name represents a wildcard that matches any string.

Examples:

• structs("iblk")
• structs("*bl*k*")
• structs("pentry","bpool")

Parameters:

names - list of struct names

Returns:

XCSG.C.Struct nodes

ref

public static com.ensoftcorp.atlas.core.query.Q ref(com.ensoftcorp.atlas.core.query.Q object)

Returns the induced call graph of functions referencing (read/write) the given global variables and/or types (structures) given in parameter (object).

Parameters:

object - : the set of global variables and/or types

Returns:

A set of type/structure/global variable nodes

cfg

public static com.ensoftcorp.atlas.core.query.Q cfg(java.lang.String funcName)

Returns the control-flow graph (CFG) of the given function name in (funcName)

Parameters:

funcName - : function name as a String

Returns:

the CFG of the given function

cg

public static com.ensoftcorp.atlas.core.query.Q cg(com.ensoftcorp.atlas.core.query.Q funcs)

Returns the call graph of the given function(s) in (funcs)

Parameters:

funcs - : function node(s)

Returns:

The call graph of given function(s)

rcg

public static com.ensoftcorp.atlas.core.query.Q rcg(com.ensoftcorp.atlas.core.query.Q funcs)

Returns the reverse-call graph of the given function(s) in (funcs)

Parameters:

funcs - : function node(s)

Returns:

The reverse call graph of given function(s)

call

public static com.ensoftcorp.atlas.core.query.Q call(com.ensoftcorp.atlas.core.query.Q funcs)

Returns the set of function directly calling a given function(s)

Parameters:

functs - : function node(s)

Returns:

direct callers of given function(s)

calledBy

public static com.ensoftcorp.atlas.core.query.Q calledBy(com.ensoftcorp.atlas.core.query.Q funcs)

Returns the set of functions that are directly called by given function(s)

Parameters:

functs - : function node(s)

Returns:

direct callees by given function(s)

graph

public static com.ensoftcorp.atlas.core.query.Q graph(com.ensoftcorp.atlas.core.query.Q roots,
                                                      com.ensoftcorp.atlas.core.query.Q leaves)

Returns the call graph between the functions in (roots) and functions in (leaves)

Parameters:

roots - : function node(s)

leaves - : function node(s)

Returns:

a call graph

induceCG

public static com.ensoftcorp.atlas.core.query.Q induceCG(com.ensoftcorp.atlas.core.query.Q functs)

Induces a call edges between the given set of function(s) in (funcs)

Parameters:

functs - : function node(s)

induceCFG

public static com.ensoftcorp.atlas.core.query.Q induceCFG(com.ensoftcorp.atlas.core.query.Q nodes)

Induces the control-flow edges between the given control-flow blocks in (nodes)

Parameters:

nodes - : control-flow node(s)

mpg

public static com.ensoftcorp.atlas.core.query.Q mpg(com.ensoftcorp.atlas.core.query.Q e1Functions,
                                                    com.ensoftcorp.atlas.core.query.Q e2Functions,
                                                    com.ensoftcorp.atlas.core.query.Q object)

Returns the Matching Pair Graph for given object and event functions

Parameters:

e1Functions - : L function node(s)

e2Functions - : U function node(s)

object - : type node

Returns:

the matching pair graph for object (object)

projectDFG

public static com.ensoftcorp.atlas.core.query.Q projectDFG(com.ensoftcorp.atlas.core.query.Q dfg,
                                                           com.ensoftcorp.atlas.core.query.Q func)

Returns the portion of data-flow graph within the given Function

Parameters:

dfg - A previously computed data-flow graph

func - Function node(s)

Returns:

intra-procedural data-flow graph

forwardProjection

public static com.ensoftcorp.atlas.core.query.Q forwardProjection(com.ensoftcorp.atlas.core.query.Q projection,
                                                                  com.ensoftcorp.atlas.core.query.Q node)

Returns the intra-procedural forward data-flow graph starting at the given node within the projection

Parameters:

projection - data-flow graph

node - where the flow starts

Returns:

a forward data-flow graph from the selected node

dfg

public static com.ensoftcorp.atlas.core.query.Q dfg(java.lang.String functionContext,
                                                    java.lang.String functionSource,
                                                    java.lang.String functionSink)

Returns the forward data-flow graph starting at the return value of Function "functionSource" in the context of Function "functionContext". The flow continues until it reaches a parameter of Function "functionSink".

In Xinu, try: dfg("dsread", "getbuf", "freebuf")

Parameters:

functionContext - caller of functionSource

functionSource - return value to use as origin in data-flow graph

functionSink - stopping point for data-flow graph

file

public static com.ensoftcorp.atlas.core.query.Q file(java.lang.String path)

Returns Types, GlobalVariables, Functions, and Macros with source correspondence matching the given path. Wildcards are allowed. Paths are always normalized to use / as a directory separator. Paths are always assumed to start with a wildcard (to avoid needing to include the full project path).

Examples:

• file("open.c") -- any file ending with open.c
• file("/open.c") -- exactly files named open.c
• file("/dg*.c") -- any file starting with dg and ending with .c

Parameters:

path -

Returns:

getContainingFunction

public static com.ensoftcorp.atlas.core.query.Q getContainingFunction(com.ensoftcorp.atlas.core.query.Q nodes)

Returns the Functions containing the given nodes (if any). Not all nodes are nested under a Function.

Parameters:

nodes -

Returns:

Functions containing the given nodes

typeOf

public static com.ensoftcorp.atlas.core.query.Q typeOf(com.ensoftcorp.atlas.core.query.Q q)

Extends the given graph through the edges describing the type of the nodes.

Parameters:

q -

Returns:

The given graph extended along the type edges.

See Also:

typeEdges()

functionPtr

public static com.ensoftcorp.atlas.core.query.Q functionPtr()

Selects all functions, and one step of data flow for the capture of the address of a function.

Returns: