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