The simplest form of filter expression is one that tests for the existence of an attribute. This expression is formed simply by giving the attribute's name. To search for objects having an attribute named for_sale, for example:

% fnsearch composite_name for_sale

Another simple filter expression is one that tests the value of a particular attribute. To find objects whose ages are less than 17:

% fnsearch composite_name "age < 17"

String values are indicated by enclosing the string in single quotes. To find all red objects:

% fnsearch composite_name "color == 'red'"

Note that the double quotes (") in this example are not part of the filter expression. Instead, they prevent the shell from interpreting the white-space and single quotes that are part of the expression.

Simple filter expressions may be composed using the logical operators and, or, and not. For example:

% fnsearch composite_name "age >= 35 and us_citizen"

Parentheses may be used to group expressions:

% fnsearch composite_name "not (make == 'olds' and year == 1973)"

The precedence of operators is, in order of increasing precedence:

or and not relational operators (see Relational Operators below)

The logical operators and and or are left-associative.

The following are the relational operators that may be used to compare an attribute to a supplied value:

==

True if at least one value of the attribute is equal to the supplied value.

!=

True if none of the attribute's values are equal to the supplied value.

<

True if at least one value of the attribute is less than the supplied value.

<=

True if at least one value of the attribute is less than or equal to the supplied value.

>

True if at least one value of the attribute is greater than the supplied value.

>=

True if at least one value of the attribute is greater than or equal to the supplied value.

~=

True if at least one value of the attribute matches the supplied value according to some context-specific approximate matching criterion. This criterion must subsume strict equality.

Comparisons and ordering are specific to the syntax or rules of the attribute being tested.

By default, the fnsearch command displays the names and all of the attributes of each object matching the search criteria. The list of attributes displayed may be restricted by using the -a command line option. In the following example, only the color and shape attributes of small objects are displayed:

% fnsearch composite_name -a color -a shape "size == 'small'"

The format of an attribute identifier is taken to be FN_ID_STRING (an ASCII string) by default. To name an attribute identifier that is an OSI OID or a DCE UUID , the attribute name is prefixed by -O or -U, respectively:

-O

The identifier format is FN_ID_ISO_OID_STRING, an ASN.1 dot-separated integer list string.

-U

The identifier format is FN_ID_DCE_UUID, a DCE UUID in string form.

For example:

% fnsearch composite_name -a -O 2.5.4.0 "shoe_size < 9"

and

% fnsearch composite_name -a -U 0006a446-5e97-105f-9828-8190285baa77 \ "bowling_avg > 200"

Some parts of a filter expression may be replaced by a substitution token: a percent sign (%) followed by a single character. The value of this portion of the expression is then given in a filter argument that follows the filter expression, in much the same way as is done in printf(1). The available substitution tokens are:

%a

attribute

%s

string

%i

identifier

%v

attribute value (the only syntax currently supported is fn_attr_syntax_ascii)

For example, the command:

% fnsearch composite_name "color == 'red'"

could equivalently be written:

% fnsearch composite_name "%a == 'red'" color

or:

% fnsearch composite_name "%a == %s" color red

The use of substitution tokens is helpful when writing shell scripts in which the values of the filter arguments are generated at run-time.

By default, the format of the identifier of an attribute such as the color attribute above is taken to be FN_ID_STRING (an ASCII string). Substitution tokens enable the use of OSI OIDs and DCE UUIDs instead. The filter argument is prefixed by -O or -U, with the same meaning as in the -a command line option described above:

-O

The identifier format is FN_ID_ISO_OID_STRING, an ASN.1 dot-separated integer list string.

-U

The identifier format is FN_ID_DCE_UUID, a DCE UUID in string form.

For example:

% fnsearch composite_name "%a -O 2.5.4.0

and

% fnsearch composite_name "%a" =='red'" \ -U 0006a446-5e97-105f-9828-8190285baa77

A wildcarded string consists of a sequence of alternating wildcard specifiers and strings. The wildcard specifiers is denoted by the asterisk (*) and means zero or more occurrences of any character.

Wildcarded strings are used to specify substring matches. The following are some examples of wildcarded strings and their meanings.

*

any string

'tom'

the string "tom"

'harv'*

any string starting with "harv"

*'ing'

any string ending with "ing"

'a'*'b'

any string starting with "a" and ending with "b"

'jo'*'ph'*'ne'*'er'

any string starting with "jo" and containing the substring "ph", and which contains the substring "ne" in the portion of the string following "ph", and which ends with "er"

%s*

any string starting with the string supplied as a filter argument

'bix'*%s

any string starting with "bix" and ending with the string supplied as a filter argument

Extended operators are predicates (functions that return TRUE or FALSE) that may be freely mixed with other operators in a filter expression.

An extended operation is specified by giving the operation name as a quoted string, followed by an argument in parentheses. The following three extended operations are currently defined:

'name'(WildcardedString)

TRUE if the name of the object matches the supplied wildcarded string.

'reftype'(Identifier)

TRUE if the reference type of the object is equal to the supplied identifier.

'addrtype'(Identifier)

TRUE if any of the address types in the reference of the object are equal to the supplied identifier.

The following example shows a search for objects whose names start with bill and having IQ attributes over 80:

% fnsearch composite_name "'name'('bill'*) and IQ > 80"

The complete grammar of filter expressions is given below. It is based on the grammar defined by the XFN specification (see FN_search_filter_t(3XFN)).

String literals in this grammar are enclosed in double quotes; the quotes are not themselves part of the expression. Braces are used for grouping; brackets indicate optional elements. An unquoted asterisk (*) signifies zero or more occurrences of the preceding element; a plus sign (+) signifies one or more occurrences.

FilterExpr ::=

[Expr]

Expr ::=

Expr "or" Expr | Expr "and" Expr | "not" Expr | "(" Expr ")" | Attribute [RelOp Value] | Ext

RelOp ::=

"==" | "!=" | "<" | "<=" | ">" | ">=" | "~="

Attribute ::=

Char* | "%a"

Value ::=

Integer | WildcardedString | "%v"

WildcardedString ::=

"*" | String | {String "*"}+ [String] | {"*" String}+ ["*"] (that is, an alternating sequence of String and "*")

String ::=

"'" Char* "'" | "%s"

Ext ::=

"'name'(" WildcardedString ")" | "'reftype'(" Identifier ")" | "'addrtype'(" Identifier ")"

Identifier ::=

"'" Char* "'" | "%i"

Char ::=

an element of the Portable Character Set (ASCII) | a character in the repertoire of a string representation