* imported changes from apt--main

[apt.git] / doc / cache.sgml

diff --git a/doc/cache.sgml b/doc/cache.sgml
index 43f8d4fffefce19a1ab662bc1679996ac8f2e695..aa87db98680c4c48c9067d0e8273027330681df9 100644 (file)
--- a/doc/cache.sgml
+++ b/doc/cache.sgml
@@ -1,10 +1,10 @@
-<!doctype debiandoc system>

 <!-- -*- mode: sgml; mode: fold -*- -->
 <!-- -*- mode: sgml; mode: fold -*- -->

+<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">

 <book>
 <title>APT Cache File Format</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
 <book>
 <title>APT Cache File Format</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>

-<version>$Id: cache.sgml,v 1.1 1998/07/02 02:58:12 jgg Exp $</version>
+<version>$Id: cache.sgml,v 1.11 2003/02/12 15:05:44 doogie Exp $</version>

 
 <abstract>
 This document describes the complete implementation and format of the APT
 
 <abstract>
 This document describes the complete implementation and format of the APT


@@ -19,7 +19,7 @@ structures used by the package library and the APT GUI.
 </abstract>
 
 <copyright>
 </abstract>
 
 <copyright>

-Copyright &copy; Jason Gunthorpe, 1997.
+Copyright &copy; Jason Gunthorpe, 1997-1998.

 <p>
 APT and this document are free software; you can redistribute them and/or
 modify them under the terms of the GNU General Public License as published
 <p>
 APT and this document are free software; you can redistribute them and/or
 modify them under the terms of the GNU General Public License as published


@@ -28,7 +28,7 @@ option) any later version.
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file

-/usr/doc/copyright/GPL for the full license.
+/usr/share/common-licenses/GPL for the full license.

 </copyright>
 
 <toc sect>
 </copyright>
 
 <toc sect>


@@ -53,10 +53,10 @@ contained in the status file which might be considered a separate package
 file.
 
 <p>
 file.
 
 <p>

-Please understand, this is designed as a -CACHE FILE- it is not ment to be
-used on any system other than the one it was created for. It is not ment to
-be authoritative either, ie if a system crash or software failure occures it
-must be perfectly acceptable for the cache file to be in an inconsistant
+Please understand, this is designed as a -CACHE FILE- it is not meant to be
+used on any system other than the one it was created for. It is not meant to
+be authoritative either, i.e. if a system crash or software failure occurs it
+must be perfectly acceptable for the cache file to be in an inconsistent

 state. Furthermore at any time the cache file may be erased without losing
 any information.
 
 state. Furthermore at any time the cache file may be erased without losing
 any information.
 


@@ -67,7 +67,7 @@ to extend it with associate cache files that contain other information.
 
 <p>
 To keep memory use down the cache file only contains often used fields and
 
 <p>
 To keep memory use down the cache file only contains often used fields and

-fields that are inexepensive to store, the Package file has a full list of
+fields that are inexpensive to store, the Package file has a full list of

 fields. Also the client may assume that all items are perfectly valid and
 need not perform checks against their correctness. Removal of information
 from the cache is possible, but blanks will be left in the file, and
 fields. Also the client may assume that all items are perfectly valid and
 need not perform checks against their correctness. Removal of information
 from the cache is possible, but blanks will be left in the file, and


@@ -81,10 +81,10 @@ effects.
 Every item in every structure is stored as the index to that structure.
 What this means is that once the files is mmaped every data access has to
 go through a fixup stage to get a real memory pointer. This is done
 Every item in every structure is stored as the index to that structure.
 What this means is that once the files is mmaped every data access has to
 go through a fixup stage to get a real memory pointer. This is done

-by taking the tndex, multiplying it by the type size and then adding
+by taking the index, multiplying it by the type size and then adding

 it to the start address of the memory block. This sounds complex, but
 in C it is a single array dereference. Because all items are aligned to 
 it to the start address of the memory block. This sounds complex, but
 in C it is a single array dereference. Because all items are aligned to 

-their size and indexs are stored as multiples of the size of the structure
+their size and indexes are stored as multiples of the size of the structure

 the format is immediately portable to all possible architectures - BUT the
 generated files are -NOT-.
 
 the format is immediately portable to all possible architectures - BUT the
 generated files are -NOT-.
 


@@ -133,7 +133,8 @@ This is the first item in the file.
       unsigned short VersionSz;
       unsigned short DependencySz;
       unsigned short ProvidesSz;
       unsigned short VersionSz;
       unsigned short DependencySz;
       unsigned short ProvidesSz;

-
+      unsigned short VerFileSz;
+      

       // Structure counts
       unsigned long PackageCount;
       unsigned long VersionCount;
       // Structure counts
       unsigned long PackageCount;
       unsigned long VersionCount;


@@ -143,14 +144,20 @@ This is the first item in the file.
       // Offsets
       unsigned long FileList;              // PackageFile
       unsigned long StringList;            // StringItem
       // Offsets
       unsigned long FileList;              // PackageFile
       unsigned long StringList;            // StringItem

+      unsigned long VerSysName;            // StringTable
+      unsigned long Architecture;          // StringTable
+      unsigned long MaxVerFileSize;

       
       

-      // Pool structures
-      unsigned long PoolStart[6];
-      unsigned long PoolSize[6];
-      unsigned long PoolAln[6];
-      
+      // Allocation pools
+      struct
+      {
+         unsigned long ItemSize;
+        unsigned long Start;
+        unsigned long Count;
+      } Pools[7];
+

       // Package name lookup
       // Package name lookup

-      unsigned long HashTable[512];        // Package
+      unsigned long HashTable[2*1024];        // Package

    };
 </example>
 <taglist>
    };
 </example>
 <taglist>


@@ -173,9 +180,10 @@ be erased and rebuilt if it is true.
 <tag>PackageFileSz
 <tag>VersionSz
 <tag>DependencySz
 <tag>PackageFileSz
 <tag>VersionSz
 <tag>DependencySz

+<tag>VerFileSz

 <tag>ProvidesSz<item>
 *Sz contains the sizeof() that particular structure. It is used as an
 <tag>ProvidesSz<item>
 *Sz contains the sizeof() that particular structure. It is used as an

-extra consistancy check on the structure of the file.
+extra consistency check on the structure of the file.

 
 If any of the size values do not exactly match what the client expects then
 the client should refuse the load the file.
 
 If any of the size values do not exactly match what the client expects then
 the client should refuse the load the file.


@@ -184,13 +192,23 @@ the client should refuse the load the file.
 <tag>VersionCount
 <tag>DependsCount
 <tag>PackageFileCount<item>
 <tag>VersionCount
 <tag>DependsCount
 <tag>PackageFileCount<item>

-These indicate the number of each structure contianed in the cache. 
-PackageCount is especially usefull for generating user state structures. 
+These indicate the number of each structure contained in the cache. 
+PackageCount is especially useful for generating user state structures. 

 See Package::Id for more info.
 
 See Package::Id for more info.
 

+<tag>VerSysName<item>
+String representing the version system used for this cache
+
+<tag>Architecture<item>
+Architecture the cache was built against.
+
+<tag>MaxVerFileSize<item>
+The maximum size of a raw entry from the original Package file 
+(i.e. VerFile::Size) is stored here.
+

 <tag>FileList<item>
 This contains the index of the first PackageFile structure. The PackageFile
 <tag>FileList<item>
 This contains the index of the first PackageFile structure. The PackageFile

-structures are singely linked lists that represent all package files that
+structures are singly linked lists that represent all package files that

 have been merged into the cache.
 
 <tag>StringList<item>
 have been merged into the cache.
 
 <tag>StringList<item>


@@ -198,15 +216,14 @@ This contains a list of all the unique strings (string item type strings) in
 the cache. The parser reads this list into memory so it can match strings 
 against it.
 
 the cache. The parser reads this list into memory so it can match strings 
 against it.
 

