manpages.info - online man pages   

SunOS man pages : fnsearch (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 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. SunOS 5.8 Last change: 21 Jul 1996 1 User Commands fnsearch(1) 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: SunOS 5.8 Last change: 21 Jul 1996 2 User Commands fnsearch(1) % 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 SunOS 5.8 Last change: 21 Jul 1996 3 User Commands fnsearch(1) 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 SunOS 5.8 Last change: 21 Jul 1996 4 User Commands fnsearch(1) 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" SunOS 5.8 Last change: 21 Jul 1996 5 User Commands fnsearch(1) '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. SunOS 5.8 Last change: 21 Jul 1996 6 User Commands fnsearch(1) 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 ::= SunOS 5.8 Last change: 21 Jul 1996 7 User Commands fnsearch(1) "'" 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. SunOS 5.8 Last change: 21 Jul 1996 8