.Dd July 11, 2012

.Op Fl r Ar repo

.Op Fl S Ar search

.Op Fl L Ar label

.Op Fl M Ar mod

.Ar pattern

.Op Fl r Ar repo

.Ar pattern

The output may be modified to additionally show many other package

data available from the repository catalogues.

.It Fl c

Search for packages with comment text matching

.Ar pattern .

Equivalent to

.Fl "S comment" . 

.It Fl D

Display the list of packages depended on by each matched package.

Equivalent to

.Fl "M depends-on" .

.It Fl d

Search for packages with description text matching

.Ar pattern .

Equivalent to

.Fl "S description" .

should be an exact match against the search field.

.It Fl f

Show ``full'' information about the package.

Equivalent to

.Fl "M full" . 

as a shell globbing expression.

The glob pattern must match the entire field being seached.

.It Fl L Ar label

Select which identifying label is printed for each matched package,

unless

.Fl q

is used.

Several different fields from the repository catalogue database may be

used to search on, or to generate the label, as indicated by the

.Ar label

argument.

See the 

.Qq Sx Search and Label Options

section for details.

If unspecified,

.Ar label

is set to the same as the value searched via the

.Fl S Ar search

option.

.It Fl M Ar mod

Modify the output by adding an additional field to the result.

Multiple fields can be added by using additional

.Fl M Ar mod

flags.  See the

.Qq Sx Output Modifier Options

section for details.

.It Fl o

List packages by origin for each package matching

.Ar pattern .

Equivalent to

.Fl "L origin" .

.It Fl p

Display the package installation prefix for each matched package.

Equivalent to

.Fl "M prefix" . 

.It Fl q

Be ``quiet''.

Produce less output.

In particular don't show an identifying label field for each package.

.It Fl r Ar repo

In multi-repo mode, select only the repository catalogue from

.Sy repo

to search.

By default all known repository catalogues are searched.

.It Fl S Ar search

Specify the field to search the repository catalogue on.

If unspecified, searches on

.Ar pkg-name

unless the search term contains a 

.Sy /

character, when it searches on port

.Ar origin .

Output will be sorted in order of the

.Ar search

field.

See the

.Qq Sx Search and Label Options

sections for more details.

.It Fl s

Display the installed size of matched packages.

Equivalent to

.Fl "M size" . 

Matches any substring of the search field unless explicit beginning

or ending anchor terms are used.

.It Fl x

Treat

as a regular expression.  This is the default.

Matches any substring of the search field unless explicit beginning

or ending anchor terms are used.

.El

.Ss Search and Label Options

The following database fields (or composites of several fields) can

be used both for searching for a match to the given

and as identifying labels for the block of output for each package.

.Bl -tag -width 2n

.It Sy comment

The one line comment field describing the port, derived from the

.Cm COMMENT

variable in the port's

.Fa Makefile .

When chosen as a label option, the output format will additionally

include the packge name, equivalent to

.Fl "L pkg-name"

.Fl "M comment" .

When chosen as a search option, only the

.Sy comment

field is used for sorting the output.

.It Sy description

The multi-line package description from the

.Fa pkg-descr

file in the port.

This does include the

.Cm WWW

URL reference, if any, from that file.

When chosen as a label option, the output format will additionally

include the package name, equivalent to

.Fl "L pkg-name"

.Fl "M description" .

When chosen as a search option, only the

.Sy description

field is used for sorting the output.

.It Sy name

The name of the package, derived from the

.Cm PORTNAME

variable in the port's

.Fa Makefile .

.It Sy origin

The port origin, in the format

.Fa category/port ,

that the package was compiled from.

.It Sy pkg-name

The package name in the format

.Sy name Ns - Ns Cm version .

The same as the

.Cm PKGNAME

variable in the port's

.Fa Makefile .

.Pp

Any unambiguous prefix of the label name may be used on the command line.

Thus

.Fl "Sd" ,

.Fl "S descr"

and

.Fl "S description"

are all equivalent.

.Ss Output Modifier Options

Additional data from the repository catalogue to print for each matched

package.

Multiple output modifiers can be combined.

Where more than one output field is required, either because multiple

