Browsing Source With `sbquery`

25

This chapter describes one of the command-line utilities for browsing source code. The sbquery command provides you with a command-line browsing environment that you can access from terminals and from workstations emulating terminals.

The information contained in this chapter pertains mainly to the use of the command line to complete tasks also available from within WorkShop. For more conceptual information on using source browsing, see the online help.

This chapter is organized into the following sections:

Basic Concepts

page 335

Command Reference

page 336

Basic Concepts	page 335
Command Reference	page 336

Basic Concepts

The command-line interface to the Source Browsing mode of WorkShop is sbquery.

To issue a query from the command line:

Type sbquery, followed by any command-line options and their arguments, followed by the symbol you want to search for.

sbquery [options] symbols

All lines that contain symbols are displayed.

sbquery displays a list of matches that includes the file in which the symbol appears, the line number, the function containing the symbol, and the source line containing the symbol.

By default, sbquery searches for symbols in the database in the current working directory. If you want to browse a database stored in another directory, see Chapter 26, "Controlling the Browser Database With .sbinit."

Command Reference

To obtain a list of the sbquery command-line options:

Type sbquery at the shell prompt.
Two types of options are available to help you narrow your search: filter options and focus options. The filter options are used to search for symbols based on how they are used in a program. For example, you could limit your search to declarations of variables. The focus options limit your search to specific classes of code, such as particular programs, functions, or libraries.

Arguments
Description

-break_lock

Breaks the lock on a locked database. This argument might be needed if the update of the index file is aborted, the next time you issue a query you might get a message telling you that the database is locked.
After using this option, your database may be in an inconsistent state. To ensure consistency, remove the .sb subdirectory and recompile your program.

-help

Displays a synopsis of the sbquery command. Equivalent to typing sbquery with no options.

-help_focus

Displays a list of the focus options available for querying only specific program types in a directory. Use focus options to issue a query limited to specific units of code such as programs or functions.

-help_filter

Displays a list of the languages for which filter options are available. Use filtering options to search for symbols based on how they are used in a program.

-max_memory <size>

Sets the approximate amount of memory, in megabytes, that should be allocated before sbquery uses temporary files when building the index file.

-no_update

Doesn't rebuild the index file when you issue a query following compilation. If you do not include this option and issue a query following compilation or recompilation, then the database updates and processes your query.

-o <file>

Sends query output to a file.

-show_db_dirs

Lists all .sb directories scanned when you issue a query. The list includes the following:
the .sb directory in the current working directory and all other .sb directories specified by the import or export commands in your .sbinit file.

-version | -V

Displays the current version number.

-files_only

Lists only the files where the symbols you are searching for appear.

-no_secondaries

Returns only the primary match. A secondary match is an identifier inside a macro. You might want to turn off secondary matches if you are doing a lot of filtered querying, and the symbols you are querying on are used in a lot of macros.

-no_source

Displays only the file name and line number associated with each match.

-symbols_only

Displays a list of all symbols that match the patterns in your search pattern. Useful when you use wildcards in a query.

-pattern <sym>

Queries on symbol, which may contain special characters, including a leading dash (-). This option allows you to query on a symbol that looks like a command-line option. For instance, you can query on the symbol -help, and sbquery distinguishes it from the regular option -help.

-no_case

Makes the query case-insensitive.

-sh_pattern

Use shell-style expressions when issuing a query that includes wildcards. This wildcard setting is the default; include this option if you are doing other pattern matching on the same command line.
See sh(1) for more information about shell-style pattern matching.

-reg_expr

Use regular expressions when issuing a query that includes wildcards. If you do not include this option, shell-style patterns are assumed.

-literal

Do not use any wildcard expressions for the query. Useful when you want to search for a string that contains meta characters from other wildcard schemes.

