>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: