dpkg: Pass the package reference count to maintainer scripts

The new variable DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT will contain the
number of package instances with a state grater than not-installed.
This should allow packages to easily perform actions on the first
instance installed or the last instance removed, for example.

Closes: #681370

debian/changelog

@@ -25,6 +25,8 @@ dpkg (1.17.2) UNRELEASED; urgency=low
     Thanks to Jeff Bailey <jeffbailey@google.com>.
   * Use dpkg-gencontrol -c argument as a fallback lock file in case
     debian/control does not exist. Closes: #667008
+  * Pass the package reference count (i.e. number of present instances) to
+    maintainer scripts via the new variable DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT.
 
   [ Updated programs translations ]
   * Vietnamese (Trần Ngọc Quân).

man/dpkg.1

@@ -711,6 +711,11 @@ version of the currently running \fBdpkg\fP instance.
 Defined by \fBdpkg\fP on the maintainer script environment to the
 (non-arch-qualified) package name being handled.
 .TP
+.B DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT
+Defined by \fBdpkg\fP on the maintainer script environment to the
+package reference count, i.e. the number of package instances with
+a state greater than \fBnot\-installed\fP. Since dpkg 1.17.2.
+.TP
 .B DPKG_MAINTSCRIPT_ARCH
 Defined by \fBdpkg\fP on the maintainer script environment to the
 architecture the package got built for.

src/script.c

@@ -216,7 +216,12 @@ do_script(struct pkginfo *pkg, struct pkgbin *pkgbin,
 
 	pid = subproc_fork();
 	if (pid == 0) {
+		char *pkg_count;
+
+		m_asprintf(&pkg_count, "%d", pkgset_installed_instances(pkg->set));
+
 		if (setenv("DPKG_MAINTSCRIPT_PACKAGE", pkg->set->name, 1) ||
+		    setenv("DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT", pkg_count, 1) ||
 		    setenv("DPKG_MAINTSCRIPT_ARCH", pkgbin->arch->name, 1) ||
 		    setenv("DPKG_MAINTSCRIPT_NAME", cmd->argv[0], 1) ||
 		    setenv("DPKG_RUNNING_VERSION", PACKAGE_VERSION, 1))