Arguments	Description
`-break_lock`	Breaks the lock on a locked database. This argument might be needed if the update of the index file is aborted, the next time you issue a query you might get a message telling you that the database is locked. After using this option, your database may be in an inconsistent state. To ensure consistency, remove the `.sb` subdirectory and recompile your program.
`-help`	Displays a synopsis of the `sbquery` command. Equivalent to typing `sbquery` with no options.
`-help_focus`	Displays a list of the focus options available for querying only specific program types in a directory. Use focus options to issue a query limited to specific units of code such as programs or functions.
`-help_filter`	Displays a list of the languages for which filter options are available. Use filtering options to search for symbols based on how they are used in a program.
`-max_memory <size>`	Sets the approximate amount of memory, in megabytes, that should be allocated before `sbquery` uses temporary files when building the index file.
`-no_update`	Doesn't rebuild the index file when you issue a query following compilation. If you do not include this option and issue a query following compilation or recompilation, then the database updates and processes your query.
`-o <file>`	Sends query output to a file.
`-show_db_dirs`	Lists all `.sb` directories scanned when you issue a query. The list includes the following: the `.sb` directory in the current working directory and all other `.sb` directories specified by the `import` or `export` commands in your `.sbinit` file.
`-version \| -V`	Displays the current version number.
`-files_only`	Lists only the files where the symbols you are searching for appear.
`-no_secondaries`	Returns only the primary match. A secondary match is an identifier inside a macro. You might want to turn off secondary matches if you are doing a lot of filtered querying, and the symbols you are querying on are used in a lot of macros.
`-no_source`	Displays only the file name and line number associated with each match.
`-symbols_only`	Displays a list of all symbols that match the patterns in your search pattern. Useful when you use wildcards in a query.
`-pattern <sym>`	Queries on `symbol`, which may contain special characters, including a leading dash (-). This option allows you to query on a symbol that looks like a command-line option. For instance, you can query on the symbol `-help`, and `sbquery` distinguishes it from the regular option `-help`.
`-no_case`	Makes the query case-insensitive.
`-sh_pattern`	Use shell-style expressions when issuing a query that includes wildcards. This wildcard setting is the default; include this option if you are doing other pattern matching on the same command line. See `sh`(1) for more information about shell-style pattern matching.
`-reg_expr`	Use regular expressions when issuing a query that includes wildcards. If you do not include this option, shell-style patterns are assumed.
`-literal`	Do not use any wildcard expressions for the query. Useful when you want to search for a string that contains meta characters from other wildcard schemes.

Filter Language Options


`sbquery -help_filter` language

Options

ansi_c

sun_as

sun_c_plus_plus

sun_f77

sun_pascal

Options
`ansi_c`
`sun_as`
`sun_c_plus_plus`
`sun_f77`
`sun_pascal`

Focus Options


`sbquery` focus_option symbol

Focus Option
Description

-in_program Program

Limit query to matches in program.

-in_directory Directory

Limit query to matches in directory.

-in_source_file Source_File

Limit query to matches in source_file.

-in_function Function

Limit query to matches in function.

-in_class Class

Limit query to matches in class.

-in_template Template

Limit query to matches in template.

-in_language Language

Limit query to matches in language.

Focus Option	Description
`-in_program` Program	Limit query to matches in program.
`-in_directory` Directory	Limit query to matches in directory.
`-in_source_file` Source_File	Limit query to matches in source_file.
`-in_function` Function	Limit query to matches in function.
`-in_class` Class	Limit query to matches in class.
`-in_template` Template	Limit query to matches in template.
`-in_language` Language	Limit query to matches in language.

Note - If you include two or more focus options, a match is returned if it is found with any of the supplied focus options.

Environment Variables

Environment variables provide information that affects the operation of sbquery (and of source browsing in WorkShop). For more information on .sbinit, see Chapter 26, "Controlling the Browser Database With .sbinit."


Variable	Description
`HOME`	The name of your login directory.
`PWD`	The full path name of the current directory.
`SUNPRO_SB_ATTEMPTS_MAX`	The maximum number of times the index builder tries to access a locked database.
`SUNPRO_SB_EX_FILE_NAME`	The absolute pathname of the file `sun_source_browser.ex`.
`SUNPRO_SB_INIT_FILE_NAME`	The absolute pathname of the `.sbinit` file.

Browsing Source With sbquery

25

Basic Concepts

Command Reference

Filter Language Options sbquery -help_filter language Options ansi_c sun_as sun_c_plus_plus sun_f77 sun_pascal

Environment Variables

Browsing Source With `sbquery`

Filter Language Options

`sbquery -help_filter` language

Options

`ansi_c`

`sun_as`

`sun_c_plus_plus`

`sun_f77`

`sun_pascal`