+
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the "error unwind" calls listed
+ below.
+
+ <enumlist>
+ <item>
+ <enumlist>
+ <item>
+ If a version of the package is already installed, call
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ If this works, the upgrade continues. If this
+ does not work, the error unwind:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this works, then the old-version is
+ "Installed", if not, the old version is in a
+ "Failed-Config" state.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to <tt>Breaks</tt>):
+ <enumlist>
+ <item>
+ If <tt>--auto-deconfigure</tt> is
+ specified, call, for each package to be deconfigured
+ due to <tt>Breaks</tt>:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ If any packages depended on a conflicting
+ package being removed and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ To prepare for removal of each conflicting package, call:
+ <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call:
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
+ </example>
+ If this fails, we call:
+ <example>
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ <enumlist>
+ <item>
+ <p>
+ If that works, then
+ <example>
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ is called. If this works, then the old version
+ is in an "Installed" state, or else it is left
+ in an "Unpacked" state.
+ </p>
+ </item>
+ <item>
+ <p>
+ If it fails, then the old version is left
+ in an "Half-Installed" state.
+ </p>
+ </item>
+ </enumlist>
+
+ </item>
+ <item>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the "configuration files only" state):
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
+ </example>
+ Error unwind:
+ <example>
+<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
+ If this fails, the package is left in a
+ "Half-Installed" state, which requires a
+ reinstall. If it works, the packages is left in
+ a "Config Files" state.
+ </item>
+ <item>
+ Otherwise (i.e., the package was completely purged):
+ <example compact="compact">
+<var>new-preinst</var> install
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>new-postrm</var> abort-install
+ </example>
+ If the error-unwind fails, the package is in a
+ "Half Installed" phase, and requires a
+ reinstall. If the error unwind works, the
+ package is in a not installed state.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+ </p>
+
+ <p>
+ It is an error for a package to contain files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ -->
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to "missing" programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.<footnote>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic link
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call
+ <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If this fails, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ If this works, installation continues. If not,
+ Error unwind:
+ <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this fails, the old version is in an
+ "Unpacked" state.
+ </item>
+ </enumlist>
+ </p>
+
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
+
+ <item>
+ Any files which were in the old version of the package
+ but not in the new are removed.
+ </item>
+
+ <item>
+ The new file list replaces the old.
+ </item>
+
+ <item>
+ The new maintainer scripts replace the old.
+ </item>
+
+ <item>
+ Any packages all of whose files have been overwritten
+ during the installation, and which aren't required for
+ dependencies, are considered to have been removed.
+ For each such package
+ <enumlist>
+ <item>
+ <prgn>dpkg</prgn> calls:
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </item>
+ <item>
+ The package's maintainer scripts are removed.
+ </item>
+ <item>
+ It is noted in the status database as being in a
+ sane state, namely not installed (any conffiles
+ it may have are ignored, rather than being
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ Any files in the package we're unpacking that are also
+ listed in the file lists of other packages are removed
+ from those lists. (This will lobotomize the file list
+ of the "conflicting" package if there is one.)
+ </item>
+
+ <item>
+ The backup files made during installation, above, are
+ deleted.
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ "unpacked".
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
+ </p>
+ </item>
+
+ <item>
+ If there was a conflicting package we go and do the
+ removal actions (described below), starting with the
+ removal of the conflicting package's files (any that
+ are also in the package being installed have already
+ been removed from the conflicting package's file list,
+ and so do not get removed now).
+ </item>
+ </enumlist>