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