1  .\"
  2  .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3  .\" of non-core utilities.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\" 1. Redistributions of source code must retain the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer.
 10  .\" 2. Redistributions in binary form must reproduce the above copyright
 11  .\"    notice, this list of conditions and the following disclaimer in the
 12  .\"    documentation and/or other materials provided with the distribution.
 13  .\"
 14  .\"
 15  .\"     @(#)pkg.8
 16  .\"
 17  .Dd July 7, 2024
 18  .Dt PKG-RQUERY 8
 19  .Os
 20  .Sh NAME
 21  .Nm "pkg rquery"
 22  .Nd query information from remote repositories
 23  .Sh SYNOPSIS
 24  .Nm
 25  .Fl I Ns | Ns Ar query-format
 26  .Ar pkg-name
 27  .Nm
 28  .Op Fl aU
 29  .Op Fl r Ar reponame ...
 30  .Fl I Ns | Ns Ar query-format
 31  .Nm
 32  .Op Fl U
 33  .Op Fl Cgix
 34  .Op Fl e Ar evaluation-condition
 35  .Op Fl r Ar reponame ...
 36  .Fl I Ns | Ns Ar query-format
 37  .Ar pattern ...
 38  .Sh DESCRIPTION
 39  .Nm
 40  is used for displaying information about remote packages.
 41  .Pp
 42  Package repository catalogues will be automatically updated whenever
 43  .Nm
 44  is run by a user ID with write access to the package database,
 45  unless disabled by the
 46  .Fl U
 47  flag or setting
 48  .Va REPO_AUTOUPDATE
 49  to
 50  .Dq Li NO
 51  in
 52  .Xr pkg.conf 5 .
 53  .Sh OPTIONS
 54  The following options are supported by
 55  .Nm :
 56  .Bl -tag -width Ds
 57  .It Fl a , Fl -all
 58  Match all packages from the database.
 59  .It Fl C , Fl -case-sensitive
 60  Make the standard or the regular expression
 61  .Pq Fl x
 62  matching against
 63  .Ar pkg-name
 64  in pattern case sensitive.
 65  .It Fl e Ar evaluation-condition , Fl -evaluate Ar evaluation-condition
 66  Match packages using the given
 67  .Ar evaluation-condition .
 68  See
 69  .Sx EVALUATION FORMAT
 70  for details.
 71  .It Fl I , Fl -index-line
 72  Print out the corresponding line from the ports
 73  .Pa INDEX
 74  file for each matched package.
 75  This option is a shorthand
 76  .Ar query-format
 77  argument.
 78  Only the first query format (including the
 79  .Fl I
 80  option) on the command line will be interpreted.
 81  .It Fl r Ar reponame , Fl -repository Ar reponame
 82  Query for data about packages from only the named repository.
 83  This option can be specified multiple times to use several repositories.
 84  Data will be queried from the named repositories only, irrespective of the configured
 85  .Dq enabled
 86  status from
 87  .Pa repo.conf .
 88  By default, catalogues for all enabled repositories are queried.
 89  .It Fl g , Fl -glob
 90  Treat
 91  .Ar pattern
 92  as a glob pattern.
 93  .It Fl i , Fl -case-insensitive
 94  Make the standard or regular expression
 95  .Pq Fl x
 96  matching against
 97  .Ar pkg-name
 98  in pattern case insensitive.
 99  This is the default, unless modified by setting
