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 satis-
fies 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 syn-
tax 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:
o object
Only the object composite_name is searched.
o context
Objects bound directly to composite_name are searched.
o subtree
Objects bound to composite_name or any of its subcon-
texts are searched.
o 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 sin-
gle 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 pre-
cedence:
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 cri-
teria. 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 attri-
bute 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 sub-
stitution 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 gen-
erated 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 argu-
ment 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 sub-
string "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 expres-
sion. 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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWfns |
|_____________________________|_____________________________|
SEE ALSO
printf(1), FN_search_control_t(3XFN),
FN_search_filter_t(3XFN), fn_attr_ext_search(3XFN),
fn_attr_search(3XFN), attributes(5), fns(5)
NOTES
If the filter expression is empty, it evaluates to TRUE (all
objects satisfy it).
If the identifier in any subexpression of the filter expres-
sion does not exist as an attribute of an object, then the
innermost logical expression containing that identifier
evaluates to FALSE.
Man(1) output converted with
man2html