apt-pkg/pkgcache.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 /**\file pkgcache.h
   4    \brief pkgCache - Structure definitions for the cache file
   5
   6    The goal of the cache file is two fold:
   7    Firstly to speed loading and processing of the package file array and
   8    secondly to reduce memory consumption of the package file array.
   9
  10    The implementation is aimed at an environment with many primary package
  11    files, for instance someone that has a Package file for their CD-ROM, a
  12    Package file for the latest version of the distribution on the CD-ROM and a
  13    package file for the development version. Always present is the information
  14    contained in the status file which might be considered a separate package
  15    file.
  16
  17    Please understand, this is designed as a <b>Cache file</b> it is not meant to be
  18    used on any system other than the one it was created for. It is not meant to
  19    be authoritative either, i.e. if a system crash or software failure occurs it
  20    must be perfectly acceptable for the cache file to be in an inconsistent
  21    state. Furthermore at any time the cache file may be erased without losing
  22    any information.
  23
  24    Also the structures and storage layout is optimized for use by the APT
  25    and may not be suitable for all purposes. However it should be possible
  26    to extend it with associate cache files that contain other information.
  27
  28    To keep memory use down the cache file only contains often used fields and
  29    fields that are inexpensive to store, the Package file has a full list of
  30    fields. Also the client may assume that all items are perfectly valid and
  31    need not perform checks against their correctness. Removal of information
  32    from the cache is possible, but blanks will be left in the file, and
  33    unused strings will also be present. The recommended implementation is to
  34    simply rebuild the cache each time any of the data files change. It is
  35    possible to add a new package file to the cache without any negative side
  36    effects.
  37
  38    <b>Note on Pointer access</b>
  39    Clients should always use the CacheIterators classes for access to the
  40    cache and the data in it. They also provide a simple STL-like method for
  41    traversing the links of the datastructure.
  42
  43    Every item in every structure is stored as the index to that structure.
  44    What this means is that once the files is mmaped every data access has to
  45    go through a fix up stage to get a real memory pointer. This is done
  46    by taking the index, multiplying it by the type size and then adding
  47    it to the start address of the memory block. This sounds complex, but
  48    in C it is a single array dereference. Because all items are aligned to
  49    their size and indexes are stored as multiples of the size of the structure
  50    the format is immediately portable to all possible architectures - BUT the
  51    generated files are -NOT-.
  52
  53    This scheme allows code like this to be written:
  54    <example>
  55      void *Map = mmap(...);
  56      Package *PkgList = (Package *)Map;
  57      Header *Head = (Header *)Map;
  58      char *Strings = (char *)Map;
  59      cout << (Strings + PkgList[Head->HashTable[0]]->Name) << endl;
  60    </example>
  61    Notice the lack of casting or multiplication. The net result is to return
  62    the name of the first package in the first hash bucket, without error
  63    checks.
  64
  65    The generator uses allocation pools to group similarly sized structures in
  66    large blocks to eliminate any alignment overhead. The generator also
  67    assures that no structures overlap and all indexes are unique. Although
  68    at first glance it may seem like there is the potential for two structures
  69    to exist at the same point the generator never allows this to happen.
  70    (See the discussion of free space pools)
  71
  72    See \ref pkgcachegen.h for more information about generating cache structures. */
  73                                                                         /*}}}*/
  74 #ifndef PKGLIB_PKGCACHE_H
  75 #define PKGLIB_PKGCACHE_H
  76
  77 #include <apt-pkg/mmap.h>
  78 #include <apt-pkg/macros.h>
  79
  80 #include <string>
  81 #include <time.h>
  82 #include <stdint.h>
  83
  84 #ifndef APT_8_CLEANER_HEADERS
  85 using std::string;
  86 #endif
  87
  88 #if APT_PKG_ABI >= 413
  89 // storing file sizes of indexes, which are way below 4 GB for now
  90 typedef uint32_t map_filesize_t;
  91 typedef map_filesize_t should_be_map_filesize_t;
  92 #else
  93 typedef unsigned long map_filesize_t;
  94 typedef unsigned int should_be_map_filesize_t;
  95 #endif
  96 #if APT_PKG_ABI >= 413
  97 // each package/group/dependency gets an id
  98 typedef uint32_t map_id_t;
  99 typedef map_id_t should_be_map_id_t;
 100 #else
 101 typedef unsigned long map_id_t;
 102 typedef unsigned int should_be_map_id_t;
 103 #endif
 104 #if APT_PKG_ABI >= 413
 105 // some files get an id, too, but in far less absolute numbers
 106 typedef uint16_t map_fileid_t;
 107 typedef map_fileid_t should_be_map_fileid_t;
 108 #else
 109 typedef unsigned long map_fileid_t;
 110 typedef unsigned int should_be_map_fileid_t;
 111 #endif
 112 #if APT_PKG_ABI >= 413
 113 // relative pointer from cache start
 114 typedef uint32_t map_pointer_t;
 115 #else
 116 typedef unsigned int map_pointer_t;
 117 #endif
 118 // same as the previous, but documented to be to a string item
 119 typedef map_pointer_t map_stringitem_t;
 120 #if APT_PKG_ABI >= 413
 121 typedef uint64_t should_be_uint64_t;
 122 typedef uint64_t should_be_uint64_small_t;
 123 #else
 124 typedef unsigned long long should_be_uint64_t;
 125 typedef unsigned long should_be_uint64_small_t;
 126 #endif
 127
 128 class pkgVersioningSystem;
 129 class pkgCache                                                          /*{{{*/
 130 {
 131    public:
 132    // Cache element predeclarations
 133    struct Header;
 134    struct Group;
 135    struct Package;
 136    struct PackageFile;
 137    struct Version;
 138    struct Description;
 139    struct Provides;
 140    struct Dependency;
 141    struct StringItem;
 142    struct VerFile;
 143    struct DescFile;
 144
 145    // Iterators
 146    template<typename Str, typename Itr> class Iterator;
 147    class GrpIterator;
 148    class PkgIterator;
 149    class VerIterator;
 150    class DescIterator;
 151    class DepIterator;
 152    class PrvIterator;
 153    class PkgFileIterator;
 154    class VerFileIterator;
 155    class DescFileIterator;
 156
 157    class Namespace;
 158
 159    // These are all the constants used in the cache structures
 160
 161    // WARNING - if you change these lists you must also edit
 162    // the stringification in pkgcache.cc and also consider whether
 163    // the cache file will become incompatible.
 164    struct Dep
 165    {
 166       enum DepType {Depends=1,PreDepends=2,Suggests=3,Recommends=4,
 167          Conflicts=5,Replaces=6,Obsoletes=7,DpkgBreaks=8,Enhances=9};
 168       /** \brief available compare operators
 169
 170           The lower 4 bits are used to indicate what operator is being specified and
 171           the upper 4 bits are flags. OR indicates that the next package is
 172           or'd with the current package. */
 173       enum DepCompareOp {Or=0x10,NoOp=0,LessEq=0x1,GreaterEq=0x2,Less=0x3,
 174          Greater=0x4,Equals=0x5,NotEquals=0x6};
 175    };
 176
 177    struct State
 178    {
 179       /** \brief priority of a package version
 180
 181           Zero is used for unparsable or absent Priority fields. */
 182       enum VerPriority {Required=1,Important=2,Standard=3,Optional=4,Extra=5};
 183       enum PkgSelectedState {Unknown=0,Install=1,Hold=2,DeInstall=3,Purge=4};
 184       enum PkgInstState {Ok=0,ReInstReq=1,HoldInst=2,HoldReInstReq=3};
 185       enum PkgCurrentState {NotInstalled=0,UnPacked=1,HalfConfigured=2,
 186            HalfInstalled=4,ConfigFiles=5,Installed=6,
 187            TriggersAwaited=7,TriggersPending=8};
 188    };
 189
 190    struct Flag
 191    {
 192       enum PkgFlags {Auto=(1<<0),Essential=(1<<3),Important=(1<<4)};
 193       enum PkgFFlags {
 194          NotSource=(1<<0), /*!< packages can't be fetched from here, e.g. dpkg/status file */
 195          NotAutomatic=(1<<1), /*!< archive has a default pin of 1 */
 196          ButAutomaticUpgrades=(1<<2), /*!< (together with the previous) archive has a default pin of 100 */
 197          LocalSource=(1<<3), /*!< local sources can't and will not be verified by hashes */
 198       };
 199    };
 200
 201    protected:
 202
 203    // Memory mapped cache file
 204    std::string CacheFile;
 205    MMap &Map;
 206
 207    map_id_t sHash(const std::string &S) const APT_PURE;
 208    map_id_t sHash(const char *S) const APT_PURE;
 209
 210    public:
 211
 212    // Pointers to the arrays of items
 213    Header *HeaderP;
 214    Group *GrpP;
 215    Package *PkgP;
 216    VerFile *VerFileP;
 217    DescFile *DescFileP;
 218    PackageFile *PkgFileP;
 219    Version *VerP;
 220    Description *DescP;
 221    Provides *ProvideP;
 222    Dependency *DepP;
 223    APT_DEPRECATED StringItem *StringItemP;
 224    char *StrP;
 225
 226    virtual bool ReMap(bool const &Errorchecks = true);
 227    inline bool Sync() {return Map.Sync();}
 228    inline MMap &GetMap() {return Map;}
 229    inline void *DataEnd() {return ((unsigned char *)Map.Data()) + Map.Size();}
 230
 231    // String hashing function (512 range)
 232    inline map_id_t Hash(const std::string &S) const {return sHash(S);}
 233    inline map_id_t Hash(const char *S) const {return sHash(S);}
 234
 235    // Useful transformation things
 236    const char *Priority(unsigned char Priority);
 237
 238    // Accessors
 239    GrpIterator FindGrp(const std::string &Name);
 240    PkgIterator FindPkg(const std::string &Name);
 241    PkgIterator FindPkg(const std::string &Name, const std::string &Arch);
 242
 243    Header &Head() {return *HeaderP;}
 244    inline GrpIterator GrpBegin();
 245    inline GrpIterator GrpEnd();
 246    inline PkgIterator PkgBegin();
 247    inline PkgIterator PkgEnd();
 248    inline PkgFileIterator FileBegin();
 249    inline PkgFileIterator FileEnd();
 250
 251    inline bool MultiArchCache() const { return MultiArchEnabled; }
 252    inline char const * NativeArch();
 253
 254    // Make me a function
 255    pkgVersioningSystem *VS;
 256
 257    // Converters
 258    static const char *CompTypeDeb(unsigned char Comp) APT_CONST;
 259    static const char *CompType(unsigned char Comp) APT_CONST;
 260    static const char *DepType(unsigned char Dep);
 261
 262    pkgCache(MMap *Map,bool DoMap = true);
 263    virtual ~pkgCache() {}
 264
 265 private:
 266    bool MultiArchEnabled;
 267    APT_HIDDEN PkgIterator SingleArchFindPkg(const std::string &Name);
 268 };
 269                                                                         /*}}}*/
 270 // Header structure                                                     /*{{{*/
 271 struct pkgCache::Header
 272 {
 273    /** \brief Signature information
 274
 275        This must contain the hex value 0x98FE76DC which is designed to
 276        verify that the system loading the image has the same byte order
 277        and byte size as the system saving the image */
 278    unsigned long Signature;
 279    /** These contain the version of the cache file */
 280    short MajorVersion;
 281    short MinorVersion;
 282    /** \brief indicates if the cache should be erased
 283
 284        Dirty is true if the cache file was opened for reading, the client
 285        expects to have written things to it and have not fully synced it.
 286        The file should be erased and rebuilt if it is true. */
 287    bool Dirty;
 288
 289    /** \brief Size of structure values
 290
 291        All *Sz variables contains the sizeof() that particular structure.
 292        It is used as an extra consistency check on the structure of the file.
 293
 294        If any of the size values do not exactly match what the client expects
 295        then the client should refuse the load the file. */
 296    unsigned short HeaderSz;
 297    unsigned short GroupSz;
 298    unsigned short PackageSz;
 299    unsigned short PackageFileSz;
 300    unsigned short VersionSz;
 301    unsigned short DescriptionSz;
 302    unsigned short DependencySz;
 303    unsigned short ProvidesSz;
 304    unsigned short VerFileSz;
 305    unsigned short DescFileSz;
 306
 307    /** \brief Structure counts
 308
 309        These indicate the number of each structure contained in the cache.
 310        PackageCount is especially useful for generating user state structures.
 311        See Package::Id for more info. */
 312    map_id_t GroupCount;
 313    map_id_t PackageCount;
 314    map_id_t VersionCount;
 315    map_id_t DescriptionCount;
 316    map_id_t DependsCount;
 317    map_fileid_t PackageFileCount;
 318    map_fileid_t VerFileCount;
 319    map_fileid_t DescFileCount;
 320    map_id_t ProvidesCount;
 321
 322    /** \brief index of the first PackageFile structure
 323
 324        The PackageFile structures are singly linked lists that represent
 325        all package files that have been merged into the cache. */
 326    map_pointer_t FileList;
 327 #if APT_PKG_ABI < 413
 328    APT_DEPRECATED map_pointer_t StringList;
 329 #endif
 330    /** \brief String representing the version system used */
 331    map_pointer_t VerSysName;
 332    /** \brief native architecture the cache was built against */
 333    map_pointer_t Architecture;
 334 #if APT_PKG_ABI >= 413
 335    /** \brief all architectures the cache was built against */
 336    map_pointer_t Architectures;
 337 #endif
 338    /** \brief The maximum size of a raw entry from the original Package file */
 339    map_filesize_t MaxVerFileSize;
 340    /** \brief The maximum size of a raw entry from the original Translation file */
 341    map_filesize_t MaxDescFileSize;
 342
 343    /** \brief The Pool structures manage the allocation pools that the generator uses
 344
 345        Start indicates the first byte of the pool, Count is the number of objects
 346        remaining in the pool and ItemSize is the structure size (alignment factor)
 347        of the pool. An ItemSize of 0 indicates the pool is empty. There should be
 348        the same number of pools as there are structure types. The generator
 349        stores this information so future additions can make use of any unused pool
 350        blocks. */
 351    DynamicMMap::Pool Pools[9];
 352
 353    /** \brief hash tables providing rapid group/package name lookup
 354
 355        Each group/package name is inserted into a hash table using pkgCache::Hash(const &string)
 356        By iterating over each entry in the hash table it is possible to iterate over
 357        the entire list of packages. Hash Collisions are handled with a singly linked
 358        list of packages based at the hash item. The linked list contains only
 359        packages that match the hashing function.
 360        In the PkgHashTable is it possible that multiple packages have the same name -
 361        these packages are stored as a sequence in the list.
 362        The size of both tables is the same. */
 363 #if APT_PKG_ABI >= 413
 364    unsigned int HashTableSize;
 365    unsigned int GetHashTableSize() const { return HashTableSize; }
 366    void SetHashTableSize(unsigned int const sz) { HashTableSize = sz; }
 367    map_pointer_t GetArchitectures() const { return Architectures; }
 368    void SetArchitectures(map_pointer_t const idx) { Architectures = idx; }
 369 #else
 370    // BEWARE: these tables are pretty much empty and just here for abi compat
 371    map_ptrloc PkgHashTable[2*1048];
 372    map_ptrloc GrpHashTable[2*1048];
 373    unsigned int GetHashTableSize() const { return PkgHashTable[0]; }
 374    void SetHashTableSize(unsigned int const sz) { PkgHashTable[0] = sz; }
 375    map_pointer_t GetArchitectures() const { return PkgHashTable[1]; }
 376    void SetArchitectures(map_pointer_t const idx) { PkgHashTable[1] = idx; }
 377 #endif
 378    map_pointer_t * PkgHashTableP() const { return (map_pointer_t*) (this + 1); }
 379    map_pointer_t * GrpHashTableP() const { return PkgHashTableP() + GetHashTableSize(); }
 380
 381    /** \brief Size of the complete cache file */
 382    should_be_uint64_small_t CacheFileSize;
 383
 384    bool CheckSizes(Header &Against) const APT_PURE;
 385    Header();
 386 };
 387                                                                         /*}}}*/
 388 // Group structure                                                      /*{{{*/
 389 /** \brief groups architecture depending packages together
 390
 391     On or more packages with the same name form a group, so we have
 392     a simple way to access a package built for different architectures
 393     Group exists in a singly linked list of group records starting at
 394     the hash index of the name in the pkgCache::Header::GrpHashTable */
 395 struct pkgCache::Group
 396 {
 397    /** \brief Name of the group */
 398    map_stringitem_t Name;
 399
 400    // Linked List
 401    /** \brief Link to the first package which belongs to the group */
 402    map_pointer_t FirstPackage;  // Package
 403    /** \brief Link to the last package which belongs to the group */
 404    map_pointer_t LastPackage;   // Package
 405    /** \brief Link to the next Group */
 406    map_pointer_t Next;          // Group
 407    /** \brief unique sequel ID */
 408    should_be_map_id_t ID;
 409
 410 };
 411                                                                         /*}}}*/
 412 // Package structure                                                    /*{{{*/
 413 /** \brief contains information for a single unique package
 414
 415     There can be any number of versions of a given package.
 416     Package exists in a singly linked list of package records starting at
 417     the hash index of the name in the pkgCache::Header::PkgHashTable
 418
 419     A package can be created for every architecture so package names are
 420     not unique, but it is guaranteed that packages with the same name
 421     are sequencel ordered in the list. Packages with the same name can be
 422     accessed with the Group.
 423 */
 424 struct pkgCache::Package
 425 {
 426    /** \brief Name of the package
 427     * Note that the access method Name() will remain. It is just this data member
 428     * deprecated as this information is already stored and available via the
 429     * associated Group – so it is wasting precious binary cache space */
 430    APT_DEPRECATED map_stringitem_t Name;
 431    /** \brief Architecture of the package */
 432    map_stringitem_t Arch;
 433    /** \brief Base of a singly linked list of versions
 434
 435        Each structure represents a unique version of the package.
 436        The version structures contain links into PackageFile and the
 437        original text file as well as detailed information about the size
 438        and dependencies of the specific package. In this way multiple
 439        versions of a package can be cleanly handled by the system.
 440        Furthermore, this linked list is guaranteed to be sorted
 441        from Highest version to lowest version with no duplicate entries. */
 442    map_pointer_t VersionList;       // Version
 443    /** \brief index to the installed version */
 444    map_pointer_t CurrentVer;        // Version
 445    /** \brief indicates nothing (consistently)
 446        This field used to contain ONE section the package belongs to,
 447        if those differs between versions it is a RANDOM one.
 448        The Section() method tries to reproduce it, but the only sane
 449        thing to do is use the Section field from the version! */
 450    APT_DEPRECATED map_ptrloc Section; // StringItem
 451    /** \brief index of the group this package belongs to */
 452    map_pointer_t Group;             // Group the Package belongs to
 453
 454    // Linked list
 455    /** \brief Link to the next package in the same bucket */
 456    map_pointer_t NextPackage;       // Package
 457    /** \brief List of all dependencies on this package */
 458    map_pointer_t RevDepends;        // Dependency
 459    /** \brief List of all "packages" this package provide */
 460    map_pointer_t ProvidesList;      // Provides
 461
 462    // Install/Remove/Purge etc
 463    /** \brief state that the user wishes the package to be in */
 464    unsigned char SelectedState;     // What
 465    /** \brief installation state of the package
 466
 467        This should be "ok" but in case the installation failed
 468        it will be different.
 469    */
 470    unsigned char InstState;         // Flags
 471    /** \brief indicates if the package is installed */
 472    unsigned char CurrentState;      // State
 473
 474    /** \brief unique sequel ID
 475
 476        ID is a unique value from 0 to Header->PackageCount assigned by the generator.
 477        This allows clients to create an array of size PackageCount and use it to store
 478        state information for the package map. For instance the status file emitter uses
 479        this to track which packages have been emitted already. */
 480    should_be_map_id_t ID;
 481    /** \brief some useful indicators of the package's state */
 482    unsigned long Flags;
 483 };
 484                                                                         /*}}}*/
 485 // Package File structure                                               /*{{{*/
 486 /** \brief stores information about the files used to generate the cache
 487
 488     Package files are referenced by Version structures to be able to know
 489     after the generation still from which Packages file includes this Version
 490     as we need this information later on e.g. for pinning. */
 491 struct pkgCache::PackageFile
 492 {
 493    /** \brief physical disk file that this PackageFile represents */
 494    map_stringitem_t FileName;
 495    /** \brief the release information
 496
 497        Please see the files document for a description of what the
 498        release information means. */
 499    map_stringitem_t Archive;
 500    map_stringitem_t Codename;
 501    map_stringitem_t Component;
 502    map_stringitem_t Version;
 503    map_stringitem_t Origin;
 504    map_stringitem_t Label;
 505    map_stringitem_t Architecture;
 506    /** \brief The site the index file was fetched from */
 507    map_stringitem_t Site;
 508    /** \brief indicates what sort of index file this is
 509
 510        @TODO enumerate at least the possible indexes */
 511    map_stringitem_t IndexType;
 512    /** \brief Size of the file
 513
 514        Used together with the modification time as a
 515        simple check to ensure that the Packages
 516        file has not been altered since Cache generation. */
 517    map_filesize_t Size;
 518    /** \brief Modification time for the file */
 519    time_t mtime;
 520
 521    /** @TODO document PackageFile::Flags */
 522    unsigned long Flags;
 523
 524    // Linked list
 525    /** \brief Link to the next PackageFile in the Cache */
 526    map_pointer_t NextFile;        // PackageFile
 527    /** \brief unique sequel ID */
 528    should_be_map_fileid_t ID;
 529 };
 530                                                                         /*}}}*/
 531 // VerFile structure                                                    /*{{{*/
 532 /** \brief associates a version with a PackageFile
 533
 534     This allows a full description of all Versions in all files
 535     (and hence all sources) under consideration. */
 536 struct pkgCache::VerFile
 537 {
 538    /** \brief index of the package file that this version was found in */
 539    map_pointer_t File;           // PackageFile
 540    /** \brief next step in the linked list */
 541    map_pointer_t NextFile;       // PkgVerFile
 542    /** \brief position in the package file */
 543    should_be_map_filesize_t Offset;         // File offset
 544    /** @TODO document pkgCache::VerFile::Size */
 545    map_filesize_t Size;
 546 };
 547                                                                         /*}}}*/
 548 // DescFile structure                                                   /*{{{*/
 549 /** \brief associates a description with a Translation file */
 550 struct pkgCache::DescFile
 551 {
 552    /** \brief index of the file that this description was found in */
 553    map_pointer_t File;           // PackageFile
 554    /** \brief next step in the linked list */
 555    map_pointer_t NextFile;       // PkgVerFile
 556    /** \brief position in the file */
 557    should_be_map_filesize_t Offset;         // File offset
 558    /** @TODO document pkgCache::DescFile::Size */
 559    map_filesize_t Size;
 560 };
 561                                                                         /*}}}*/
 562 // Version structure                                                    /*{{{*/
 563 /** \brief information for a single version of a package
 564
 565     The version list is always sorted from highest version to lowest
 566     version by the generator. Equal version numbers are either merged
 567     or handled as separate versions based on the Hash value. */
 568 struct pkgCache::Version
 569 {
 570    /** \brief complete version string */
 571    map_stringitem_t VerStr;
 572    /** \brief section this version is filled in */
 573    map_stringitem_t Section;
 574 #if APT_PKG_ABI >= 413
 575    /** \brief source package name this version comes from
 576       Always contains the name, even if it is the same as the binary name */
 577    map_stringitem_t SourcePkgName;
 578    /** \brief source version this version comes from
 579       Always contains the version string, even if it is the same as the binary version */
 580    map_stringitem_t SourceVerStr;
 581 #endif
 582
 583    /** \brief Multi-Arch capabilities of a package version */
 584    enum VerMultiArch { None = 0, /*!< is the default and doesn't trigger special behaviour */
 585                        All = (1<<0), /*!< will cause that Ver.Arch() will report "all" */
 586                        Foreign = (1<<1), /*!< can satisfy dependencies in another architecture */
 587                        Same = (1<<2), /*!< can be co-installed with itself from other architectures */
 588                        Allowed = (1<<3), /*!< other packages are allowed to depend on thispkg:any */
 589                        AllForeign = All | Foreign,
 590                        AllAllowed = All | Allowed };
 591    /** \brief stores the MultiArch capabilities of this version
 592
 593        Flags used are defined in pkgCache::Version::VerMultiArch
 594    */
 595    unsigned char MultiArch;
 596
 597    /** \brief references all the PackageFile's that this version came from
 598
 599        FileList can be used to determine what distribution(s) the Version
 600        applies to. If FileList is 0 then this is a blank version.
 601        The structure should also have a 0 in all other fields excluding
 602        pkgCache::Version::VerStr and Possibly pkgCache::Version::NextVer. */
 603    map_pointer_t FileList;          // VerFile
 604    /** \brief next (lower or equal) version in the linked list */
 605    map_pointer_t NextVer;           // Version
 606    /** \brief next description in the linked list */
 607    map_pointer_t DescriptionList;   // Description
 608    /** \brief base of the dependency list */
 609    map_pointer_t DependsList;       // Dependency
 610    /** \brief links to the owning package
 611
 612        This allows reverse dependencies to determine the package */
 613    map_pointer_t ParentPkg;         // Package
 614    /** \brief list of pkgCache::Provides */
 615    map_pointer_t ProvidesList;      // Provides
 616
 617    /** \brief archive size for this version
 618
 619        For Debian this is the size of the .deb file. */
 620    should_be_uint64_t Size; // These are the .deb size
 621    /** \brief uncompressed size for this version */
 622    should_be_uint64_t InstalledSize;
 623    /** \brief characteristic value representing this version
 624
 625        No two packages in existence should have the same VerStr
 626        and Hash with different contents. */
 627    unsigned short Hash;
 628    /** \brief unique sequel ID */
 629    should_be_map_id_t ID;
 630    /** \brief parsed priority value */
 631    unsigned char Priority;
 632 };
 633                                                                         /*}}}*/
 634 // Description structure                                                /*{{{*/
 635 /** \brief datamember of a linked list of available description for a version */
 636 struct pkgCache::Description
 637 {
 638    /** \brief Language code of this description (translation)
 639
 640        If the value has a 0 length then this is read using the Package
 641        file else the Translation-CODE file is used. */
 642    map_stringitem_t language_code;
 643    /** \brief MD5sum of the original description
 644
 645        Used to map Translations of a description to a version
 646        and to check that the Translation is up-to-date. */
 647    map_stringitem_t md5sum;
 648
 649    /** @TODO document pkgCache::Description::FileList */
 650    map_pointer_t FileList;          // DescFile
 651    /** \brief next translation for this description */
 652    map_pointer_t NextDesc;          // Description
 653    /** \brief the text is a description of this package */
 654    map_pointer_t ParentPkg;         // Package
 655
 656    /** \brief unique sequel ID */
 657    should_be_map_id_t ID;
 658 };
 659                                                                         /*}}}*/
 660 // Dependency structure                                                 /*{{{*/
 661 /** \brief information for a single dependency record
 662
 663     The records are split up like this to ease processing by the client.
 664     The base of the linked list is pkgCache::Version::DependsList.
 665     All forms of dependencies are recorded here including Depends,
 666     Recommends, Suggests, Enhances, Conflicts, Replaces and Breaks. */
 667 struct pkgCache::Dependency
 668 {
 669    /** \brief string of the version the dependency is applied against */
 670    map_stringitem_t Version;
 671    /** \brief index of the package this depends applies to
 672
 673        The generator will - if the package does not already exist -
 674        create a blank (no version records) package. */
 675    map_pointer_t Package;         // Package
 676    /** \brief next dependency of this version */
 677    map_pointer_t NextDepends;     // Dependency
 678    /** \brief next reverse dependency of this package */
 679    map_pointer_t NextRevDepends;  // Dependency
 680    /** \brief version of the package which has the reverse depends */
 681    map_pointer_t ParentVer;       // Version
 682
 683    /** \brief unique sequel ID */
 684    should_be_map_id_t ID;
 685    /** \brief Dependency type - Depends, Recommends, Conflicts, etc */
 686    unsigned char Type;
 687    /** \brief comparison operator specified on the depends line
 688
 689        If the high bit is set then it is a logical OR with the previous record. */
 690    unsigned char CompareOp;
 691 };
 692                                                                         /*}}}*/
 693 // Provides structure                                                   /*{{{*/
 694 /** \brief handles virtual packages
 695
 696     When a Provides: line is encountered a new provides record is added
 697     associating the package with a virtual package name.
 698     The provides structures are linked off the package structures.
 699     This simplifies the analysis of dependencies and other aspects A provides
 700     refers to a specific version of a specific package, not all versions need to
 701     provide that provides.*/
 702 struct pkgCache::Provides
 703 {
 704    /** \brief index of the package providing this */
 705    map_pointer_t ParentPkg;        // Package
 706    /** \brief index of the version this provide line applies to */
 707    map_pointer_t Version;          // Version
 708    /** \brief version in the provides line (if any)
 709
 710        This version allows dependencies to depend on specific versions of a
 711        Provides, as well as allowing Provides to override existing packages.
 712        This is experimental. Note that Debian doesn't allow versioned provides */
 713    map_stringitem_t ProvideVersion;
 714    /** \brief next provides (based of package) */
 715    map_pointer_t NextProvides;     // Provides
 716    /** \brief next provides (based of version) */
 717    map_pointer_t NextPkgProv;      // Provides
 718 };
 719                                                                         /*}}}*/
 720 // UNUSED StringItem structure                                          /*{{{*/
 721 struct APT_DEPRECATED  pkgCache::StringItem
 722 {
 723    /** \brief string this refers to */
 724    map_ptrloc String;        // StringItem
 725    /** \brief Next link in the chain */
 726    map_ptrloc NextItem;      // StringItem
 727 };
 728                                                                         /*}}}*/
 729
 730 inline char const * pkgCache::NativeArch()
 731         { return StrP + HeaderP->Architecture; }
 732
 733 #include <apt-pkg/cacheiterators.h>
 734
 735 inline pkgCache::GrpIterator pkgCache::GrpBegin()
 736        {return GrpIterator(*this);}
 737 inline pkgCache::GrpIterator pkgCache::GrpEnd()
 738        {return GrpIterator(*this,GrpP);}
 739 inline pkgCache::PkgIterator pkgCache::PkgBegin()
 740        {return PkgIterator(*this);}
 741 inline pkgCache::PkgIterator pkgCache::PkgEnd()
 742        {return PkgIterator(*this,PkgP);}
 743 inline pkgCache::PkgFileIterator pkgCache::FileBegin()
 744        {return PkgFileIterator(*this,PkgFileP + HeaderP->FileList);}
 745 inline pkgCache::PkgFileIterator pkgCache::FileEnd()
 746        {return PkgFileIterator(*this,PkgFileP);}
 747
 748 // Oh I wish for Real Name Space Support
 749 class pkgCache::Namespace                                               /*{{{*/
 750 {
 751    public:
 752    typedef pkgCache::GrpIterator GrpIterator;
 753    typedef pkgCache::PkgIterator PkgIterator;
 754    typedef pkgCache::VerIterator VerIterator;
 755    typedef pkgCache::DescIterator DescIterator;
 756    typedef pkgCache::DepIterator DepIterator;
 757    typedef pkgCache::PrvIterator PrvIterator;
 758    typedef pkgCache::PkgFileIterator PkgFileIterator;
 759    typedef pkgCache::VerFileIterator VerFileIterator;
 760    typedef pkgCache::Version Version;
 761    typedef pkgCache::Description Description;
 762    typedef pkgCache::Package Package;
 763    typedef pkgCache::Header Header;
 764    typedef pkgCache::Dep Dep;
 765    typedef pkgCache::Flag Flag;
 766 };
 767                                                                         /*}}}*/
 768 #endif