| blob | df22fbf626aaf1891829e6f87f865a9d9de11cb2 |
1 .\" $NetBSD: pkg_info.1,v 1.24 2009/03/02 17:13:49 joerg Exp $
2 .\"
3 .\" FreeBSD install - a package for the installation and maintenance
4 .\" of non-core utilities.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" Jordan K. Hubbard
16 .\"
17 .\"
18 .\" @(#)pkg_info.1
19 .\"
20 .Dd March 2, 2009
21 .Dt PKG_INFO 1
22 .Os
23 .Sh NAME
24 .Nm pkg_info
25 .Nd a utility for displaying information on software packages
26 .Sh SYNOPSIS
27 .Nm
28 .Op Fl BbcDdFfhIikLmNnpqrRSsVvX
29 .Op Fl e Ar package
30 .Op Fl E Ar package
31 .Op Fl K Ar pkg_dbdir
32 .Op Fl l Ar prefix
33 .Ar pkg-name ...
34 .Nm
35 .Op Fl a | Fl u
36 .Op flags
37 .Nm
38 .Op Fl Q Ar variable
39 .Ar pkg-name ...
40 .Sh DESCRIPTION
41 The
42 .Nm
43 command is used to dump out information for packages, which may be either
44 packed up in files or already installed on the system with the
45 .Xr pkg_create 1
46 command.
47 .Pp
48 The
49 .Ar pkg-name
50 may be the name of an installed package (with our without version), a
51 pattern matching several installed packages (see the
52 .Sx PACKAGE WILDCARDS
53 section for a description of possible patterns),
54 the pathname to a
55 binary package, a filename belonging to an installed
56 package (if
57 .Fl F
58 is also given), or a URL to an ftp-available package.
59 .Pp
60 The following command-line options are supported:
61 .Bl -tag -width indent
62 .It Fl a
63 Show information for all currently installed packages.
64 See also
65 .Fl u .
66 .It Fl B
67 Show some of the important definitions used when building
68 the binary package (the
69 .Dq Build information )
70 for each package.
71 Additionally, any installation information variables
72 (lowercase) can be queried, too.
73 In particular,
74 .Ar automatic
75 tells if a package was installed automatically
76 as a dependency of another package.
77 .It Fl b
78 Show the
79 .Nx
80 RCS Id strings from the files used in the construction
81 of the binary package (the "Build version") for each package.
82 These files are the package Makefile, any patch files, any checksum
83 files, and the packing list file.
84 .It Fl c
85 Show the one-line comment field for each package.
86 .It Fl D
87 Show the install-message file (if any) for each package.
88 .It Fl d
89 Show the long-description field for each package.
90 .It Fl E Ar pkg-name
91 This option
92 allows you to test for the existence of a given package.
93 If a package identified by
94 .Ar pkg-name
95 is currently installed, return code is 0, otherwise 1.
96 The name of the best matching package found installed is printed to
97 stdout unless turned off using the
98 .Fl q
99 option.
100 .Ar pkg-name
101 can contain wildcards (see the
102 .Sx PACKAGE WILDCARDS
103 section below).
104 .It Fl e Ar pkg-name
105 This option
106 allows you to test for the existence of a given package.
107 If a package identified by
108 .Ar pkg-name
109 is currently installed, return code is 0, otherwise 1.
110 The names of any package(s) found installed are printed to
111 stdout unless turned off using the
112 .Fl q
113 option.
114 .Ar pkg-name
115 can contain wildcards (see the
116 .Sx PACKAGE WILDCARDS
117 section below).
118 .It Fl F
119 Interpret any pkg-name given as filename, and translate it to a
120 package name using the Package Database.
121 This can be used to query information on a per-file basis, e.g. in
122 conjunction with the
123 .Fl e
124 flag to find out which package a file belongs to.
125 .It Fl f
126 Show the packing list instructions for each package.
127 .It Fl I
128 Show the index entry for each package.
129 .It Fl i
130 Show the install script (if any) for each package.
131 .It Fl K Ar pkg_dbdir
132 Set
133 .Ar pkg_dbdir
134 as the package database directory.
135 If this option isn't specified, then the package database directory is
136 taken from the value of the environment variable
137 .Ev PKG_DBDIR
138 if it's set, otherwise it defaults to
139 .Pa /var/db/pkg .
140 .It Fl k
141 Show the de-install script (if any) for each package.
142 .It Fl L
143 Show the files within each package.
144 This is different from just viewing the packing list, since full pathnames
145 for everything are generated.
146 Files that were created dynamically during installation of the package
147 are not listed.
148 .It Fl l Ar str
149 Prefix each information category header (see
150 .Fl q )
151 shown with
152 .Ar str .
153 This is primarily of use to front-end programs that want to request a
154 lot of different information fields at once for a package, but don't
155 necessary want the output intermingled in such a way that they can't
156 organize it.
157 This lets you add a special token to the start of each field.
158 .It Fl m
159 Show the mtree file (if any) for each package.
160 .It Fl N
161 Show which packages each package was built with (exact dependencies), if any.
162 .It Fl n
163 Show which packages each package needs (depends upon), if any.
164 .It Fl p
165 Show the installation prefix for each package.
166 .It Fl Q
167 Show the definition of
168 .Ar variable
169 from the build information for each package.
170 An empty string is returned if no such variable definition is found for
171 the package(s).
172 .It Fl q
173 Be
174 .Dq quiet
175 in emitting report headers and such, just dump the
176 raw info (basically, assume a non-human reading).
177 .It Fl R
178 For each package, show the packages that require it.
179 .It Fl r
180 For each package, show the packages that require it.
181 Continue recursively to show all dependents.
182 .It Fl S
183 Show the size of this package and all the packages it requires,
184 in bytes.
185 .It Fl s
186 Show the size of this package in bytes.
187 The size is calculated by adding up the size of each file of the package.
188 .It Fl u
189 Show information for all user-installed packages.
190 Automatically installed packages (as dependencies
191 of other packages) are not displayed.
192 See also
193 .Fl a .
194 .It Fl V
195 Print version number and exit.
196 .It Fl v
197 Turn on verbose output.
198 .It Fl X
199 Print summary information for each package.
200 The summary format is
201 described in
202 .Xr pkg_summary 5 .
203 Its primary use is to contain all information about the contents of a
204 (remote) binary package repository needed by package managing software.
205 .El
206 .Sh TECHNICAL DETAILS
207 Package info is either extracted from package files named on the
208 command line, or from already installed package information
209 in
210 .Pa /var/db/pkg/\*[Lt]pkg-name\*[Gt] .
211 .Pp
212 A filename can be given instead of a (installed) package name to query
213 information on the package this file belongs to.
214 This filename is then resolved to a package name using the Package Database.
215 For this translation to take place, the
216 .Fl F
217 flag must be given.
218 The filename must be absolute, compare the output of pkg_info
219 .Fl aF .
220 .Sh PACKAGE WILDCARDS
221 In the places where a package name/version is expected, e.g. for the
222 .Fl e
223 switch, several forms can be used.
224 Either use a package name with or without version, or specify a
225 package wildcard that gets matched against all installed packages.
226 .Pp
227 Package wildcards use
228 .Xr fnmatch 3 .
229 In addition,
230 .Xr csh 1
231 style {,} alternates have been implemented.
232 Package version numbers can also be matched in a relational manner
233 using the
234 .Pa \*[Ge] , \*[Le] , \*[Gt] ,
235 and
236 .Pa \*[Lt]
237 operators.
238 For example,
239 .Pa pkg_info -e 'name\*[Ge]1.3'
240 will match versions 1.3 and later of the
241 .Pa name
242 package.
243 Additionally, ranges can be defined by giving a lower bound with
244 \*[Gt] or \*[Ge] and an upper bound with \*[Lt] or \*[Le].
245 The lower bound has to come first.
246 For example,
247 .Pa pkg_info -e 'name\*[Ge]1.3\*[Lt]2.0'
248 will match versions 1.3 (inclusive) to 2.0 (exclusive)
249 of package
250 .Pa name .
251 .Pp
252 The collating sequence of the various package version numbers is
253 unusual, but strives to be consistent.
254 The magic string
255 .Dq alpha
256 equates to
257 .Pa alpha version
258 and sorts before a beta version.
259 The magic string
260 .Dq beta
261 equates to
262 .Pa beta version
263 and sorts before a release candidate.
264 The magic string
265 .Dq rc
266 equates to
267 .Pa release candidate
268 and sorts before a release.
269 The magic string
270 .Dq pre ,
271 short for
272 .Dq pre-release ,
273 is a synonym for
274 .Dq rc .
275 For example,
276 .Pa name-1.3rc3
277 will sort before
278 .Pa name-1.3
279 and after
280 .Pa name-1.2.9 .
281 Similarly
282 .Pa name-1.3alpha2
283 will sort before
284 .Pa name-1.3beta1
285 and they both sort before
286 .Pa name-1.3rc1 .
287 In addition, alphabetic characters sort in the same place as
288 their numeric counterparts, so that
289 .Pa name-1.2e
290 has the same sorting value as
291 .Pa name-1.2.5
292 The magic string
293 .Dq pl
294 equates to a
295 .Pa patch level
296 and has the same value as a dot in the dewey-decimal ordering schemes.
297 .Sh ENVIRONMENT
298 .Bl -tag -width PKG_DBDIR
299 .It Ev PKG_DBDIR
300 If the
301 .Fl K
302 flag isn't given, then
303 .Ev PKG_DBDIR
304 is the location of the package database directory.
305 The default package database directory is
306 .Pa /var/db/pkg .
307 .El
308 .Sh SEE ALSO
309 .Xr pkg_add 1 ,
310 .Xr pkg_admin 1 ,
311 .Xr pkg_create 1 ,
312 .Xr pkg_delete 1 ,
313 .Xr mktemp 3 ,
314 .Xr pkgsrc 7 ,
315 .Xr mtree 8
316 .Sh AUTHORS
317 .Bl -tag -width indent -compact
318 .It "Jordan Hubbard"
319 most of the work
320 .It "John Kohl"
321 refined it for
322 .Nx
323 .It "Hubert Feyrer"
324 .Nx
325 wildcard dependency processing, pkgdb, depends displaying,
326 pkg size display etc.
327 .El