-<tag>PoolStart
-<tag>PoolSize
-<tag>PoolAln<item>
+<tag>Pools<item>

 The Pool structures manage the allocation pools that the generator uses.
 The Pool structures manage the allocation pools that the generator uses.

-Start indicates the first byte of the pool, Size is the number of bytes
-remaining in the pool and Aln (alignment) is the structure size of the pool. 
-An Aln of 0 indicates the slot is empty. There should be the same number of
-slots as there are structure types. The generator stores this information 
-so future additions can make use of any unused pool blocks.
+Start indicates the first byte of the pool, Count is the number of objects
+remaining in the pool and ItemSize is the structure size (alignment factor)
+of the pool. An ItemSize of 0 indicates the pool is empty. There should be 
+the same number of pools as there are structure types. The generator 
+stores this information so future additions can make use of any unused pool 
+blocks.

 
 <tag>HashTable<item>
 HashTable is a hash table that provides indexing for all of the packages.
 
 <tag>HashTable<item>
 HashTable is a hash table that provides indexing for all of the packages.


@@ -223,9 +240,9 @@ function:
 </example>
 <p>
 By iterating over each entry in the hash table it is possible to iterate over 
 </example>
 <p>
 By iterating over each entry in the hash table it is possible to iterate over 

-the entire list of packages. Hash Collisions are handled with a singely linked
+the entire list of packages. Hash Collisions are handled with a singly linked

 list of packages based at the hash item. The linked list contains only 
 list of packages based at the hash item. The linked list contains only 

-packages that macth the hashing function.
+packages that match the hashing function.

 
 </taglist>
                                                                   <!-- }}} -->
 
 </taglist>
                                                                   <!-- }}} -->


@@ -233,7 +250,7 @@ packages that macth the hashing function.
 <!-- ===================================================================== -->
 <sect>Package
 <p>
 <!-- ===================================================================== -->
 <sect>Package
 <p>

-This contians information for a single unique package. There can be any
+This contains information for a single unique package. There can be any

 number of versions of a given package. Package exists in a singly
 linked list of package records starting at the hash index of the name in 
 the Header->HashTable.
 number of versions of a given package. Package exists in a singly
 linked list of package records starting at the hash index of the name in 
 the Header->HashTable.


@@ -243,9 +260,7 @@ the Header->HashTable.
       // Pointers
       unsigned long Name;              // Stringtable
       unsigned long VersionList;       // Version
       // Pointers
       unsigned long Name;              // Stringtable
       unsigned long VersionList;       // Version

-      unsigned long TargetVer;         // Version

       unsigned long CurrentVer;        // Version
       unsigned long CurrentVer;        // Version

-      unsigned long TargetDist;        // StringTable (StringItem)

       unsigned long Section;           // StringTable (StringItem)
       
       // Linked lists 
       unsigned long Section;           // StringTable (StringItem)
       
       // Linked lists 


@@ -260,7 +275,7 @@ the Header->HashTable.
 
       // Unique ID for this pkg
       unsigned short ID;
 
       // Unique ID for this pkg
       unsigned short ID;

-      unsigned short Flags;
+      unsigned long Flags;

    };
 </example>   
 
    };
 </example>   
 


@@ -269,25 +284,18 @@ the Header->HashTable.
 Name of the package.
 
 <tag>VersionList<item>
 Name of the package.
 
 <tag>VersionList<item>

-Base of a singely linked list of version structures. Each structure 
+Base of a singly linked list of version structures. Each structure 

 represents a unique version of the package. The version structures
 contain links into PackageFile and the original text file as well as
 represents a unique version of the package. The version structures
 contain links into PackageFile and the original text file as well as

-detailed infromation about the size and dependencies of the specific
+detailed information about the size and dependencies of the specific

 package. In this way multiple versions of a package can be cleanly handled
 package. In this way multiple versions of a package can be cleanly handled

-by the system. Furthermore, this linked list is guarenteed to be sorted
+by the system. Furthermore, this linked list is guaranteed to be sorted

 from Highest version to lowest version with no duplicate entries.
 
 from Highest version to lowest version with no duplicate entries.
 

-<tag>TargetVer

 <tag>CurrentVer<item>
 <tag>CurrentVer<item>

-This is an index (pointer) to the sub version that is being targeted for
-upgrading. CurrentVer is an index to the installed version, either can be
+CurrentVer is an index to the installed version, either can be

 0.
 
 0.
 

-<tag>TargetDist<item>
-This indicates the target distribution. Automatic upgrades should not go
-outside of the specified dist. If it is 0 then the global target dist should 
-be used. The string should be contained in the StringItem list.
-

 <tag>Section<item>
 This indicates the deduced section. It should be "Unknown" or the section
 of the last parsed item.
 <tag>Section<item>
 This indicates the deduced section. It should be "Unknown" or the section
 of the last parsed item.


@@ -305,14 +313,14 @@ This is a linked list of all provides for this package name.
 <tag>SelectedState
 <tag>InstState
 <tag>CurrentState<item>
 <tag>SelectedState
 <tag>InstState
 <tag>CurrentState<item>

-These corrispond to the 3 items in the Status field found in the status
+These correspond to the 3 items in the Status field found in the status

 file. See the section on defines for the possible values.
 <p>
 SelectedState is the state that the user wishes the package to be
 in.
 <p>
 InstState is the installation state of the package. This normally
 file. See the section on defines for the possible values.
 <p>
 SelectedState is the state that the user wishes the package to be
 in.
 <p>
 InstState is the installation state of the package. This normally

-should be Ok, but if the installation had an accident it may be otherwise.
+should be OK, but if the installation had an accident it may be otherwise.

 <p>
 CurrentState indicates if the package is installed, partially installed or
 not installed.
 <p>
 CurrentState indicates if the package is installed, partially installed or
 not installed.


@@ -325,7 +333,7 @@ status file emitter uses this to track which packages have been emitted
 already.
 
 <tag>Flags<item>
 already.
 
 <tag>Flags<item>

-Flags are some usefull indicators of the package's state. 
+Flags are some useful indicators of the package's state. 

 
 </taglist>
 
 
 </taglist>
 


@@ -334,7 +342,7 @@ Flags are some usefull indicators of the package's state.
 <!-- ===================================================================== -->
 <sect>PackageFile
 <p>
 <!-- ===================================================================== -->
 <sect>PackageFile
 <p>

-This contians information for a single package file. Package files are
+This contains information for a single package file. Package files are

 referenced by Version structures. This is a singly linked list based from
 Header.FileList
 <example>
 referenced by Version structures. This is a singly linked list based from
 Header.FileList
 <example>


@@ -342,14 +350,20 @@ Header.FileList
    {
       // Names
       unsigned long FileName;        // Stringtable
    {
       // Names
       unsigned long FileName;        // Stringtable

+      unsigned long Archive;         // Stringtable
+      unsigned long Component;       // Stringtable

       unsigned long Version;         // Stringtable
       unsigned long Version;         // Stringtable

-      unsigned long Distribution;    // Stringtable
+      unsigned long Origin;          // Stringtable
+      unsigned long Label;           // Stringtable
+      unsigned long Architecture;    // Stringtable
+      unsigned long Site;            // Stringtable
+      unsigned long IndexType;       // Stringtable

       unsigned long Size;            
       unsigned long Size;            

-      
+

       // Linked list
       unsigned long NextFile;        // PackageFile
       unsigned short ID;
       // Linked list
       unsigned long NextFile;        // PackageFile
       unsigned short ID;

-      unsigned short Flags;
+      unsigned long Flags;

       time_t mtime;                  // Modification time
    };
 </example>   
       time_t mtime;                  // Modification time
    };
 </example>   


@@ -358,11 +372,21 @@ Header.FileList
 <tag>FileName<item>
 Refers the the physical disk file that this PacakgeFile represents.
 
 <tag>FileName<item>
 Refers the the physical disk file that this PacakgeFile represents.
 

-<tag>Version<item>
-Version is the given version, ie 1.3.1, 2.4_revision_1 etc.
+<tag>Archive
+<tag>Component
+<tag>Version
+<tag>Origin
+<tag>Label
+<tag>Architecture
+<tag>NotAutomatic<item>
+This is the release information. Please see the files document for a 
+description of what the release information means.
+
+<tag>Site<item>
+The site the index file was fetched from.

 
 

-<tag>Distribution<item>
-Distribution is the symbolic name for this PackageFile, hamm,bo,rexx etc
+<tag>IndexType<item>
+A string indicating what sort of index file this is.

 
 <tag>Size<item>
 Size is provided as a simple check to ensure that the package file has not
 
 <tag>Size<item>
 Size is provided as a simple check to ensure that the package file has not


@@ -384,8 +408,8 @@ Modification time for the file at time of cache generation.
 <!-- ===================================================================== -->
 <sect>Version
 <p>
 <!-- ===================================================================== -->
 <sect>Version
 <p>

-This contians the information for a single version of a package. This is a
-singley linked list based from Package.Versionlist.
+This contains the information for a single version of a package. This is a
+single linked list based from Package.Versionlist.

 
 <p>
 The version list is always sorted from highest version to lowest version by
 
 <p>
 The version list is always sorted from highest version to lowest version by


@@ -396,18 +420,19 @@ VerStr).
    struct Version
    {
       unsigned long VerStr;            // Stringtable
    struct Version
    {
       unsigned long VerStr;            // Stringtable

-      unsigned long File;              // PackageFile

       unsigned long Section;           // StringTable (StringItem)
       unsigned long Section;           // StringTable (StringItem)

+      unsigned long Arch;              // StringTable

       
       // Lists
       
       // Lists

+      unsigned long FileList;          // VerFile

       unsigned long NextVer;           // Version
       unsigned long DependsList;       // Dependency
       unsigned long ParentPkg;         // Package
       unsigned long ProvidesList;      // Provides
       unsigned long NextVer;           // Version
       unsigned long DependsList;       // Dependency
       unsigned long ParentPkg;         // Package
       unsigned long ProvidesList;      // Provides

-     
-      unsigned long Offset;
+      

       unsigned long Size;
       unsigned long InstalledSize;
       unsigned long Size;
       unsigned long InstalledSize;

+      unsigned long Hash;

       unsigned short ID;
       unsigned char Priority;
    };
       unsigned short ID;
       unsigned char Priority;
    };


@@ -417,16 +442,19 @@ VerStr).
 <tag>VerStr<item>
 This is the complete version string.
 
 <tag>VerStr<item>
 This is the complete version string.
 

-<tag>File<item>
-References the PackageFile that this version came out of. File can be used
-to determine what distribution the Version applies to. If File is 0 then
-this is a blank version. The structure should also have a 0 in all other
-fields excluding VerStr and Possibly NextVer.
+<tag>FileList<item>
+References the all the PackageFile's that this version came out of. FileList 
+can be used to determine what distribution(s) the Version applies to. If 
+FileList is 0 then this is a blank version. The structure should also have 
+a 0 in all other fields excluding VerStr and Possibly NextVer.

 
 <tag>Section<item>
 This string indicates which section it is part of. The string should be
 contained in the StringItem list.
 
 
 <tag>Section<item>
 This string indicates which section it is part of. The string should be
 contained in the StringItem list.
 

+<tag>Arch<item>
+Architecture the package was compiled for.
+

 <tag>NextVer<item>
 Next step in the linked list.
 
 <tag>NextVer<item>
 Next step in the linked list.
 


@@ -440,15 +468,15 @@ to determine the package.
 <tag>ProvidesList<item>
 Head of the linked list of Provides::NextPkgProv, forward provides.
 
 <tag>ProvidesList<item>
 Head of the linked list of Provides::NextPkgProv, forward provides.
 

