dpkg: Clarify that --set-selections needs an up-to-date available db

Document this in the man page, and warn whenever we find unknown
packages during the --set-selections processing.

Closes: #703092

debian/changelog

@@ -1,5 +1,6 @@
 dpkg (1.17.0) UNRELEASED; urgency=low
 
+  [ Guillem Jover ]
   * Switch update-alternatives back to a fatal error on out of range priority
     on --install.
   * Document dpkg-deb --debug in --help output.
@@ -94,6 +95,9 @@ dpkg (1.17.0) UNRELEASED; urgency=low
     not yet supported). Thanks to Matthias Klose <doko@ubuntu.com>.
     Closes: #711936
   * Add GCJFLAGS support to dpkg-buildflags. Closes: #708375
+  * Clarify that dpkg --set-selections needs an up-to-date available db,
+    by documenting it on the dpkg(1) man page, and warning whenever dpkg
+    finds unknown packages while setting the selections. Closes: #703092
 
   [ Updated programs translations ]
   * Fix typo in Spanish translation of update-alternatives.

man/dpkg.1

@@ -246,6 +246,11 @@ Set package selections using file read from stdin. This file should be
 in the format '\fIpackage\fP \fIstate\fP', where state is one of
 \fBinstall\fP, \fBhold\fP, \fBdeinstall\fP or \fBpurge\fP. Blank lines
 and comment lines beginning with '#' are also permitted.
+
+The available database needs to be up-to-date for this command to be
+useful, otherwise unknown packages will be ignored with a warning. See
+the \fB\-\-update\-avail\fP and \fB\-\-merge\-avail\fP commands for more
+information.
 .TP
 .B \-\-clear\-selections
 Set the requested state of every non-essential package to deinstall.

src/select.c

@@ -112,6 +112,7 @@ setselections(const char *const *argv)
   int c, lno;
   struct varbuf namevb = VARBUF_INIT;
   struct varbuf selvb = VARBUF_INIT;
+  bool db_possibly_outdated = false;
 
   if (*argv)
     badusage(_("--%s takes no arguments"), cipaction->olong);
@@ -163,6 +164,7 @@ setselections(const char *const *argv)
 
     if (!pkg_is_informative(pkg, &pkg->installed) &&
         !pkg_is_informative(pkg, &pkg->available)) {
+      db_possibly_outdated = true;
       warning(_("package not in database at line %d: %.250s"), lno, namevb.buf);
       continue;
     }
@@ -180,6 +182,10 @@ setselections(const char *const *argv)
   varbuf_destroy(&namevb);
   varbuf_destroy(&selvb);
 
+  if (db_possibly_outdated)
+    warning(_("found unknown packages; this might mean the available database\n"
+              "is outdated, and needs to be updated through a frontend method"));
+
   return 0;
 }