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