Subject: pkg/6005: pkg_info and its docs are out of sync
To: None <gnats-bugs@gnats.netbsd.org>
From: None <jbernard@ox.mines.edu>
List: netbsd-bugs
Date: 08/22/1998 18:10:12
>Number: 6005
>Category: pkg
>Synopsis: pkg_info and its docs are out of sync
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: gnats-admin (GNATS administrator)
>State: open
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Sat Aug 22 17:20:01 1998
>Last-Modified:
>Originator: Jim Bernard
>Organization:
Speaking for myself
>Release: August 22, 1998
>Environment:
System: NetBSD zoo 1.3F NetBSD 1.3F (ZOO) #0: Sun Jun 14 09:09:08 MDT 1998 local@zoo:/home/local/compile/sys/arch/i386/compile/ZOO i386
>Description:
pkg_info has undocumented options (-I, -R), and a documented option
that isn't supported (-t). Both the man page and the usage()
message are out of sync with the code.
>How-To-Repeat:
Read the man page and the code.
>Fix:
In the file usr.sbin/pkg_install/info/main.c, I removed all residual
support for -t (which was unsupported by virtue of being omitted
from the getopt string, could not work if added to the getopt string
without substantial code changes, provides a facility already handled
better by a couple of environment variables, and that facility has
almost negligible probability of ever being needed for the purpose
for which it was provided). I also sorted the getopt string and
the switch that decodes the options, and updated the usage() message
to match.
In the file usr.sbin/pkg_install/info/pkg_info.1, I removed mention
of -t, added entries for -I and -R, removed the OPTIONS section
heading, moved the discussion of pkg_name from the options list to
the general description at the top, sorted the options, added an
ENVIRONMENT section, and cleaned up a bunch of nits here and there,
including updating the date. I did not change the OS--should it be
changed?
--- main.c-dist Tue Jan 13 08:29:27 1998
+++ main.c Sat Aug 22 16:52:39 1998
@@ -32,11 +32,11 @@
#include <err.h>
#include "lib.h"
#include "info.h"
-static char Options[] = "acdDe:fikrRpLqImvhl:";
+static char Options[] = "acDde:fIikLl:mpqRrvh";
int Flags = 0;
Boolean AllInstalled = FALSE;
Boolean Quiet = FALSE;
char *InfoPrefix = "";
@@ -56,86 +56,82 @@
switch(ch) {
case 'a':
AllInstalled = TRUE;
break;
- case 'v':
- Verbose = TRUE;
- /* Reasonable definition of 'everything' */
- Flags = SHOW_COMMENT | SHOW_DESC | SHOW_PLIST | SHOW_INSTALL |
- SHOW_DEINSTALL | SHOW_REQUIRE | SHOW_DISPLAY | SHOW_MTREE;
- break;
-
- case 'I':
- Flags |= SHOW_INDEX;
- break;
-
- case 'p':
- Flags |= SHOW_PREFIX;
- break;
-
case 'c':
Flags |= SHOW_COMMENT;
break;
+ case 'D':
+ Flags |= SHOW_DISPLAY;
+ break;
+
case 'd':
Flags |= SHOW_DESC;
break;
- case 'D':
- Flags |= SHOW_DISPLAY;
+ case 'e':
+ CheckPkg = optarg;
break;
case 'f':
Flags |= SHOW_PLIST;
break;
+ case 'I':
+ Flags |= SHOW_INDEX;
+ break;
+
case 'i':
Flags |= SHOW_INSTALL;
break;
case 'k':
Flags |= SHOW_DEINSTALL;
break;
- case 'r':
- Flags |= SHOW_REQUIRE;
- break;
-
- case 'R':
- Flags |= SHOW_REQBY;
- break;
-
case 'L':
Flags |= SHOW_FILES;
break;
+ case 'l':
+ InfoPrefix = optarg;
+ break;
+
case 'm':
Flags |= SHOW_MTREE;
break;
- case 'l':
- InfoPrefix = optarg;
+ case 'p':
+ Flags |= SHOW_PREFIX;
break;
case 'q':
Quiet = TRUE;
break;
- case 't':
- strcpy(PlayPen, optarg);
+ case 'R':
+ Flags |= SHOW_REQBY;
break;
- case 'e':
- CheckPkg = optarg;
+ case 'r':
+ Flags |= SHOW_REQUIRE;
+ break;
+
+ case 'v':
+ Verbose = TRUE;
+ /* Reasonable definition of 'everything' */
+ Flags = SHOW_COMMENT | SHOW_DESC | SHOW_PLIST | SHOW_INSTALL |
+ SHOW_DEINSTALL | SHOW_REQUIRE | SHOW_DISPLAY | SHOW_MTREE;
break;
case 'h':
case '?':
default:
usage();
- break;
+ /* NOTREACHED */
}
argc -= optind;
argv += optind;
@@ -162,10 +158,10 @@
static void
usage()
{
fprintf(stderr, "%s\n%s\n%s\n",
- "usage: pkg_info [-cdDikrRpLqImv] [-e package] [-l prefix]",
+ "usage: pkg_info [-cDdfIikLmpqRrvh] [-e package] [-l prefix]",
" pkg-name [pkg-name ...]",
" pkg_info -a [flags]");
exit(1);
}
--- pkg_info.1-dist Fri Jul 10 05:17:07 1998
+++ pkg_info.1 Sat Aug 22 17:17:49 1998
@@ -15,116 +15,143 @@
.\" Jordan K. Hubbard
.\"
.\"
.\" @(#)pkg_info.1
.\"
-.Dd November 25, 1994
-.Dt pkg_info 1
+.Dd August 22, 1998
+.Dt PKG_INFO 1
.Os FreeBSD
.Sh NAME
.Nm pkg_info
.Nd a utility for displaying information on software packages
.Sh SYNOPSIS
.Nm pkg_info
-.Op Fl cdDikrRpLqImv
+.Op Fl cDdfIikLmpqRrvh
.Op Fl e Ar package
.Op Fl l Ar prefix
.Ar pkg-name [pkg-name ...]
.Nm pkg_info
-.Fl a
-.Op Ar flags
+.Op Fl a Ar flags
.Sh DESCRIPTION
The
.Nm
-command is used to dump out information for packages, either packed up in
-files or already installed on the system
-with the
+command is used to dump out information for packages, which may be either
+packed up in files or already installed on the system with the
.Xr pkg_create 1
command.
-.Sh OPTIONS
-The following command line options are supported:
+.Pp
+The
+.Ar pkg-name
+may be the name of an installed package, the pathname to a package
+distribution file, or a URL to an ftp-available package.
+.Pp
+The following command-line options are supported:
.Bl -tag -width indent
-.It Ar pkg-name ...
-The named packages are described. A package name may either be the name of
-an installed package, the pathname to a package distribution file or a
-URL to an ftp available package.
.It Fl a
-Show all currently installed packages.
-.It Fl v
-Turn on verbose output.
-.It Fl p
-Show the installation prefix for each package.
-.It Fl q
-Be ``quiet'' in emitting report headers and such, just dump the
-raw info (basically, assume a non-human reading).
+Show information for all currently installed packages.
.It Fl c
-Show the comment (one liner) field for each package.
-.It Fl d
-Show the long description field for each package.
+Show the one-line comment field for each package.
.It Fl D
-Show the install-message file for each package.
-.It Fl f
-Show the packing list instructions for each package.
-.It Fl i
-Show the install script (if any) for each package.
-.It Fl k
-Show the de-install script (if any) for each package.
-.It Fl r
-Show the requirements script (if any) for each package.
-.It Fl m
-Show the mtree file (if any) for each package.
-.It Fl L
-Show the files within each package. This is different from just
-viewing the packing list, since full pathnames for everything
-are generated.
+Show the install-message file (if any) for each package.
+.It Fl d
+Show the long-description field for each package.
.It Fl e Ar pkg-name
If the package identified by
.Ar pkg-name
is currently installed, return 0, otherwise return 1.
-If the give pkg-name contains a
+If the given pkg-name contains a
shell metacharacter, it will be matched against all installed
packages using
.Xr fnmatch 3 ,
and any packages found installed are printed to stdout, one name per
-line. This printing can be turned off using the
+line. This printing can be turned off using the
.Fl q
option.
This option
allows you to easily test for the presence of another (perhaps
prerequisite) package from a script.
+.It Fl f
+Show the packing list instructions for each package.
+.It Fl I
+Show the index entry for each package.
+.It Fl i
+Show the install script (if any) for each package.
+.It Fl k
+Show the de-install script (if any) for each package.
+.It Fl L
+Show the files within each package. This is different from just
+viewing the packing list, since full pathnames for everything
+are generated.
.It Fl l Ar str
Prefix each information category header (see
.Fl q )
shown with
.Ar str .
-This is primarily of use to front-end programs who want to request a
+This is primarily of use to front-end programs that want to request a
lot of different information fields at once for a package, but don't
necessary want the output intermingled in such a way that they can't
organize it. This lets you add a special token to the start of
each field.
-.It Fl t Ar template
-Use
-.Ar template
-as the input to
-.Xr mktemp 3
-when creating a ``staging area.''
-By default, this is the string
-.Pa /tmp/instmp.XXXXXX ,
-but it may be necessary to override it in the situation where
-space in your
-.Pa /tmp
-directory is limited. Be sure to leave some number of `X' characters
-for
-.Xr mktemp 3
-to fill in with a unique ID.
-.Bd -filled -offset indent -compact
-Note: This should really not be necessary with pkg_info,
-since very little information is extracted from each package
-and one would have to have a very small
-.Pa /tmp
-indeed to overflow it.
-.Ed
+.It Fl m
+Show the mtree file (if any) for each package.
+.It Fl p
+Show the installation prefix for each package.
+.It Fl q
+Be ``quiet'' in emitting report headers and such, just dump the
+raw info (basically, assume a non-human reading).
+.It Fl R
+Show which packages are required by each package.
+.It Fl r
+Show the requirements script (if any) for each package.
+.It Fl v
+Turn on verbose output.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width PKG_DBDIR
+.It Ev PKG_DBDIR
+The standard package database directory,
+.Pa /var/db/pkg ,
+can be overridden by specifying an alternative directory in the
+.Ev PKG_DBDIR
+environment variable.
+.It Ev PKG_PATH
+This can be used to specify a colon-separated list of paths to search for
+package files. The current directory is always searched first, even if
+.Ev PKG_PATH
+is set. If
+.Ev PKG_PATH
+is used, the suffix
+.Pa .tgz
+is automatically appended to the
+.Ar pkg-name ,
+whereas searching in the current directory uses
+.Ar pkg-name
+literally.
+.It Ev PKG_TMPDIR , Ev TMPDIR
+These are tried in turn (if set) as candidate directories in which
+to create a ``staging area'' for any files extracted by
+.Nm
+from package files. If neither
+.Ev PKG_TMPDIR
+nor
+.Ev TMPDIR
+yields a suitable scratch directory,
+.Pa /var/tmp ,
+.Pa /tmp ,
+and
+.Pa /usr/tmp
+are tried in turn. Note that
+.Pa /usr/tmp
+may be created, if it doesn't already exist.
+.Pp
+Since
+.Nm
+requires very little information to be extracted from any package
+files examined, it is unlikely that these environment variables would
+ever need to be used to work around limited available space in the
+default locations.
+.El
.Sh TECHNICAL DETAILS
Package info is either extracted from package files named on the
command line, or from already installed package information
in
.Pa /var/db/pkg/<pkg-name> .
>Audit-Trail:
>Unformatted: