You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

871 lines
26 KiB

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  4. <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
  5. <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
  6. <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
  7. ]>
  8. <book lang="en">
  9. <title>dpkg technical manual</title>
  10. <bookinfo>
  11. <authorgroup>
  12. <author>
  13. <personname>Tom Lees</personname><email>tom@lpsg.demon.co.uk</email>
  14. </author>
  15. </authorgroup>
  16. <releaseinfo>Version &apt-product-version;</releaseinfo>
  17. <abstract>
  18. <para>
  19. This document describes the minimum necessary workings for the APT dselect
  20. replacement. It gives an overall specification of what its external interface
  21. must look like for compatibility, and also gives details of some internal
  22. quirks.
  23. </para>
  24. </abstract>
  25. <copyright><year>1997</year><holder>Tom Lees</holder></copyright>
  26. <legalnotice>
  27. <title>License Notice</title>
  28. <para>
  29. APT and this document are free software; you can redistribute them and/or
  30. modify them under the terms of the GNU General Public License as published by
  31. the Free Software Foundation; either version 2 of the License, or (at your
  32. option) any later version.
  33. </para>
  34. <para>
  35. For more details, on Debian systems, see the file
  36. /usr/share/common-licenses/GPL for the full license.
  37. </para>
  38. </legalnotice>
  39. </bookinfo>
  40. <chapter id="ch1"><title>Quick summary of dpkg's external interface</title>
  41. <section id="control"><title>Control files</title>
  42. <para>
  43. The basic dpkg package control file supports the following major features:-
  44. </para>
  45. <itemizedlist>
  46. <listitem>
  47. <para>
  48. 5 types of dependencies:-
  49. </para>
  50. <itemizedlist>
  51. <listitem>
  52. <para>
  53. Pre-Depends, which must be satisfied before a package may be unpacked
  54. </para>
  55. </listitem>
  56. <listitem>
  57. <para>
  58. Depends, which must be satisfied before a package may be configured
  59. </para>
  60. </listitem>
  61. <listitem>
  62. <para>
  63. Recommends, to specify a package which if not installed may severely limit the
  64. usefulness of the package
  65. </para>
  66. </listitem>
  67. <listitem>
  68. <para>
  69. Suggests, to specify a package which may increase the productivity of the
  70. package
  71. </para>
  72. </listitem>
  73. <listitem>
  74. <para>
  75. Conflicts, to specify a package which must NOT be installed in order for the
  76. package to be configured
  77. </para>
  78. </listitem>
  79. <listitem>
  80. <para>
  81. Breaks, to specify a package which is broken by the package and which should
  82. therefore not be configured while broken
  83. </para>
  84. </listitem>
  85. </itemizedlist>
  86. <para>
  87. Each of these dependencies can specify a version and a dependency on that
  88. version, for example "&lt;= 0.5-1", "== 2.7.2-1", etc. The comparators
  89. available are:-
  90. </para>
  91. <itemizedlist>
  92. <listitem>
  93. <para>
  94. "&lt;&lt;" - less than
  95. </para>
  96. </listitem>
  97. <listitem>
  98. <para>
  99. "&lt;=" - less than or equal to
  100. </para>
  101. </listitem>
  102. <listitem>
  103. <para>
  104. "&gt;&gt;" - greater than
  105. </para>
  106. </listitem>
  107. <listitem>
  108. <para>
  109. "&gt;=" - greater than or equal to
  110. </para>
  111. </listitem>
  112. <listitem>
  113. <para>
  114. "==" - equal to
  115. </para>
  116. </listitem>
  117. </itemizedlist>
  118. </listitem>
  119. <listitem>
  120. <para>
  121. The concept of "virtual packages", which many other packages may provide,
  122. using the Provides mechanism. An example of this is the "httpd" virtual
  123. package, which all web servers should provide. Virtual package names may be
  124. used in dependency headers. However, current policy is that virtual packages
  125. do not support version numbers, so dependencies on virtual packages with
  126. versions will always fail.
  127. </para>
  128. </listitem>
  129. <listitem>
  130. <para>
  131. Several other control fields, such as Package, Version, Description, Section,
  132. Priority, etc., which are mainly for classification purposes. The package
  133. name must consist entirely of lowercase characters, plus the characters '+',
  134. '-', and '.'. Fields can extend across multiple lines - on the second and
  135. subsequent lines, there is a space at the beginning instead of a field name
  136. and a ':'. Empty lines must consist of the text " .", which will be ignored,
  137. as will the initial space for other continuation lines. This feature is
  138. usually only used in the Description field.
  139. </para>
  140. </listitem>
  141. </itemizedlist>
  142. </section>
  143. <section id="s1.2"><title>The dpkg status area</title>
  144. <para>
  145. The "dpkg status area" is the term used to refer to the directory where dpkg
  146. keeps its various status files (GNU would have you call it the dpkg shared
  147. state directory). This is always, on Debian systems, /var/lib/dpkg. However,
  148. the default directory name should not be hard-coded, but #define'd, so that
  149. alteration is possible (it is available via configure in dpkg 1.4.0.9 and
  150. above). Of course, in a library, code should be allowed to override the
  151. default directory, but the default should be part of the library (so that
  152. the user may change the dpkg admin dir simply by replacing the library).
  153. </para>
  154. <para>
  155. Dpkg keeps a variety of files in its status area. These are discussed later
  156. on in this document, but a quick summary of the files is here:-
  157. </para>
  158. <itemizedlist>
  159. <listitem>
  160. <para>
  161. available - this file contains a concatenation of control information from all
  162. the packages which dpkg knows about. This is updated using the dpkg commands
  163. "--update-avail &lt;file&gt;", "--merge-avail &lt;file&gt;", and
  164. "--clear-avail".
  165. </para>
  166. </listitem>
  167. <listitem>
  168. <para>
  169. status - this file contains information on the following things for every
  170. package:-
  171. </para>
  172. <itemizedlist>
  173. <listitem>
  174. <para>
  175. Whether it is installed, not installed, unpacked, removed, failed
  176. configuration, or half-installed (deconfigured in favour of another package).
  177. </para>
  178. </listitem>
  179. <listitem>
  180. <para>
  181. Whether it is selected as install, hold, remove, or purge.
  182. </para>
  183. </listitem>
  184. <listitem>
  185. <para>
  186. If it is "ok" (no installation problems), or "not-ok".
  187. </para>
  188. </listitem>
  189. <listitem>
  190. <para>
  191. It usually also contains the section and priority (so that dselect may classify
  192. packages not in available)
  193. </para>
  194. </listitem>
  195. <listitem>
  196. <para>
  197. For packages which did not initially appear in the "available" file when they
  198. were installed, the other control information for them.
  199. </para>
  200. </listitem>
  201. </itemizedlist>
  202. <para>
  203. The exact format for the "Status:" field is:
  204. </para>
  205. <screen>
  206. Status: Want Flag Status
  207. </screen>
  208. <para>
  209. Where <replaceable>Want</replaceable> may be one of
  210. <emphasis>unknown</emphasis>, <emphasis>install</emphasis>,
  211. <emphasis>hold</emphasis>, <emphasis>deinstall</emphasis>,
  212. <emphasis>purge</emphasis>. <replaceable>Flag</replaceable> may
  213. be one of <emphasis>ok</emphasis>, <emphasis>reinstreq</emphasis>.
  214. <replaceable>Status</replaceable> may
  215. be one of <emphasis>not-installed</emphasis>, <emphasis>config-files</emphasis>,
  216. <emphasis>half-installed</emphasis>, <emphasis>unpacked</emphasis>,
  217. <emphasis>half-configured</emphasis> and <emphasis>installed</emphasis>.
  218. The states are as follows:-
  219. </para>
  220. <variablelist>
  221. <varlistentry>
  222. <term>not-installed</term>
  223. <listitem>
  224. <para>
  225. No files are installed from the package, it has no config files left, it
  226. uninstalled cleanly if it ever was installed.
  227. </para>
  228. </listitem>
  229. </varlistentry>
  230. <varlistentry>
  231. <term>unpacked</term>
  232. <listitem>
  233. <para>
  234. The basic files have been unpacked (and are listed in
  235. /var/lib/dpkg/info/[package].list. There are config files present, but the
  236. postinst script has _NOT_ been run.
  237. </para>
  238. </listitem>
  239. </varlistentry>
  240. <varlistentry>
  241. <term>half-configured</term>
  242. <listitem>
  243. <para>
  244. The package was installed and unpacked, but the postinst script failed in some
  245. way.
  246. </para>
  247. </listitem>
  248. </varlistentry>
  249. <varlistentry>
  250. <term>installed</term>
  251. <listitem>
  252. <para>
  253. All files for the package are installed, and the configuration was also
  254. successful.
  255. </para>
  256. </listitem>
  257. </varlistentry>
  258. <varlistentry>
  259. <term>half-installed</term>
  260. <listitem>
  261. <para>
  262. An attempt was made to remove the package but there was a failure in the
  263. prerm script.
  264. </para>
  265. </listitem>
  266. </varlistentry>
  267. <varlistentry>
  268. <term>config-files</term>
  269. <listitem>
  270. <para>
  271. The package was "removed", not "purged". The config files are left, but
  272. nothing else.
  273. </para>
  274. </listitem>
  275. </varlistentry>
  276. </variablelist>
  277. <para>
  278. The two last items are only left in dpkg for compatibility - they are
  279. understood by it, but never written out in this form.
  280. </para>
  281. <para>
  282. Please see the dpkg source code, <literal>lib/parshelp.c</literal>,
  283. <emphasis>statusinfos</emphasis>, <emphasis>eflaginfos</emphasis> and
  284. <emphasis>wantinfos</emphasis> for more details.
  285. </para>
  286. </listitem>
  287. <listitem>
  288. <para>
  289. info - this directory contains files from the control archive of every
  290. package currently installed. They are installed with a prefix of
  291. "&lt;packagename&gt;.". In addition to this, it also contains a file
  292. called &lt;package&gt;.list for every package, which contains a list
  293. of files. Note also that the control file is not copied into here; it
  294. is instead found as part of status or available.
  295. </para>
  296. </listitem>
  297. <listitem>
  298. <para>
  299. methods - this directory is reserved for "method"-specific files - each
  300. "method" has a subdirectory underneath this directory (or at least,
  301. it can have). In addition, there is another subdirectory "mnt", where
  302. misc. filesystems (floppies, CD-ROMs, etc.) are mounted.
  303. </para>
  304. </listitem>
  305. <listitem>
  306. <para>
  307. alternatives - directory used by the "update-alternatives" program. It
  308. contains one file for each "alternatives" interface, which contains
  309. information about all the needed symlinked files for each alternative.
  310. </para>
  311. </listitem>
  312. <listitem>
  313. <para>
  314. diversions - file used by the "dpkg-divert" program. Each diversion takes
  315. three lines. The first is the package name (or ":" for user diversion), the
  316. second the original filename, and the third the diverted filename.
  317. </para>
  318. </listitem>
  319. <listitem>
  320. <para>
  321. updates - directory used internally by dpkg. This is discussed later, in the
  322. section <xref linkend="updates"/>.
  323. </para>
  324. </listitem>
  325. <listitem>
  326. <para>
  327. parts - temporary directory used by dpkg-split
  328. </para>
  329. </listitem>
  330. </itemizedlist>
  331. </section>
  332. <section id="s1.3"><title>The dpkg library files</title>
  333. <para>
  334. These files are installed under /usr/lib/dpkg (usually), but
  335. /usr/local/lib/dpkg is also a possibility (as Debian policy dictates). Under
  336. this directory, there is a "methods" subdirectory. The methods subdirectory in
  337. turn contains any number of subdirectories for each general method processor
  338. (note that one set of method scripts can, and is, used for more than one of
  339. the methods listed under dselect).
  340. </para>
  341. <para>
  342. The following files may be found in each of these subdirectories:-
  343. </para>
  344. <itemizedlist>
  345. <listitem>
  346. <para>
  347. names - One line per method, two-digit priority to appear on menu at
  348. beginning, followed by a space, the name, and then another space and
  349. the short description.
  350. </para>
  351. </listitem>
  352. <listitem>
  353. <para>
  354. desc.&lt;name&gt; - Contains the long description displayed by dselect
  355. when the cursor is put over the &lt;name&gt; method.
  356. </para>
  357. </listitem>
  358. <listitem>
  359. <para>
  360. setup - Script or program which sets up the initial values to be used
  361. by this method. Called with first argument as the status area directory
  362. (/var/lib/dpkg), second argument as the name of the method (as in the
  363. directory name), and the third argument as the option (as in the names file).
  364. </para>
  365. </listitem>
  366. <listitem>
  367. <para>
  368. install - Script/program called when the "install" option of dselect is run
  369. with this method. Same arguments as for setup.
  370. </para>
  371. </listitem>
  372. <listitem>
  373. <para>
  374. update - Script/program called when the "update" option of dselect is
  375. run. Same arguments as for setup/install.
  376. </para>
  377. </listitem>
  378. </itemizedlist>
  379. </section>
  380. <section id="s1.4"><title>The "dpkg" command-line utility</title>
  381. <section id="s1.4.1"><title>"Documented" command-line interfaces</title>
  382. <para>
  383. As yet unwritten. You can refer to the other manuals for now. See
  384. <citerefentry><refentrytitle>dpkg</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  385. </para>
  386. </section>
  387. <section id="s1.4.2"><title>Environment variables which dpkg responds to</title>
  388. <itemizedlist>
  389. <listitem>
  390. <para>
  391. SHELL - used to determine which shell to run.
  392. </para>
  393. </listitem>
  394. <listitem>
  395. <para>
  396. CC - used as the C compiler to call to determine the target architecture. The
  397. default is "gcc".
  398. </para>
  399. </listitem>
  400. <listitem>
  401. <para>
  402. PATH - dpkg checks that it can find at least the following files in the path
  403. when it wants to run package installation scripts, and gives an error if it
  404. cannot find all of them:-
  405. </para>
  406. <itemizedlist>
  407. <listitem>
  408. <para>
  409. ldconfig
  410. </para>
  411. </listitem>
  412. <listitem>
  413. <para>
  414. start-stop-daemon
  415. </para>
  416. </listitem>
  417. <listitem>
  418. <para>
  419. install-info
  420. </para>
  421. </listitem>
  422. <listitem>
  423. <para>
  424. update-rc.d
  425. </para>
  426. </listitem>
  427. </itemizedlist>
  428. </listitem>
  429. </itemizedlist>
  430. </section>
  431. <section id="s1.4.3"><title>Assertions</title>
  432. <para>
  433. The dpkg utility itself is required for quite a number of packages, even if
  434. they have been installed with a tool totally separate from dpkg. The reason
  435. for this is that some packages, in their pre-installation scripts, check that
  436. your version of dpkg supports certain features. This was broken from the
  437. start, and it should have actually been a control file header "Dpkg-requires",
  438. or similar. What happens is that the configuration scripts will abort or
  439. continue according to the exit code of a call to dpkg, which will stop them
  440. from being wrongly configured.
  441. </para>
  442. <para>
  443. These special command-line options, which simply return as true or false are
  444. all prefixed with "--assert-". Here is a list of them (without the prefix):-
  445. </para>
  446. <itemizedlist>
  447. <listitem>
  448. <para>
  449. support-predepends - Returns success or failure according to whether a version
  450. of dpkg which supports predepends properly (1.1.0 or above) is installed,
  451. according to the database.
  452. </para>
  453. </listitem>
  454. <listitem>
  455. <para>
  456. working-epoch - Return success or failure according to whether a version of
  457. dpkg which supports epochs in version properly (1.4.0.7 or above) is installed,
  458. according to the database.
  459. </para>
  460. </listitem>
  461. </itemizedlist>
  462. <para>
  463. Both these options check the status database to see what version of the
  464. "dpkg" package is installed, and check it against a known working version.
  465. </para>
  466. </section>
  467. <section id="s1.4.4"><title>--predep-package</title>
  468. <para>
  469. This strange option is described as follows in the source code:
  470. </para>
  471. <screen>
  472. /* Print a single package which:
  473. * (a) is the target of one or more relevant predependencies.
  474. * (b) has itself no unsatisfied pre-dependencies.
  475. * If such a package is present output is the Packages file entry,
  476. * which can be massaged as appropriate.
  477. * Exit status:
  478. * 0 = a package printed, OK
  479. * 1 = no suitable package available
  480. * 2 = error
  481. */
  482. </screen>
  483. <para>
  484. On further inspection of the source code, it appears that what is does is
  485. this:-
  486. </para>
  487. <itemizedlist>
  488. <listitem>
  489. <para>
  490. Looks at the packages in the database which are selected as "install",
  491. and are installed.
  492. </para>
  493. </listitem>
  494. <listitem>
  495. <para>
  496. It then looks at the Pre-Depends information for each of these packages
  497. from the available file. When it find a package for which any of the
  498. pre-dependencies are not satisfied, it breaks from the loop through the
  499. packages.
  500. </para>
  501. </listitem>
  502. <listitem>
  503. <para>
  504. It then looks through the unsatisfied pre-dependencies, and looks for
  505. packages which would satisfy this pre-dependency, stopping on the first
  506. it finds. If it finds none, it bombs out with an error.
  507. </para>
  508. </listitem>
  509. <listitem>
  510. <para>
  511. It then continues this for every dependency of the initial package.
  512. </para>
  513. </listitem>
  514. </itemizedlist>
  515. <para>
  516. Eventually, it writes out the record of all the packages to satisfy the
  517. pre-dependencies. This is used by the disk method to make sure that its
  518. dependency ordering is correct. What happens is that all pre-depending
  519. packages are first installed, then it runs dpkg -iGROEB on the directory,
  520. which installs in the order package files are found. Since pre-dependencies
  521. mean that a package may not even be unpacked unless they are satisfied, it
  522. is necessary to do this (usually, since all the package files are unpacked
  523. in one phase, the configured in another, this is not needed).
  524. </para>
  525. </section>
  526. </section>
  527. </chapter>
  528. <chapter id="ch2"><title>dpkg-deb and .deb file internals</title>
  529. <para>
  530. This chapter describes the internals to the "dpkg-deb" tool, which is used by
  531. "dpkg" as a back-end. dpkg-deb has its own tar extraction functions, which is
  532. the source of many problems, as it does not support long filenames, using
  533. extension blocks.
  534. </para>
  535. <section id="s2.1"><title>The .deb archive format</title>
  536. <para>
  537. The main principal of the new-format Debian archive (I won't describe the old
  538. format - for that have a look at deb-old.5), is that the archive really is an
  539. archive - as used by "ar" and friends. However, dpkg-deb uses this format
  540. internally, rather than calling "ar". Inside this archive, there are usually
  541. the following members:-
  542. </para>
  543. <itemizedlist>
  544. <listitem>
  545. <para>
  546. debian-binary
  547. </para>
  548. </listitem>
  549. <listitem>
  550. <para>
  551. control.tar.gz
  552. </para>
  553. </listitem>
  554. <listitem>
  555. <para>
  556. data.tar.gz
  557. </para>
  558. </listitem>
  559. </itemizedlist>
  560. <para>
  561. The debian-binary member consists simply of the string "2.0", indicating
  562. the format version. control.tar.gz contains the control files (and scripts),
  563. and the data.tar.gz contains the actual files to populate the filesystem
  564. with. Both tarfiles extract straight into the current directory. Information
  565. on the tar formats can be found in the GNU tar info page. Since dpkg-deb
  566. calls "tar -cf" to build packages, the Debian packages use the GNU extensions.
  567. </para>
  568. </section>
  569. <section id="s2.2"><title>The dpkg-deb command-line</title>
  570. <para>
  571. dpkg-deb documents itself thoroughly with its '--help' command-line
  572. option. However, I am including a reference to these for
  573. completeness. dpkg-deb supports the following options:-
  574. </para>
  575. <itemizedlist>
  576. <listitem>
  577. <para>
  578. --build (-b) &lt;dir&gt; - builds a .deb archive, takes a directory which
  579. contains all the files as an argument. Note that the directory
  580. &lt;dir&gt;/DEBIAN will be packed separately into the control archive.
  581. </para>
  582. </listitem>
  583. <listitem>
  584. <para>
  585. --contents (-c) &lt;debfile&gt; - Lists the contents of the "data.tar.gz"
  586. member.
  587. </para>
  588. </listitem>
  589. <listitem>
  590. <para>
  591. --control (-e) &lt;debfile&gt; - Extracts the control archive into a directory
  592. called DEBIAN. Alternatively, with another argument, it will extract it into a
  593. different directory.
  594. </para>
  595. </listitem>
  596. <listitem>
  597. <para>
  598. --info (-I) &lt;debfile&gt; - Prints the contents of the "control" file in the
  599. control archive to stdout. Alternatively, giving it other arguments will cause
  600. it to print the contents of those files instead.
  601. </para>
  602. </listitem>
  603. <listitem>
  604. <para>
  605. --field (-f) &lt;debfile&gt; &lt;field&gt; ... - Prints any number of fields
  606. from the "control" file. Giving it extra arguments limits the fields it prints
  607. to only those specified. With no command-line arguments other than a filename,
  608. it is equivalent to -I and just the .deb filename.
  609. </para>
  610. </listitem>
  611. <listitem>
  612. <para>
  613. --extract (-x) &lt;debfile&gt; &lt;dir&gt; - Extracts the data archive of a
  614. debian package under the directory &lt;dir&gt;.
  615. </para>
  616. </listitem>
  617. <listitem>
  618. <para>
  619. --vextract (-X) &lt;debfile&gt; &lt;dir&gt; - Same as --extract, except it
  620. is equivalent of giving tar the '-v' option - it prints the filenames as it
  621. extracts them.
  622. </para>
  623. </listitem>
  624. <listitem>
  625. <para>
  626. --fsys-tarfile &lt;debfile&gt; - This option outputs a gunzip'd version of
  627. data.tar.gz to stdout.
  628. </para>
  629. </listitem>
  630. <listitem>
  631. <para>
  632. --new - sets the archive format to be used to the new Debian format
  633. </para>
  634. </listitem>
  635. <listitem>
  636. <para>
  637. --old - sets the archive format to be used to the old Debian format
  638. </para>
  639. </listitem>
  640. <listitem>
  641. <para>
  642. --debug - Tells dpkg-deb to produce debugging output
  643. </para>
  644. </listitem>
  645. <listitem>
  646. <para>
  647. --nocheck - Tells dpkg-deb not to check the sanity of the control file
  648. </para>
  649. </listitem>
  650. <listitem>
  651. <para>
  652. --help (-h) - Gives a help message
  653. </para>
  654. </listitem>
  655. <listitem>
  656. <para>
  657. --version - Shows the version number
  658. </para>
  659. </listitem>
  660. <listitem>
  661. <para>
  662. --licence/--license (UK/US spellings) - Shows a brief outline of the GPL
  663. </para>
  664. </listitem>
  665. </itemizedlist>
  666. <section id="s2.2.1"><title>Internal checks used by dpkg-deb when building packages</title>
  667. <para>
  668. Here is a list of the internal checks used by dpkg-deb when building
  669. packages. It is in the order they are done.
  670. </para>
  671. <itemizedlist>
  672. <listitem>
  673. <para>
  674. First, the output Debian archive argument, if it is given, is checked using
  675. stat. If it is a directory, an internal flag is set. This check is only made
  676. if the archive name is specified explicitly on the command-line. If the
  677. argument was not given, the default is the directory name, with ".deb"
  678. appended.
  679. </para>
  680. </listitem>
  681. <listitem>
  682. <para>
  683. Next, the control file is checked, unless the --nocheck flag was specified on
  684. the command-line. dpkg-deb will bomb out if the second argument to --build was
  685. a directory, and --nocheck was specified. Note that dpkg-deb will not be able
  686. to determine the name of the package in this case. In the control file, the
  687. following things are checked:-
  688. </para>
  689. <itemizedlist>
  690. <listitem>
  691. <para>
  692. The package name is checked to see if it contains any invalid characters (see
  693. <xref linkend="control"/> for this).
  694. </para>
  695. </listitem>
  696. <listitem>
  697. <para>
  698. The priority field is checked to see if it uses standard values, and
  699. user-defined values are warned against. However, note that this check is now
  700. redundant, since the control file no longer contains the priority - the
  701. changes file now does this.
  702. </para>
  703. </listitem>
  704. <listitem>
  705. <para>
  706. The control file fields are then checked against the standard list of fields
  707. which appear in control files, and any "user-defined" fields are reported as
  708. warnings.
  709. </para>
  710. </listitem>
  711. <listitem>
  712. <para>
  713. dpkg-deb then checks that the control file contains a valid version number.
  714. </para>
  715. </listitem>
  716. </itemizedlist>
  717. </listitem>
  718. <listitem>
  719. <para>
  720. After this, in the case where a directory was specified to build the .deb file
  721. in, the filename is created as "directory/pkg_ver.deb" or
  722. "directory/pkg_ver_arch.deb", depending on whether the control file contains
  723. an architecture field.
  724. </para>
  725. </listitem>
  726. <listitem>
  727. <para>
  728. Next, dpkg-deb checks for the &lt;dir&gt;/DEBIAN directory. It complains if it
  729. doesn't exist, or if it has permissions &lt; 0755, or &gt; 0775.
  730. </para>
  731. </listitem>
  732. <listitem>
  733. <para>
  734. It then checks that all the files in this subdir are either symlinks or plain
  735. files, and have permissions between 0555 and 0775.
  736. </para>
  737. </listitem>
  738. <listitem>
  739. <para>
  740. The conffiles file is then checked to see if the filenames are too
  741. long. Warnings are produced for each that is. After this, it checks
  742. that the package provides initial copies of each of these conffiles,
  743. and that they are all plain files.
  744. </para>
  745. </listitem>
  746. </itemizedlist>
  747. </section>
  748. </section>
  749. </chapter>
  750. <chapter id="ch3"><title>dpkg internals</title>
  751. <para>
  752. This chapter describes the internals of dpkg itself. Although the low-level
  753. formats are quite simple, what dpkg does in certain cases often does not make
  754. sense.
  755. </para>
  756. <section id="updates"><title>Updates</title>
  757. <para>
  758. This describes the /var/lib/dpkg/updates directory. The function of this
  759. directory is somewhat strange, and seems only to be used internally. A
  760. function called cleanupdates is called whenever the database is scanned. This
  761. function in turn uses
  762. <citerefentry><refentrytitle>scandir</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  763. to sort the files in this directory. Files who names do not consist entirely
  764. of digits are discarded. dpkg also causes a fatal error if any of the
  765. filenames are different lengths.
  766. </para>
  767. <para>
  768. After having scanned the directory, dpkg in turn parses each file the same way
  769. it parses the status file (they are sorted by the scandir to be in numerical
  770. order). After having done this, it then writes the status information back to
  771. the "status" file, and removes all the "updates" files.
  772. </para>
  773. <para>
  774. These files are created internally by dpkg's "checkpoint" function, and are
  775. cleaned up when dpkg exits cleanly.
  776. </para>
  777. <para>
  778. Judging by the use of the updates directory I would call it a Journal. Inorder
  779. to efficiently ensure the complete integrity of the status file dpkg will
  780. "checkpoint" or journal all of it's activities in the updates directory. By
  781. merging the contents of the updates directory (in order!!) against the original
  782. status file it can get the precise current state of the system, even in the
  783. event of a system failure while dpkg is running.
  784. </para>
  785. <para>
  786. The other option would be to sync-rewrite the status file after each operation,
  787. which would kill performance.
  788. </para>
  789. <para>
  790. It is very important that any program that uses the status file abort if the
  791. updates directory is not empty! The user should be informed to run dpkg
  792. manually (what options though??) to correct the situation.
  793. </para>
  794. </section>
  795. <section id="s3.2"><title>What happens when dpkg reads the database</title>
  796. <para>
  797. First, the status file is read. This gives dpkg an initial idea of the
  798. packages that are there. Next, the updates files are read in, overriding the
  799. status file, and if necessary, the status file is re-written, and updates files
  800. are removed. Finally, the available file is read. The available file is read
  801. with flags which preclude dpkg from updating any status information from it,
  802. though - installed version, etc., and is also told to record that the packages
  803. it reads this time are available, not installed.
  804. </para>
  805. <para>
  806. More information on updates is given above.
  807. </para>
  808. </section>
  809. <section id="s3.3"><title>How dpkg compares version numbers</title>
  810. <para>
  811. Version numbers consist of three parts: the epoch, the upstream version, and
  812. the Debian revision. Dpkg compares these parts in that order. If the epochs
  813. are different, it returns immediately, and so on.
  814. </para>
  815. <para>
  816. However, the important part is how it compares the versions which are
  817. essentially stored as just strings. These are compared in two distinct
  818. parts: those consisting of numerical characters (which are evaluated, and
  819. then compared), and those consisting of other characters. When comparing
  820. non-numerical parts, they are compared as the character values (ASCII),
  821. but non-alphabetical characters are considered "greater than" alphabetical
  822. ones. Also note that longer strings (after excluding differences where
  823. numerical values are equal) are considered "greater than" shorter ones.
  824. </para>
  825. <para>
  826. Here are a few examples of how these rules apply:-
  827. </para>
  828. <screen>
  829. 15 &gt; 10
  830. 0010 == 10
  831. d.r &gt; dsr
  832. 32.d.r == 0032.d.r
  833. d.rnr &lt; d.rnrn
  834. </screen>
  835. </section>
  836. </chapter>
  837. </book>