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