100  .Va CASE_SENSITIVE_MATCH
101  to
102  .Dq Li true
103  in
104  .Pa pkg.conf .
105  .It Fl U , Fl -no-repo-update
106  Suppress the automatic update of the local copy of the repository catalogue
107  from remote.
108  Automatic repository catalogue updates are only attempted when the
109  effective UID of the process has write access to the package database.
110  Otherwise they are silently ignored.
111  .It Fl x , Fl -regex
112  Treat
113  .Ar pattern
114  as a regular expression according to the
115  .Dq modern
116  or
117  .Dq extended
118  syntax of
119  .Xr re_format 7 .
120  .El
121  .Sh QUERY FORMAT
122  There are two types of keywords for the query format: the multiline and the
123  normal one.
124  Only one type of multiline pattern is accepted for a given query.
125  .Ss Normal patterns:
126  .Bl -tag -width Ds
127  .It Cm \&%R
128  Name of the repository the package is in
129  .It Cm \&%n
130  Name of the matched package
131  .It Cm \&%v
132  Version of the matched package
133  .It Cm \&%o
134  Origin of the matched package
135  .It Cm \&%p
136  Prefix of the matched package
137  .It Cm \&%m
138  Maintainer of the matched package
139  .It Cm \&%c
140  Comment of the matched package
141  .It Cm \&%e
142  Description of the matched package
143  .It Cm \&%w
144  Home page of the matched package
145  .It Cm \&%q
146  Architecture of the matched package
147  .It Cm \&%l
148  License logic of the matched package
149  .Pp
150  One of the following will be printed:
151  .Bl -tag -width " single " -compact
152  .It Dq single
153  if the package is distributed under one license
154  .It Dq and
155  if the package is multi-licensed
156  .It Dq or
157  if the package is dual-licensed
158  .El
159  .It Cm \&%s Ns Op Cm bh
160  The flat size of the matched package, where
161  .Cm b
162  is in bytes, and
163  .Cm h
164  is in human readable format
165  .It Cm \&%M
166  Message contained in the matched package
167  .It Cm \&%? Ns Op Cm drCOLBbA
168  Returns 0 if the list is empty and 1 if the list has information to display
169  .Bl -tag -width "d"
170  .It Cm d
171  for dependencies
172  .It Cm r
173  for reverse dependencies
174  .It Cm C
175  for categories
176  .It Cm O
177  for options
178  .It Cm L
179  for licenses
180  .It Cm B
181  for required shared libraries
182  .It Cm b
183  for provided shared libraries
184  .It Cm A
185  for annotations
186  .El
187  .It Cm \&%# Ns Op Cm drCOLBbA
188  Returns the number of elements in the list
189  .Bl -tag -width "d"
190  .It Cm d
191  for dependencies
192  .It Cm r
193  for reverse dependencies
194  .It Cm C
195  for categories
196  .It Cm O
197  for options
198  .It Cm L
199  for licenses
200  .It Cm B
201  for required shared libraries
202  .It Cm b
203  for provided shared libraries
204  .It Cm A
205  for annotations
206  .El
207  .El
208  .Ss Multiline patterns:
209  .Bl -tag -width Ds
210  .It Cm \&%d Ns Op Cm nov
211  Expands to the list of dependencies for the matched package, where
212  .Cm n
213  stands for the package name,
214  .Cm o
215  for the package origin, and
216  .Cm v
217  for the package version.
218  .It Cm \&%r Ns Op Cm nov
219  Expands to the list of reverse dependencies for the matched package, where
220  .Cm n
221  stands for the package name,
222  .Cm o
223  for the package origin, and
224  .Cm v
225  for the package version.
226  .It Cm \&%C
227  Expands to the list of categories the matched package belongs to.
228  .It Cm \&%O Ns Op Cm kvdD
229  Expands to the list of options of the matched package, where
230  .Cm k
231  stands for option key
232  .Cm v
233  for option value,
234  .Cm d
235  for option default value, and
236  .Cm D
237  for option description.
238  Option default values and descriptions are optional metadata and may
239  be blank for certain packages or repositories.
240  .It Cm \&%L
241  Expands to the list of license(s) for the matched package.
242  .It Cm \&%B
243  Expands to the list of shared libraries used by programs from the matched package.
244  .It Cm \&%b
245  Expands to the list of shared libraries provided by the matched package.
246  .It Cm \&%A Ns Op Cm tv
247  Expands to the list of annotations associated with the matched
248  package, where
249  .Cm t
250  stands for the annotation tag, and
251  .Cm v
252  stands for the annotation value.
253  .El
254  .Sh EVALUATION FORMAT
255  .Ss Variables
256  .Bl -tag -width Ds
257  .It Cm \&%n
258  Name of the package (type string)
259  .It Cm \&%o
260  Origin of the package (type string)
261  .It Cm \&%p
262  Prefix of the package (type string)
263  .It Cm \&%m
264  Maintainer of the package (type string)
265  .It Cm \&%c
266  Comment of the package (type string)
267  .It Cm \&%e
268  Description of the package (type string)
269  .It Cm \&%w
270  WWW address of the package (type string)
271  .It Cm \&%s
272  Flatsize of the package (type integer)
273  .It Cm \&%a
274  Automatic status of the package (type integer)
275  .It Cm \&%q
276  Architecture of the package (type string)
277  .It Cm \&%M
278  Message of the package (type string)
279  .It Cm \&%# Ns Op drCOLBbA
280  Number of elements in the list of information (type integer).
281  See
282  .Cm %?
283  above for what information is used.
284  .El
285  .Ss Operators
286  .Bl -tag -width Ds
287  .It Va var Cm ~ Ar glob
288  The string value of
289  .Va var
290  matches the given glob pattern.
291  .It Va var Cm !~ Ar glob
292  The string value of
293  .Va var
294  does not match the given glob pattern.
295  .It Va var Cm > Ns Oo = Oc Ar num
296  The numerical value of
297  .Va var
298  is greater than
299  .Op or equal to
300  the given number.
301  .It Va var Cm < Ns Oo = Oc Ar num
302  The numerical value of
303  .Va var
304  is less than
305  .Op or equal to
306  the given number.
307  .It Va var Cm = Ns Oo = Oc Oo Ar num | Ar string Oc
308  The value of
309  .Va var
310  is equal to the given number or string.
311  .It Va var Cm =~ Oo Ar num | Ar string Oc
312  The value of
313  .Va var
314  is equal (case insensitive) to the given number or string.
315  .It Va var Cm != Oo Ar num | Ar string Oc
316  The value of
317  .Va var
318  is not equal to the given number or string.
319  .It Va var Cm !=~  Oo Ar num | Ar string Oc
320  The value of
321  .Va var
322  is not equal case insensitive to the given number or string.
323  .El
324  .Sh ENVIRONMENT
325  The following environment variables affect the execution of
326  .Nm .
327  See
328  .Xr pkg.conf 5
329  for further description.
330  .Bl -tag -width Ds
331  .It Ev PKG_DBDIR
332  .It Ev CASE_SENSITIVE_MATCH
333  .El
334  .Sh FILES
335  See
336  .Xr pkg.conf 5 .
337  .Sh EXIT STATUS
338  .Ex -std
339  .Sh EXAMPLES
340  See
341  .Xr pkg-query 8
342  for example usage.
343  .Sh SEE ALSO
344  .Xr pkg_create 3 ,
345  .Xr pkg_printf 3 ,
346  .Xr pkg_repo_create 3 ,
347  .Xr pkg_repos 3 ,
348  .Xr pkg-keywords 5 ,
349  .Xr pkg-lua-script 5 ,
350  .Xr pkg-repository 5 ,
351  .Xr pkg-script 5 ,
352  .Xr pkg-triggers 5 ,
353  .Xr pkg.conf 5 ,
354  .Xr pkg 8 ,
355  .Xr pkg-add 8 ,
356  .Xr pkg-alias 8 ,
357  .Xr pkg-annotate 8 ,
358  .Xr pkg-audit 8 ,
359  .Xr pkg-autoremove 8 ,
360  .Xr pkg-check 8 ,
361  .Xr pkg-clean 8 ,
362  .Xr pkg-config 8 ,
363  .Xr pkg-create 8 ,
364  .Xr pkg-delete 8 ,
365  .Xr pkg-fetch 8 ,
366  .Xr pkg-help 8 ,
367  .Xr pkg-info 8 ,
368  .Xr pkg-install 8 ,
369  .Xr pkg-key 8 ,
370  .Xr pkg-lock 8 ,
371  .Xr pkg-plugins 8 ,
372  .Xr pkg-query 8 ,
373  .Xr pkg-register 8 ,
374  .Xr pkg-repo 8 ,
375  .Xr pkg-repositories 8 ,
376  .Xr pkg-search 8 ,
377  .Xr pkg-set 8 ,
378  .Xr pkg-shell 8 ,
379  .Xr pkg-shlib 8 ,
380  .Xr pkg-ssh 8 ,
381  .Xr pkg-stats 8 ,
382  .Xr pkg-triggers 8 ,
383  .Xr pkg-unregister 8 ,
384  .Xr pkg-update 8 ,
385  .Xr pkg-updating 8 ,
386  .Xr pkg-upgrade 8 ,
387  .Xr pkg-version 8 ,
388  .Xr pkg-which 8