fnsearch(1) (man pages section 1: User Commands)

man pages section 1: User Commands

fnsearch(1)

NAME

fnsearch– search for FNS objects with specified attributes

SYNOPSIS

fnsearch

-AlLv

-n

max

-s

scope

composite_name

-a

ident

-O

-U

filter_expr

filter_arg

DESCRIPTION

The fnsearch command operation displays the names and, optionally, the attributes and references of objects bound at or below composite_name whose attributes satisfy a given filter expression. The filter expression is given in terms of logical expressions involving the identifiers and values of the attributes and references of objects examined during the search.

For general information about FNS, see fns(5).

OPTIONS

The following options are supported:

-a ident

Display the given attribute of each object that satisfies the filter expression. If the -a option is not used, all attributes are displayed. An empty ident (" " from the shell) indicates that no attributes are to be displayed. Multiple -a options may be given. The syntax of ident is described fully under Displaying Selected Attributes below.

-A

Consult the authoritative source(s) for information.

-l

Display the reference of each object that satisfies the filter expression.

-L

Follow XFN links during the search.

-n max

Restrict the maximum number of objects displayed to the given number (a positive integer). There is no limit by default.

-s scope

Set the scope of the search. scope is one of:

· object: Only the object composite_name is searched.
· context: Objects bound directly to composite_name are searched.
· subtree: Objects bound to composite_name or any of its subcontexts are searched.
· constrained_subtree: Like subtree, but the search may be restricted to a set of subcontexts defined in a context-implementation-defined manner

scope may be abbreviated to any unambiguous prefix, such as o or cont. If this option is not given, the default behavior is -s context.

-v

Display in detail the reference of each object that satisfies the filter expression. This option takes precedence over -l.

OPERANDS

The following operand is supported:

composite_name: An FNS named object.

USAGE

Simple Filter Expressions

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.

Logical Operators

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.

Relational Operators

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.

Displaying Selected Attributes

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"

Filter Arguments

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

Wildcarded Strings

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 Operations

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"

Grammar of Filter Expressions

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

EXIT STATUS

0: Operation was successful.
1: Operation failed.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWfns

NOTES

If the filter expression is empty, it evaluates to TRUE (all objects satisfy it).

If the identifier in any subexpression of the filter expression does not exist as an attribute of an object, then the innermost logical expression containing that identifier evaluates to FALSE.

SunOS 5.9 Last Revised 21 Jul 1996