.Fl M Ar mod

options were given, or one or more

.Fl M Ar mod

option was combined with the

.Fl "L comment"

or

.Fl "L description"

options, then each output field will be tagged with the field name.

.Bl -tag -width 2n

.It Sy arch

The architecture string indicating what OS version and CPU architecture

the package is suitable for.  For example,

.Ar freebsd:9:x86:64

indicates a package suitable for FreeBSD 9.x running on an amd64 processor,

while

.Ar freebsd:*

indicates an architecture independent package suitable for any version of

FreeBSD.

.It Sy categories

All categories, real and virtual, the underlying package belongs to,

derived from the

.Cm CATEGORIES

variable in the port's

.Fa Makefile .

.It Sy comment

The one line comment field describing the port, derived from the

.Cm COMMENT

variable in the port's

.Fa Makefile .

.It Sy depends-on

The list of packages the named package depends on.

Dependency packages are listed in the format

.Sy name Ns - Ns Cm version

one per line.

If the port has no dependencies, nothing will be output for

this field, including suppressing the tag name when multiple

output fields are requested.

.It Sy description

The multi-line package description from the

.Fa pkg-descr

file in the port.

This does include the

.Cm WWW

URL reference, if any, from that file.

.It Sy full

Show a standard set of fields, equivalent to a combination of the

.Sy name ,

.Sy version ,

.Sy origin ,

.Sy prefix ,

.Sy repository ,

.Sy categories ,

.Sy license ,

.Sy maintainer ,

.Sy www ,

.Sy comment ,

.Sy options ,

.Sy shared-libs ,

.Sy size ,

.Sy pkg-size

and

.Sy descr

fields, in that order.

.It Sy licenses

Displays a list of all the licenses the package is relesed under on a

single line.

Where more than one license applies, indicate if the terms of all

licenses should apply

.Sy (&)

or if one or more licenses may be selected out of those available

.Sy (|) .

.It Sy maintainer

Display the maintainer's e-mail address.

.It Sy name

Display the port name, which is derived from the

.Cm PORTNAME

variable in the port's

.Fa Makefile .

.It Sy options

Displays a list of the port options and their state (

.Sy on

or

.Sy off )

when the package was built.

If the package does not have any options to set, nothing will be

output for this field, including suppressing the tag name when

multiple output fields are requested.

.It Sy pkg-size

Display the size of the compressed package tarball, ie. how much would

need to be downloaded from the repository.

.It Sy prefix

Display the installation prefix for the package, usually

.Fa /usr/local .

.It Sy repository

Displays the repository label and the corresponding base Url for the

repository.

In multi-repo mode, the repository label and URL are one of the pairs

defined in

.Fa pkg.conf .  

In normal mode the label is always ``remote'', and the URL is the

value of

.Cm PACKAGESITE .

.It Sy required-by

Displays all of the packages in the repository that require the named

package as a dependency.

Dependency packages are listed in the format

.Sy name Ns - Ns Cm version

one per line.

If the no other packages require the named package, nothing will be

output for this field, including suppressing the tag name when

multiple output fields are requested.

.It Sy shared-libs

If the package contains dynamically linked FreeBSD ELF binaries,

display a list of all of the shared libraries other than those from

the base system required for those binaries to run.

Shared libraries for foreign (eg. Linux) binaries run

under emulation will not be displayed.

If the package does not require any shared libraries, nothing will be

output for this field including suppressing the tag name when multiple

fields are requested.

.It Sy size

Display the total amount of filesystem space the package files will

take up once unpacked and installed.

.It Sy url

Display the URL that would be used to download the package from the

repository.

.It Sy www

Display the general URL, if any, for the project developing the

software used in the package.

This is extracted from the

.Fa pkg-descr

file in the port. 

.El

.Pp

Any unambiguous prefix of the modifier name may be used on the command

line.

Thus

.Fl "Mm" ,

.Fl "M maint"

and

.Fl "M maintainer"

are all equivalent,

but you need to use at least

.Fl "M si"

and

.Fl "M sh"

to distinguish

.Cm size

from

.Cm shared-libs .

.It Ev PKG_DBDIR