-<tag>Offset<item>
-The byte offset of the first line of this item in the specified
-PackageFile
-

 <tag>Size
 <tag>InstalledSize<item>
 <tag>Size
 <tag>InstalledSize<item>

-The archive size for this version. For debian this is the size of the .deb
+The archive size for this version. For Debian this is the size of the .deb

 file. Installed size is the uncompressed size for this version
 
 file. Installed size is the uncompressed size for this version
 

+<tag>Hash<item>
+This is a characteristic value representing this package. No two packages
+in existence should have the same VerStr and Hash with different contents.
+

 <tag>ID<item>
 See Package::ID.
 
 <tag>ID<item>
 See Package::ID.
 


@@ -562,6 +590,37 @@ Next link in the singly linked list of provides (based off package)
 <tag>NextPkgProv<item>
 Next link in the singly linked list of provides for 'Version'.
 
 <tag>NextPkgProv<item>
 Next link in the singly linked list of provides for 'Version'.
 

+</taglist>
+
+                                                                  <!-- }}} -->
+<!-- VerFile                                                          {{{ -->
+<!-- ===================================================================== -->
+<sect>VerFile
+<p>
+VerFile associates a version with a PackageFile, this allows a full 
+description of all Versions in all files (and hence all sources) under
+consideration.
+
+<example>
+    struct pkgCache::VerFile
+    {
+       unsigned long File;           // PackageFile
+       unsigned long NextFile;       // PkgVerFile
+       unsigned long Offset;
+       unsigned short Size;
+    }
+</example>
+<taglist>
+<tag>File<item>
+The index of the package file that this version was found in.
+
+<tag>NextFile<item>
+The next step in the linked list.
+
+<tag>Offset
+<tag>Size<item>
+These describe the exact position in the package file for the section from 
+this version.

 </taglist>
 
                                                                   <!-- }}} -->
 </taglist>
 
                                                                   <!-- }}} -->


@@ -570,7 +629,7 @@ Next link in the singly linked list of provides for 'Version'.
 <sect>StringItem
 <p>
 StringItem is used for generating single instances of strings. Some things
 <sect>StringItem
 <p>
 StringItem is used for generating single instances of strings. Some things

-like Section Name are are usefull to have as unique tags. It is part of 
+like Section Name are are useful to have as unique tags. It is part of 

 a linked list based at Header::StringList.
 <example>
    struct StringItem
 a linked list based at Header::StringList.
 <example>
    struct StringItem


@@ -691,6 +750,7 @@ Zero is used for unparsable or absent Priority fields.
 <p>
 <example>
 #define pkgFLAG_NotSource (1 << 0)
 <p>
 <example>
 #define pkgFLAG_NotSource (1 << 0)

+#define pkgFLAG_NotAutomatic (1 << 1)

 </example>
 </sect1>
 
 </example>
 </sect1>
 


@@ -715,7 +775,7 @@ allows the specification of a specific version and a target distribution.
 
 <p>
 Different section names on different versions is supported, but I 
 
 <p>
 Different section names on different versions is supported, but I 

-do not expect to use it. To simplify the GUI it will mearly use the section
+do not expect to use it. To simplify the GUI it will merely use the section

 in the Package structure. This should be okay as I hope sections do not change
 much.
 
 in the Package structure. This should be okay as I hope sections do not change
 much.
 


@@ -754,7 +814,7 @@ information. (/var/cache/apt, FHS2)
 <p>
 Caching of the info/*.list is an excellent place to start, by generating all
 the list files into a tree structure and reverse linking them to the package
 <p>
 Caching of the info/*.list is an excellent place to start, by generating all
 the list files into a tree structure and reverse linking them to the package

-structures in the main cache file major speed gains in dpkg might be achived.
+structures in the main cache file major speed gains in dpkg might be achieved.

 
                                                                   <!-- }}} -->
 
 
                                                                   <!-- }}} -->