apt-pkg/pkgcache.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 /**\file pkgcache.h
   4    \brief pkgCache - Structure definitions for the cache file
   5
   6    The goal of the cache file is two fold:
   7    Firstly to speed loading and processing of the package file array and
   8    secondly to reduce memory consumption of the package file array.
   9
  10    The implementation is aimed at an environment with many primary package
  11    files, for instance someone that has a Package file for their CD-ROM, a
  12    Package file for the latest version of the distribution on the CD-ROM and a
  13    package file for the development version. Always present is the information
  14    contained in the status file which might be considered a separate package
  15    file.
  16
  17    Please understand, this is designed as a <b>Cache file</b> it is not meant to be
  18    used on any system other than the one it was created for. It is not meant to
  19    be authoritative either, i.e. if a system crash or software failure occurs it
  20    must be perfectly acceptable for the cache file to be in an inconsistent
  21    state. Furthermore at any time the cache file may be erased without losing
  22    any information.
  23
  24    Also the structures and storage layout is optimized for use by the APT
  25    and may not be suitable for all purposes. However it should be possible
  26    to extend it with associate cache files that contain other information.
  27
  28    To keep memory use down the cache file only contains often used fields and
  29    fields that are inexpensive to store, the Package file has a full list of
  30    fields. Also the client may assume that all items are perfectly valid and
  31    need not perform checks against their correctness. Removal of information
  32    from the cache is possible, but blanks will be left in the file, and
  33    unused strings will also be present. The recommended implementation is to
  34    simply rebuild the cache each time any of the data files change. It is
  35    possible to add a new package file to the cache without any negative side
  36    effects.
  37
  38    <b>Note on Pointer access</b>
  39    Clients should always use the CacheIterators classes for access to the
  40    cache and the data in it. They also provide a simple STL-like method for
  41    traversing the links of the datastructure.
  42
  43    Every item in every structure is stored as the index to that structure.
  44    What this means is that once the files is mmaped every data access has to
  45    go through a fix up stage to get a real memory pointer. This is done
  46    by taking the index, multiplying it by the type size and then adding
  47    it to the start address of the memory block. This sounds complex, but
  48    in C it is a single array dereference. Because all items are aligned to
  49    their size and indexes are stored as multiples of the size of the structure
  50    the format is immediately portable to all possible architectures - BUT the
  51    generated files are -NOT-.
  52
  53    This scheme allows code like this to be written:
  54    <example>
  55      void *Map = mmap(...);
  56      Package *PkgList = (Package *)Map;
  57      Header *Head = (Header *)Map;
  58      char *Strings = (char *)Map;
  59      cout << (Strings + PkgList[Head->HashTable[0]]->Name) << endl;
  60    </example>
  61    Notice the lack of casting or multiplication. The net result is to return
  62    the name of the first package in the first hash bucket, without error
  63    checks.
  64
  65    The generator uses allocation pools to group similarly sized structures in
  66    large blocks to eliminate any alignment overhead. The generator also
  67    assures that no structures overlap and all indexes are unique. Although
  68    at first glance it may seem like there is the potential for two structures
  69    to exist at the same point the generator never allows this to happen.
  70    (See the discussion of free space pools)
  71
  72    See \ref pkgcachegen.h for more information about generating cache structures. */
  73                                                                         /*}}}*/
  74 #ifndef PKGLIB_PKGCACHE_H
  75 #define PKGLIB_PKGCACHE_H
  76
  77 #include <apt-pkg/mmap.h>
  78 #include <apt-pkg/macros.h>
  79
  80 #include <string>
  81 #include <time.h>
  82 #include <stdint.h>
  83
  84 #ifndef APT_8_CLEANER_HEADERS
  85 using std::string;
  86 #endif
  87
  88 #if APT_PKG_ABI >= 413
  89 // storing file sizes of indexes, which are way below 4 GB for now
  90 typedef uint32_t map_filesize_t;
  91 typedef map_filesize_t should_be_map_filesize_t;
  92 #else
  93 typedef unsigned long map_filesize_t;
  94 typedef unsigned int should_be_map_filesize_t;
  95 #endif
  96 #if APT_PKG_ABI >= 413
  97 // each package/group/dependency gets an id
  98 typedef uint32_t map_id_t;
  99 typedef map_id_t should_be_map_id_t;
 100 #else
 101 typedef unsigned long map_id_t;
 102 typedef unsigned int should_be_map_id_t;
 103 #endif
 104 #if APT_PKG_ABI >= 413
 105 // some files get an id, too, but in far less absolute numbers
 106 typedef uint16_t map_fileid_t;
 107 typedef map_fileid_t should_be_map_fileid_t;
 108 #else
 109 typedef unsigned long map_fileid_t;
 110 typedef unsigned int should_be_map_fileid_t;
 111 #endif
 112 #if APT_PKG_ABI >= 413
 113 // relative pointer from cache start
 114 typedef uint32_t map_pointer_t;
 115 #else
 116 typedef unsigned int map_pointer_t;
 117 #endif
 118 // same as the previous, but documented to be to a string item
 119 typedef map_pointer_t map_stringitem_t;
 120 #if APT_PKG_ABI >= 413
 121 typedef uint64_t should_be_uint64_t;
 122 typedef uint64_t should_be_uint64_small_t;
 123 #else
 124 typedef unsigned long long should_be_uint64_t;
 125 typedef unsigned long should_be_uint64_small_t;
 126 #endif
 127
 128 class pkgVersioningSystem;
 129 class pkgCache                                                          /*{{{*/
 130 {
 131    public:
 132    // Cache element predeclarations
 133    struct Header;
 134    struct Group;
 135    struct Package;
 136    struct ReleaseFile;
 137    struct PackageFile;
 138    struct Version;
 139    struct Description;
 140    struct Provides;
 141    struct Dependency;
 142    struct DependencyData;
 143    struct StringItem;
 144    struct VerFile;
 145    struct DescFile;
 146
 147    // Iterators
 148    template<typename Str, typename Itr> class Iterator;
 149    class GrpIterator;
 150    class PkgIterator;
 151    class VerIterator;
 152    class DescIterator;
 153    class DepIterator;
 154    class PrvIterator;
 155    class RlsFileIterator;
 156    class PkgFileIterator;
 157    class VerFileIterator;
 158    class DescFileIterator;
 159
 160    class Namespace;
 161
 162    // These are all the constants used in the cache structures
 163
 164    // WARNING - if you change these lists you must also edit
 165    // the stringification in pkgcache.cc and also consider whether
 166    // the cache file will become incompatible.
 167    struct Dep
 168    {
 169       enum DepType {Depends=1,PreDepends=2,Suggests=3,Recommends=4,
 170          Conflicts=5,Replaces=6,Obsoletes=7,DpkgBreaks=8,Enhances=9};
 171       /** \brief available compare operators
 172
 173           The lower 4 bits are used to indicate what operator is being specified and
 174           the upper 4 bits are flags. OR indicates that the next package is
 175           or'd with the current package. */
 176       enum DepCompareOp {Or=0x10,NoOp=0,LessEq=0x1,GreaterEq=0x2,Less=0x3,
 177          Greater=0x4,Equals=0x5,NotEquals=0x6};
 178    };
 179
 180    struct State
 181    {
 182       /** \brief priority of a package version
 183
 184           Zero is used for unparsable or absent Priority fields. */
 185       enum VerPriority {Required=1,Important=2,Standard=3,Optional=4,Extra=5};
 186       enum PkgSelectedState {Unknown=0,Install=1,Hold=2,DeInstall=3,Purge=4};
 187       enum PkgInstState {Ok=0,ReInstReq=1,HoldInst=2,HoldReInstReq=3};
 188       enum PkgCurrentState {NotInstalled=0,UnPacked=1,HalfConfigured=2,
 189            HalfInstalled=4,ConfigFiles=5,Installed=6,
 190            TriggersAwaited=7,TriggersPending=8};
 191    };
 192
 193    struct Flag
 194    {
 195       enum PkgFlags {Auto=(1<<0),Essential=(1<<3),Important=(1<<4)};
 196       enum PkgFFlags {
 197          NotSource=(1<<0), /*!< packages can't be fetched from here, e.g. dpkg/status file */
 198          LocalSource=(1<<1), /*!< local sources can't and will not be verified by hashes */
 199          NoPackages=(1<<2), /*!< the file includes no package records itself, but additions like Translations */
 200       };
 201       enum ReleaseFileFlags {
 202          NotAutomatic=(1<<0), /*!< archive has a default pin of 1 */
 203          ButAutomaticUpgrades=(1<<1), /*!< (together with the previous) archive has a default pin of 100 */
 204       };
 205    };
 206
 207    protected:
 208
 209    // Memory mapped cache file
 210    std::string CacheFile;
 211    MMap &Map;
 212
 213    map_id_t sHash(const std::string &S) const APT_PURE;
 214    map_id_t sHash(const char *S) const APT_PURE;
 215
 216    public:
 217
 218    // Pointers to the arrays of items
 219    Header *HeaderP;
 220    Group *GrpP;
 221    Package *PkgP;
 222    VerFile *VerFileP;
 223    DescFile *DescFileP;
 224    ReleaseFile *RlsFileP;
 225    PackageFile *PkgFileP;
 226    Version *VerP;
 227    Description *DescP;
 228    Provides *ProvideP;
 229    Dependency *DepP;
 230    DependencyData *DepDataP;
 231    APT_DEPRECATED StringItem *StringItemP;
 232    char *StrP;
 233
 234    virtual bool ReMap(bool const &Errorchecks = true);
 235    inline bool Sync() {return Map.Sync();}
 236    inline MMap &GetMap() {return Map;}
 237    inline void *DataEnd() {return ((unsigned char *)Map.Data()) + Map.Size();}
 238
 239    // String hashing function (512 range)
 240    inline map_id_t Hash(const std::string &S) const {return sHash(S);}
 241    inline map_id_t Hash(const char *S) const {return sHash(S);}
 242
 243    // Useful transformation things
 244    const char *Priority(unsigned char Priority);
 245
 246    // Accessors
 247    GrpIterator FindGrp(const std::string &Name);
 248    PkgIterator FindPkg(const std::string &Name);
 249    PkgIterator FindPkg(const std::string &Name, const std::string &Arch);
 250
 251    Header &Head() {return *HeaderP;}
 252    inline GrpIterator GrpBegin();
 253    inline GrpIterator GrpEnd();
 254    inline PkgIterator PkgBegin();
 255    inline PkgIterator PkgEnd();
 256    inline PkgFileIterator FileBegin();
 257    inline PkgFileIterator FileEnd();
 258    inline RlsFileIterator RlsFileBegin();
 259    inline RlsFileIterator RlsFileEnd();
 260
 261    inline bool MultiArchCache() const { return MultiArchEnabled; }
 262    inline char const * NativeArch();
 263
 264    // Make me a function
 265    pkgVersioningSystem *VS;
 266
 267    // Converters
 268    static const char *CompTypeDeb(unsigned char Comp) APT_CONST;
 269    static const char *CompType(unsigned char Comp) APT_CONST;
 270    static const char *DepType(unsigned char Dep);
 271
 272    pkgCache(MMap *Map,bool DoMap = true);
 273    virtual ~pkgCache();
 274
 275 private:
 276    void * const d;
 277    bool MultiArchEnabled;
 278    APT_HIDDEN PkgIterator SingleArchFindPkg(const std::string &Name);
 279 };
 280                                                                         /*}}}*/
 281 // Header structure                                                     /*{{{*/
 282 struct pkgCache::Header
 283 {
 284    /** \brief Signature information
 285
 286        This must contain the hex value 0x98FE76DC which is designed to
 287        verify that the system loading the image has the same byte order
 288        and byte size as the system saving the image */
 289    unsigned long Signature;
 290    /** These contain the version of the cache file */
 291    short MajorVersion;
 292    short MinorVersion;
 293    /** \brief indicates if the cache should be erased
 294
 295        Dirty is true if the cache file was opened for reading, the client
 296        expects to have written things to it and have not fully synced it.
 297        The file should be erased and rebuilt if it is true. */
 298    bool Dirty;
 299
 300    /** \brief Size of structure values
 301
 302        All *Sz variables contains the sizeof() that particular structure.
 303        It is used as an extra consistency check on the structure of the file.
 304
 305        If any of the size values do not exactly match what the client expects
 306        then the client should refuse the load the file. */
 307    unsigned short HeaderSz;
 308    unsigned short GroupSz;
 309    unsigned short PackageSz;
 310    unsigned short ReleaseFileSz;
 311    unsigned short PackageFileSz;
 312    unsigned short VersionSz;
 313    unsigned short DescriptionSz;
 314    unsigned short DependencySz;
 315    unsigned short DependencyDataSz;
 316    unsigned short ProvidesSz;
 317    unsigned short VerFileSz;
 318    unsigned short DescFileSz;
 319
 320    /** \brief Structure counts
 321
 322        These indicate the number of each structure contained in the cache.
 323        PackageCount is especially useful for generating user state structures.
 324        See Package::Id for more info. */
 325    map_id_t GroupCount;
 326    map_id_t PackageCount;
 327    map_id_t VersionCount;
 328    map_id_t DescriptionCount;
 329    map_id_t DependsCount;
 330    map_id_t DependsDataCount;
 331    map_fileid_t ReleaseFileCount;
 332    map_fileid_t PackageFileCount;
 333    map_fileid_t VerFileCount;
 334    map_fileid_t DescFileCount;
 335    map_id_t ProvidesCount;
 336
 337    /** \brief index of the first PackageFile structure
 338
 339        The PackageFile structures are singly linked lists that represent
 340        all package files that have been merged into the cache. */
 341    map_pointer_t FileList;
 342    /** \brief index of the first ReleaseFile structure */
 343    map_pointer_t RlsFileList;
 344
 345 #if APT_PKG_ABI < 413
 346    APT_DEPRECATED map_pointer_t StringList;
 347 #endif
 348    /** \brief String representing the version system used */
 349    map_pointer_t VerSysName;
 350    /** \brief native architecture the cache was built against */
 351    map_pointer_t Architecture;
 352 #if APT_PKG_ABI >= 413
 353    /** \brief all architectures the cache was built against */
 354    map_pointer_t Architectures;
 355 #endif
 356    /** \brief The maximum size of a raw entry from the original Package file */
 357    map_filesize_t MaxVerFileSize;
 358    /** \brief The maximum size of a raw entry from the original Translation file */
 359    map_filesize_t MaxDescFileSize;
 360
 361    /** \brief The Pool structures manage the allocation pools that the generator uses
 362
 363        Start indicates the first byte of the pool, Count is the number of objects
 364        remaining in the pool and ItemSize is the structure size (alignment factor)
 365        of the pool. An ItemSize of 0 indicates the pool is empty. There should be
 366        the same number of pools as there are structure types. The generator
 367        stores this information so future additions can make use of any unused pool
 368        blocks. */
 369    DynamicMMap::Pool Pools[9];
 370
 371    /** \brief hash tables providing rapid group/package name lookup
 372
 373        Each group/package name is inserted into a hash table using pkgCache::Hash(const &string)
 374        By iterating over each entry in the hash table it is possible to iterate over
 375        the entire list of packages. Hash Collisions are handled with a singly linked
 376        list of packages based at the hash item. The linked list contains only
 377        packages that match the hashing function.
 378        In the PkgHashTable is it possible that multiple packages have the same name -
 379        these packages are stored as a sequence in the list.
 380        The size of both tables is the same. */
 381 #if APT_PKG_ABI >= 413
 382    unsigned int HashTableSize;
 383    unsigned int GetHashTableSize() const { return HashTableSize; }
 384    void SetHashTableSize(unsigned int const sz) { HashTableSize = sz; }
 385    map_pointer_t GetArchitectures() const { return Architectures; }
 386    void SetArchitectures(map_pointer_t const idx) { Architectures = idx; }
 387 #else
 388    // BEWARE: these tables are pretty much empty and just here for abi compat
 389    map_ptrloc PkgHashTable[2*1048];
 390    map_ptrloc GrpHashTable[2*1048];
 391    unsigned int GetHashTableSize() const { return PkgHashTable[0]; }
 392    void SetHashTableSize(unsigned int const sz) { PkgHashTable[0] = sz; }
 393    map_pointer_t GetArchitectures() const { return PkgHashTable[1]; }
 394    void SetArchitectures(map_pointer_t const idx) { PkgHashTable[1] = idx; }
 395 #endif
 396    map_pointer_t * PkgHashTableP() const { return (map_pointer_t*) (this + 1); }
 397    map_pointer_t * GrpHashTableP() const { return PkgHashTableP() + GetHashTableSize(); }
 398
 399    /** \brief Size of the complete cache file */
 400    should_be_uint64_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    should_be_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 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 indicates nothing (consistently)
 464        This field used to contain ONE section the package belongs to,
 465        if those differs between versions it is a RANDOM one.
 466        The Section() method tries to reproduce it, but the only sane
 467        thing to do is use the Section field from the version! */
 468    APT_DEPRECATED map_ptrloc Section; // StringItem
 469    /** \brief index of the group this package belongs to */
 470    map_pointer_t Group;             // Group the Package belongs to
 471
 472    // Linked list
 473    /** \brief Link to the next package in the same bucket */
 474    map_pointer_t NextPackage;       // Package
 475    /** \brief List of all dependencies on this package */
 476    map_pointer_t RevDepends;        // Dependency
 477    /** \brief List of all "packages" this package provide */
 478    map_pointer_t ProvidesList;      // Provides
 479
 480    // Install/Remove/Purge etc
 481    /** \brief state that the user wishes the package to be in */
 482    unsigned char SelectedState;     // What
 483    /** \brief installation state of the package
 484
 485        This should be "ok" but in case the installation failed
 486        it will be different.
 487    */
 488    unsigned char InstState;         // Flags
 489    /** \brief indicates if the package is installed */
 490    unsigned char CurrentState;      // State
 491
 492    /** \brief unique sequel ID
 493
 494        ID is a unique value from 0 to Header->PackageCount assigned by the generator.
 495        This allows clients to create an array of size PackageCount and use it to store
 496        state information for the package map. For instance the status file emitter uses
 497        this to track which packages have been emitted already. */
 498    should_be_map_id_t ID;
 499    /** \brief some useful indicators of the package's state */
 500    unsigned long Flags;
 501 };
 502                                                                         /*}}}*/
 503 // Release File structure                                               /*{{{*/
 504 /** \brief stores information about the release files used to generate the cache
 505
 506     PackageFiles reference ReleaseFiles as we need to keep record of which
 507     version belongs to which release e.g. for pinning. */
 508 struct pkgCache::ReleaseFile
 509 {
 510    /** \brief physical disk file that this ReleaseFile represents */
 511    map_stringitem_t FileName;
 512    /** \brief the release information
 513
 514        Please see the files document for a description of what the
 515        release information means. */
 516    map_stringitem_t Archive;
 517    map_stringitem_t Codename;
 518    map_stringitem_t Version;
 519    map_stringitem_t Origin;
 520    map_stringitem_t Label;
 521    /** \brief The site the index file was fetched from */
 522    map_stringitem_t Site;
 523
 524    /** \brief Size of the file
 525
 526        Used together with the modification time as a
 527        simple check to ensure that the Packages
 528        file has not been altered since Cache generation. */
 529    map_filesize_t Size;
 530    /** \brief Modification time for the file */
 531    time_t mtime;
 532
 533    /** @TODO document PackageFile::Flags */
 534    unsigned long Flags;
 535
 536    // Linked list
 537    /** \brief Link to the next ReleaseFile in the Cache */
 538    map_pointer_t NextFile;
 539    /** \brief unique sequel ID */
 540    should_be_map_fileid_t ID;
 541 };
 542                                                                         /*}}}*/
 543 // Package File structure                                               /*{{{*/
 544 /** \brief stores information about the files used to generate the cache
 545
 546     Package files are referenced by Version structures to be able to know
 547     after the generation still from which Packages file includes this Version
 548     as we need this information later on e.g. for pinning. */
 549 struct pkgCache::PackageFile
 550 {
 551    /** \brief physical disk file that this PackageFile represents */
 552    map_stringitem_t FileName;
 553    /** \brief the release information */
 554    map_pointer_t Release;
 555
 556    map_stringitem_t Component;
 557    map_stringitem_t Architecture;
 558
 559    /** \brief indicates what sort of index file this is
 560
 561        @TODO enumerate at least the possible indexes */
 562    map_stringitem_t IndexType;
 563    /** \brief Size of the file
 564
 565        Used together with the modification time as a
 566        simple check to ensure that the Packages
 567        file has not been altered since Cache generation. */
 568    map_filesize_t Size;
 569    /** \brief Modification time for the file */
 570    time_t mtime;
 571
 572    /** @TODO document PackageFile::Flags */
 573    unsigned long Flags;
 574
 575    // Linked list
 576    /** \brief Link to the next PackageFile in the Cache */
 577    map_pointer_t NextFile;        // PackageFile
 578    /** \brief unique sequel ID */
 579    should_be_map_fileid_t ID;
 580 };
 581                                                                         /*}}}*/
 582 // VerFile structure                                                    /*{{{*/
 583 /** \brief associates a version with a PackageFile
 584
 585     This allows a full description of all Versions in all files
 586     (and hence all sources) under consideration. */
 587 struct pkgCache::VerFile
 588 {
 589    /** \brief index of the package file that this version was found in */
 590    map_pointer_t File;           // PackageFile
 591    /** \brief next step in the linked list */
 592    map_pointer_t NextFile;       // PkgVerFile
 593    /** \brief position in the package file */
 594    should_be_map_filesize_t Offset;         // File offset
 595    /** @TODO document pkgCache::VerFile::Size */
 596    map_filesize_t Size;
 597 };
 598                                                                         /*}}}*/
 599 // DescFile structure                                                   /*{{{*/
 600 /** \brief associates a description with a Translation file */
 601 struct pkgCache::DescFile
 602 {
 603    /** \brief index of the file that this description was found in */
 604    map_pointer_t File;           // PackageFile
 605    /** \brief next step in the linked list */
 606    map_pointer_t NextFile;       // PkgVerFile
 607    /** \brief position in the file */
 608    should_be_map_filesize_t Offset;         // File offset
 609    /** @TODO document pkgCache::DescFile::Size */
 610    map_filesize_t Size;
 611 };
 612                                                                         /*}}}*/
 613 // Version structure                                                    /*{{{*/
 614 /** \brief information for a single version of a package
 615
 616     The version list is always sorted from highest version to lowest
 617     version by the generator. Equal version numbers are either merged
 618     or handled as separate versions based on the Hash value. */
 619 struct pkgCache::Version
 620 {
 621    /** \brief complete version string */
 622    map_stringitem_t VerStr;
 623    /** \brief section this version is filled in */
 624    map_stringitem_t Section;
 625 #if APT_PKG_ABI >= 413
 626    /** \brief source package name this version comes from
 627       Always contains the name, even if it is the same as the binary name */
 628    map_stringitem_t SourcePkgName;
 629    /** \brief source version this version comes from
 630       Always contains the version string, even if it is the same as the binary version */
 631    map_stringitem_t SourceVerStr;
 632 #endif
 633
 634    /** \brief Multi-Arch capabilities of a package version */
 635    enum VerMultiArch { None = 0, /*!< is the default and doesn't trigger special behaviour */
 636                        All = (1<<0), /*!< will cause that Ver.Arch() will report "all" */
 637                        Foreign = (1<<1), /*!< can satisfy dependencies in another architecture */
 638                        Same = (1<<2), /*!< can be co-installed with itself from other architectures */
 639                        Allowed = (1<<3), /*!< other packages are allowed to depend on thispkg:any */
 640                        AllForeign = All | Foreign,
 641                        AllAllowed = All | Allowed };
 642    /** \brief stores the MultiArch capabilities of this version
 643
 644        Flags used are defined in pkgCache::Version::VerMultiArch
 645    */
 646    unsigned char MultiArch;
 647
 648    /** \brief references all the PackageFile's that this version came from
 649
 650        FileList can be used to determine what distribution(s) the Version
 651        applies to. If FileList is 0 then this is a blank version.
 652        The structure should also have a 0 in all other fields excluding
 653        pkgCache::Version::VerStr and Possibly pkgCache::Version::NextVer. */
 654    map_pointer_t FileList;          // VerFile
 655    /** \brief next (lower or equal) version in the linked list */
 656    map_pointer_t NextVer;           // Version
 657    /** \brief next description in the linked list */
 658    map_pointer_t DescriptionList;   // Description
 659    /** \brief base of the dependency list */
 660    map_pointer_t DependsList;       // Dependency
 661    /** \brief links to the owning package
 662
 663        This allows reverse dependencies to determine the package */
 664    map_pointer_t ParentPkg;         // Package
 665    /** \brief list of pkgCache::Provides */
 666    map_pointer_t ProvidesList;      // Provides
 667
 668    /** \brief archive size for this version
 669
 670        For Debian this is the size of the .deb file. */
 671    should_be_uint64_t Size; // These are the .deb size
 672    /** \brief uncompressed size for this version */
 673    should_be_uint64_t InstalledSize;
 674    /** \brief characteristic value representing this version
 675
 676        No two packages in existence should have the same VerStr
 677        and Hash with different contents. */
 678    unsigned short Hash;
 679    /** \brief unique sequel ID */
 680    should_be_map_id_t ID;
 681    /** \brief parsed priority value */
 682    unsigned char Priority;
 683 };
 684                                                                         /*}}}*/
 685 // Description structure                                                /*{{{*/
 686 /** \brief datamember of a linked list of available description for a version */
 687 struct pkgCache::Description
 688 {
 689    /** \brief Language code of this description (translation)
 690
 691        If the value has a 0 length then this is read using the Package
 692        file else the Translation-CODE file is used. */
 693    map_stringitem_t language_code;
 694    /** \brief MD5sum of the original description
 695
 696        Used to map Translations of a description to a version
 697        and to check that the Translation is up-to-date. */
 698    map_stringitem_t md5sum;
 699
 700    /** @TODO document pkgCache::Description::FileList */
 701    map_pointer_t FileList;          // DescFile
 702    /** \brief next translation for this description */
 703    map_pointer_t NextDesc;          // Description
 704    /** \brief the text is a description of this package */
 705    map_pointer_t ParentPkg;         // Package
 706
 707    /** \brief unique sequel ID */
 708    should_be_map_id_t ID;
 709 };
 710                                                                         /*}}}*/
 711 // Dependency structure                                                 /*{{{*/
 712 /** \brief information for a single dependency record
 713
 714     The records are split up like this to ease processing by the client.
 715     The base of the linked list is pkgCache::Version::DependsList.
 716     All forms of dependencies are recorded here including Depends,
 717     Recommends, Suggests, Enhances, Conflicts, Replaces and Breaks. */
 718 struct pkgCache::DependencyData
 719 {
 720    /** \brief string of the version the dependency is applied against */
 721    map_stringitem_t Version;
 722    /** \brief index of the package this depends applies to
 723
 724        The generator will - if the package does not already exist -
 725        create a blank (no version records) package. */
 726    map_pointer_t Package;         // Package
 727
 728    /** \brief Dependency type - Depends, Recommends, Conflicts, etc */
 729    unsigned char Type;
 730    /** \brief comparison operator specified on the depends line
 731
 732        If the high bit is set then it is a logical OR with the previous record. */
 733    unsigned char CompareOp;
 734 };
 735 struct pkgCache::Dependency
 736 {
 737    map_pointer_t DependencyData;  // DependencyData
 738    /** \brief version of the package which has the depends */
 739    map_pointer_t ParentVer;       // Version
 740    /** \brief next reverse dependency of this package */
 741    map_pointer_t NextRevDepends;  // Dependency
 742    /** \brief next dependency of this version */
 743    map_pointer_t NextDepends;     // Dependency
 744
 745    /** \brief unique sequel ID */
 746    should_be_map_id_t ID;
 747 };
 748                                                                         /*}}}*/
 749 // Provides structure                                                   /*{{{*/
 750 /** \brief handles virtual packages
 751
 752     When a Provides: line is encountered a new provides record is added
 753     associating the package with a virtual package name.
 754     The provides structures are linked off the package structures.
 755     This simplifies the analysis of dependencies and other aspects A provides
 756     refers to a specific version of a specific package, not all versions need to
 757     provide that provides.*/
 758 struct pkgCache::Provides
 759 {
 760    /** \brief index of the package providing this */
 761    map_pointer_t ParentPkg;        // Package
 762    /** \brief index of the version this provide line applies to */
 763    map_pointer_t Version;          // Version
 764    /** \brief version in the provides line (if any)
 765
 766        This version allows dependencies to depend on specific versions of a
 767        Provides, as well as allowing Provides to override existing packages.
 768        This is experimental. Note that Debian doesn't allow versioned provides */
 769    map_stringitem_t ProvideVersion;
 770    /** \brief next provides (based of package) */
 771    map_pointer_t NextProvides;     // Provides
 772    /** \brief next provides (based of version) */
 773    map_pointer_t NextPkgProv;      // Provides
 774 };
 775                                                                         /*}}}*/
 776 // UNUSED StringItem structure                                          /*{{{*/
 777 struct APT_DEPRECATED  pkgCache::StringItem
 778 {
 779    /** \brief string this refers to */
 780    map_ptrloc String;        // StringItem
 781    /** \brief Next link in the chain */
 782    map_ptrloc NextItem;      // StringItem
 783 };
 784                                                                         /*}}}*/
 785
 786 inline char const * pkgCache::NativeArch()
 787         { return StrP + HeaderP->Architecture; }
 788
 789 #include <apt-pkg/cacheiterators.h>
 790
 791 inline pkgCache::GrpIterator pkgCache::GrpBegin()
 792        {return GrpIterator(*this);}
 793 inline pkgCache::GrpIterator pkgCache::GrpEnd()
 794        {return GrpIterator(*this,GrpP);}
 795 inline pkgCache::PkgIterator pkgCache::PkgBegin()
 796        {return PkgIterator(*this);}
 797 inline pkgCache::PkgIterator pkgCache::PkgEnd()
 798        {return PkgIterator(*this,PkgP);}
 799 inline pkgCache::PkgFileIterator pkgCache::FileBegin()
 800        {return PkgFileIterator(*this,PkgFileP + HeaderP->FileList);}
 801 inline pkgCache::PkgFileIterator pkgCache::FileEnd()
 802        {return PkgFileIterator(*this,PkgFileP);}
 803 inline pkgCache::RlsFileIterator pkgCache::RlsFileBegin()
 804        {return RlsFileIterator(*this,RlsFileP + HeaderP->RlsFileList);}
 805 inline pkgCache::RlsFileIterator pkgCache::RlsFileEnd()
 806        {return RlsFileIterator(*this,RlsFileP);}
 807
 808
 809 // Oh I wish for Real Name Space Support
 810 class pkgCache::Namespace                                               /*{{{*/
 811 {
 812    public:
 813    typedef pkgCache::GrpIterator GrpIterator;
 814    typedef pkgCache::PkgIterator PkgIterator;
 815    typedef pkgCache::VerIterator VerIterator;
 816    typedef pkgCache::DescIterator DescIterator;
 817    typedef pkgCache::DepIterator DepIterator;
 818    typedef pkgCache::PrvIterator PrvIterator;
 819    typedef pkgCache::RlsFileIterator RlsFileIterator;
 820    typedef pkgCache::PkgFileIterator PkgFileIterator;
 821    typedef pkgCache::VerFileIterator VerFileIterator;
 822    typedef pkgCache::Version Version;
 823    typedef pkgCache::Description Description;
 824    typedef pkgCache::Package Package;
 825    typedef pkgCache::Header Header;
 826    typedef pkgCache::Dep Dep;
 827    typedef pkgCache::Flag Flag;
 828 };
 829                                                                         /*}}}*/
 830 #endif