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