File: libsolv-pool.txt

package info (click to toggle)
libsolv 0.6.24-1+deb9u1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 4,320 kB
  • ctags: 4,178
  • sloc: ansic: 58,528; python: 852; perl: 740; tcl: 728; ruby: 704; sh: 263; cpp: 204; makefile: 65
file content (884 lines) | stat: -rw-r--r-- 32,720 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
Libsolv-Pool(3)
===============
:man manual: LIBSOLV
:man source: libsolv


Name
----
libsolv-pool - Libsolv's pool object


Public Attributes
-----------------

*void *appdata*::
A no-purpose pointer free to use for the library user. Freeing the pool
simply discards the pointer.

*Stringpool ss*::
The pool of unified strings.

*Reldep *rels*::
The pool of unified relation dependencies.

*int nrels*::
Number of allocated relation dependencies.

*Repo **repos*::
The array of repository pointers, indexed by repository Id.

*int nrepos*::
Number of allocated repository array elements, i.e. the size
of the repos array.

*int urepos*::
Number of used (i.e. non-zero) repository array elements.

*Repo *installed*::
Pointer to the repo holding the installed packages. You are free to read
this attribute, but you should use pool_set_installed() if you want to
change it.

*Solvable *solvables*::
The array of Solvable objects.

*int nsolvables*::
Number of Solvable objects, i.e. the size of the solvables array. Note
that the array may contain freed solvables, in that case the repo pointer
of the solvable will be zero.

*int disttype*::
The distribution type of your system, e.g. DISTTYPE_DEB. You are free to
read this attribute, but you should use pool_setdisttype() if you want to
change it.

*Id *whatprovidesdata*::
Multi-purpose Id storage holding zero terminated arrays of Ids.
pool_whatprovides() returns an offset into this data.

*Map *considered*::
Optional bitmap that can make the library ignore solvables. If a bitmap is
set, only solvables that have a set bit in the bitmap at their Id are
considered usable.

*int debugmask*::
A mask that defines which debug events should be reported.
pool_setdebuglevel() sets this mask.

*Datapos pos*::
An object storing some position in the repository data. Functions like
dataiterator_set_pos() set this object, accessing data with a pseudo
solvable Id of SOLVID_POS uses it.

*Queue pooljobs*::
A queue where fixed solver jobs can be stored. This jobs are automatically
added when solver_solve() is called, they are useful to store configuration
data like which packages should be multiversion installed.

Creation and Destruction
------------------------

	Pool *pool_create();

Create a new instance of a pool.

	void pool_free(Pool *pool);

Free a pool and all of the data it contains, e.g. the solvables, 
repositories, strings.


Debugging and error reporting
-----------------------------

=== Constants ===

*SOLV_FATAL*::
Report the error and call ``exit(1)'' afterwards. You cannot mask this
level. Reports to stderr instead of stdout.

*SOLV_ERROR*::
Used to report errors. Reports to stderr instead of stdout.

*SOLV_WARN*::
Used to report warnings.

*SOLV_DEBUG_STATS*::
Used to report statistical data.

*SOLV_DEBUG_RULE_CREATION*::
Used to report information about the solver's creation of rules.

*SOLV_DEBUG_PROPAGATE*::
Used to report information about the solver's unit rule propagation
process.

*SOLV_DEBUG_ANALYZE*::
Used to report information about the solver's learnt rule generation
mechanism.

*SOLV_DEBUG_UNSOLVABLE*::
Used to report information about the solver dealing with conflicting
rules.

*SOLV_DEBUG_SOLUTIONS*::
Used to report information about the solver creating solutions to solve
problems.

*SOLV_DEBUG_POLICY*::
Used to report information about the solver searching for an optimal
solution.

*SOLV_DEBUG_RESULT*::
Used by the debug functions to output results.

*SOLV_DEBUG_JOB*::
Used to report information about the job rule generation process.

*SOLV_DEBUG_SOLVER*::
Used to report information about what the solver is currently
doing.

*SOLV_DEBUG_TRANSACTION*::
Used to report information about the transaction generation and
ordering process.

*SOLV_DEBUG_TO_STDERR*::
Write debug messages to stderr instead of stdout.

=== Functions ===

	void pool_debug(Pool *pool, int type, const char *format, ...);

Report a message of the type _type_. You can filter debug messages by
setting a debug mask.

	void pool_setdebuglevel(Pool *pool, int level);

Set a predefined debug mask. A higher level generally means more bits in
the mask are set, thus more messages are printed.

	void pool_setdebugmask(Pool *pool, int mask);

Set the debug mask to filter debug messages.

	int pool_error(Pool *pool, int ret, const char *format, ...);

Set the pool's error string. The _ret_ value is simply used as a
return value of the function so that you can write code like
+return pool_error(...);+. If the debug mask contains the *SOLV_ERROR*
bit, pool_debug() is also called with the message and type *SOLV_ERROR*.

	extern char *pool_errstr(Pool *pool);

Return the current error string stored in the pool. Like with the libc's
errno value, the string is only meaningful after a function returned an
error.

	void pool_setdebugcallback(Pool *pool, void (*debugcallback)(Pool *, void *data, int type, const char *str), void *debugcallbackdata);

Set a custom debug callback function. Instead of writing to stdout or
stderr, the callback function will be called.


Pool configuration
------------------

=== Constants ===

*DISTTYPE_RPM*::
Used for systems which use rpm as low level package manager.

*DISTTYPE_DEB*::
Used for systems which use dpkg as low level package manager.

*DISTTYPE_ARCH*::
Used for systems which use the arch linux package manager.

*DISTTYPE_HAIKU*::
Used for systems which use haiku packages.

*POOL_FLAG_PROMOTEEPOCH*::
Promote the epoch of the providing dependency to the requesting
dependency if it does not contain an epoch. Used at some time
in old rpm versions, modern systems should never need this.

*POOL_FLAG_FORBIDSELFCONFLICTS*::
Disallow the installation of packages that conflict with themselves.
Debian always allows self-conflicting packages, rpm used to forbid
them but switched to also allowing them recently.

*POOL_FLAG_OBSOLETEUSESPROVIDES*::
Make obsolete type dependency match against provides instead of
just the name and version of packages. Very old versions of rpm
used the name/version, then it got switched to provides and later
switched back again to just name/version.

*POOL_FLAG_IMPLICITOBSOLETEUSESPROVIDES*::
An implicit obsoletes is the internal mechanism to remove the
old package on an update. The default is to remove all packages
with the same name, rpm-5 switched to also removing packages
providing the same name.

*POOL_FLAG_OBSOLETEUSESCOLORS*::
Rpm's multilib implementation (used in RedHat and Fedora)
distinguishes between 32bit and 64bit packages (the terminology
is that they have a different color). If obsoleteusescolors is
set, packages with different colors will not obsolete each other.

*POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS*::
Same as POOL_FLAG_OBSOLETEUSESCOLORS, but used to find out if
packages of the same name can be installed in parallel. For
current Fedora systems, POOL_FLAG_OBSOLETEUSESCOLORS should be
false and POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS should be true
(this is the default if FEDORA is defined when libsolv is
compiled).

*POOL_FLAG_NOINSTALLEDOBSOLETES*::
New versions of rpm consider the obsoletes of installed packages
when checking for dependency, thus you may not install a package
that is obsoleted by some other installed package, unless you
also erase the other package.

*POOL_FLAG_HAVEDISTEPOCH*::
Mandriva added a new field called distepoch that gets checked in
version comparison if the epoch/version/release of two packages
are the same.

*POOL_FLAG_NOOBSOLETESMULTIVERSION*::
If a package is installed in multiversionmode, rpm used to ignore
both the implicit obsoletes and the obsolete dependency of a
package. This was changed to ignoring just the implicit obsoletes,
thus you may install multiple versions of the same name, but
obsoleted packages still get removed.

*POOL_FLAG_ADDFILEPROVIDESFILTERED*::
Make the addfileprovides method only add files from the standard
locations (i.e. the ``bin'' and ``etc'' directories). This is
useful if you have only few packages that use non-standard file
dependencies, but you still want the fast speed that addfileprovides()
generates.


=== Functions ===
	int pool_setdisttype(Pool *pool, int disttype);

Set the package type of your system. The disttype is used for example
to define package comparison semantics. Libsolv's default disttype
should match the package manager of your system, so you only need to
use this function if you want to use the library to solve packaging
problems for different systems. The Function returns the old
disttype on success, and -1 if the new disttype is not supported.
Note that any pool_setarch and pool_setarchpolicy calls need to
come after the pool_setdisttype call, as they make use of the
noarch/any/all architecture id.

	int pool_set_flag(Pool *pool, int flag, int value);

Set a flag to a new value. Returns the old value of the flag.

	int pool_get_flag(Pool *pool, int flag);

Get the value of a pool flag. See the constants section about the meaning
of the flags.

	void pool_set_rootdir(Pool *pool, const char *rootdir);

Set a specific root directory. Some library functions support a flag that
tells the function to prepend the rootdir to file and directory names.

	const char *pool_get_rootdir(Pool *pool);

Return the current value of the root directory.

	char *pool_prepend_rootdir(Pool *pool, const char *dir);

Prepend the root directory to the _dir_ argument string. The returned
string has been newly allocated and needs to be freed after use.

	char *pool_prepend_rootdir_tmp(Pool *pool, const char *dir);

Same as pool_prepend_rootdir, but uses the pool's temporary space for
allocation.

	void pool_set_installed(Pool *pool, Repo *repo);

Set which repository should be treated as the ``installed'' repository,
i.e. the one that holds information about the installed packages.

	void pool_set_languages(Pool *pool, const char **languages, int nlanguages);

Set the language of your system. The library provides lookup functions that
return localized strings, for example for package descriptions. You can
set an array of languages to provide a fallback mechanism if one language
is not available.

	void pool_setarch(Pool *pool, const char *arch);

Set the architecture of your system. The architecture is used to determine
which packages are installable and which packages cannot be installed.
The _arch_ argument is normally the ``machine'' value of the ``uname''
system call.

	void pool_setarchpolicy(Pool *, const char *);

Set the architecture policy for your system. This is the general version
of pool_setarch (in fact pool_setarch calls pool_setarchpolicy internally).
See the section about architecture policies for more information.

	void pool_addvendorclass(Pool *pool, const char **vendorclass);

Add a new vendor equivalence class to the system. A vendor equivalence class
defines if an installed package of one vendor can be replaced by a package
coming from a different vendor. The _vendorclass_ argument must be a
NULL terminated array of strings. See the section about vendor policies for
more information.

	void pool_setvendorclasses(Pool *pool, const char **vendorclasses);

Set all allowed vendor equivalences. The vendorclasses argument must be an
NULL terminated array consisting of all allowed classes concatenated.
Each class itself must be NULL terminated, thus the last class ends with
two NULL elements, one to finish the class and one to finish the list
of classes.

	void pool_set_custom_vendorcheck(Pool *pool, int (*vendorcheck)(Pool *, Solvable *, Solvable *));

Define a custom vendor check mechanism. You can use this if libsolv's
internal vendor equivalence class mechanism does not match your needs.

	void pool_setloadcallback(Pool *pool, int (*cb)(Pool *, Repodata *, void *), void *loadcbdata);

Define a callback function that gets called when repository metadata needs
to be loaded on demand. See the section about on demand loading in the
libsolv-repodata manual.

	void pool_setnamespacecallback(Pool *pool, Id (*cb)(Pool *, void *, Id, Id), void *nscbdata);

Define a callback function to implement custom namespace support. See the
section about namespace dependencies.


Id pool management
------------------
=== Constants ===

*ID_EMPTY*::
The Id of the empty string, it is always Id 1.

*REL_LT*::
Represents a ``<'' relation.

*REL_EQ*::
Represents a ``='' relation.

*REL_GT*::
Represents a ``>'' relation. You can use combinations of REL_GT, REL_EQ,
and REL_LT or-ed together to create any relation you like.

*REL_AND*::
A boolean AND operation, the ``name'' and ``evr'' parts of the relation can
be two sub-dependencies. Packages must match both parts of the dependency.

*REL_OR*::
A boolean OR operation, the ``name'' and ``evr'' parts of the relation can
be two sub-dependencies. Packages can match any part of the dependency.

*REL_WITH*::
Like REL_AND, but packages must match both dependencies simultaneously. See
the section about boolean dependencies about more information.

*REL_NAMESPACE*::
A special namespace relation. See the section about namespace dependencies
for more information.

*REL_ARCH*::
An architecture filter dependency. The ``name'' part of the relation is a
sub-dependency, the ``evr'' part is the Id of an architecture that the
matching packages must have (note that this is an exact match ignoring
architecture policies).

*REL_FILECONFLICT*::
An internal file conflict dependency used to represent file conflicts. See
the pool_add_fileconflicts_deps() function.

*REL_COND*::
A conditional dependency, the ``name'' sub-dependency is only considered if
the ``evr'' sub-dependency is fulfilled. See the section about boolean
dependencies about more information.

*REL_COMPAT*::
A compat dependency used in Haiku to represent version ranges.  The
``name'' part is the actual version, the ``evr'' part is the backwards
compatibility version.

=== Functions ===
	Id pool_str2id(Pool *pool, const char *str, int create);

Add a string to the pool of unified strings, returning the Id of the string.
If _create_ is zero, new strings will not be added to the pool, instead
Id 0 is returned.

	Id pool_strn2id(Pool *pool, const char *str, unsigned int len, int create);

Same as pool_str2id, but only _len_ characters of the string are used. This
can be used to add substrings to the pool.

	Id pool_rel2id(Pool *pool, Id name, Id evr, int flags, int create);

Create a relational dependency from to other dependencies, _name_ and _evr_,
and a _flag_. See the *REL_* constants for the supported flags. As with
pool_str2id, _create_ defines if new dependencies will get added or Id zero
will be returned instead.

	Id pool_id2langid(Pool *pool, Id id, const char *lang, int create);

Attach a language suffix to a string Id. This function can be used to
create language keyname Ids from keynames, it is functional equivalent
to converting the _id_ argument to a string, adding a ``:'' character
and the _lang_ argument to the string and then converting the result back
into an Id.

	const char *pool_id2str(const Pool *pool, Id id);

Convert an Id back into a string. If the Id is a relational Id, the
``name'' part will be converted instead.

	const char *pool_id2rel(const Pool *pool, Id id);

Return the relation string of a relational Id. Returns an empty string if
the passed Id is not a relation.

	const char *pool_id2evr(const Pool *pool, Id id);

Return the ``evr'' part of a relational Id as string. Returns an empty
string if the passed Id is not a relation.

	const char *pool_dep2str(Pool *pool, Id id);

Convert an Id back into a string. If the passed Id belongs to a relation,
a string representing the relation is returned. Note that in that case
the string is allocated on the pool's temporary space.

	void pool_freeidhashes(Pool *pool);

Free the hashes used to unify strings and relations. You can use this
function to save memory if you know that you will no longer create new
strings and relations.


Solvable functions
------------------

	Solvable *pool_id2solvable(const Pool *pool, Id p);

Convert a solvable Id into a pointer to the solvable data. Note that the
pointer may become invalid if new solvables are created or old solvables
deleted, because the array storing all solvables may get reallocated.

	const char *pool_solvid2str(Pool *pool, Id p);

Return a string representing the solvable with the Id _p_. The string will
be some canonical representation of the solvable, usually a combination of
the name, the version, and the architecture.

	const char *pool_solvable2str(Pool *pool, Solvable *s);

Same as pool_solvid2str, but instead of the Id, a pointer to the solvable
is passed.


Dependency matching
-------------------

=== Constants ===
*EVRCMP_COMPARE*::
Compare all parts of the version, treat missing parts as empty strings.

*EVRCMP_MATCH_RELEASE*::
A special mode for rpm version string matching. If a version misses a
release part, it matches all releases. In that case the special values
``-2'' and ``2'' are returned, depending on which of the two versions
did not have a release part.

*EVRCMP_MATCH*::
A generic match, missing parts always match.

*EVRCMP_COMPARE_EVONLY*::
Only compare the epoch and the version parts, ignore the release part.

=== Functions ===
	int pool_evrcmp(const Pool *pool, Id evr1id, Id evr2id, int mode);

Compare two version Ids, return -1 if the first version is less than the
second version, 0 if they are identical, and 1 if the first version is
bigger than the second one.

	int pool_evrcmp_str(const Pool *pool, const char *evr1, const char *evr2, int mode);

Same as pool_evrcmp(), but uses strings instead of Ids.

	int pool_evrmatch(const Pool *pool, Id evrid, const char *epoch, const char *version, const char *release);

Match a version Id against an epoch, a version and a release string. Passing
NULL means that the part should match everything.

	int pool_match_dep(Pool *pool, Id d1, Id d2);

Returns ``1'' if the dependency _d1_ (the provider) is matched by the
dependency _d2_, otherwise ``0'' is returned. For two dependencies to
match, both the ``name'' parts must match and the version range described
by the ``evr'' parts must overlap.

	int pool_match_nevr(Pool *pool, Solvable *s, Id d);

Like pool_match_dep, but the provider is the "self-provides" dependency
of the Solvable _s_, i.e. the dependency ``s->name = s->evr''.


Whatprovides Index
------------------
	void pool_createwhatprovides(Pool *pool);

Create an index that maps dependency Ids to sets of packages that provide the
dependency.

	void pool_freewhatprovides(Pool *pool);

Free the whatprovides index to save memory.

	Id pool_whatprovides(Pool *pool, Id d);

Return an offset into the Pool's whatprovidesdata array. The solvables with
the Ids stored starting at that offset provide the dependency _d_. The
solvable list is zero terminated.

	Id *pool_whatprovides_ptr(Pool *pool, Id d);

Instead of returning the offset, return the pointer to the Ids stored at
that offset. Note that this pointer has a very limit validity time, as any
call that adds new values to the whatprovidesdata area may reallocate the
array.

	Id pool_queuetowhatprovides(Pool *pool, Queue *q);

Add the contents of the Queue _q_ to the end of the whatprovidesdata array,
returning the offset into the array.

	void pool_addfileprovides(Pool *pool);

Some package managers like rpm allow dependencies on files contained in
other packages. To allow libsolv to deal with those dependencies in an
efficient way, you need to call the addfileprovides method after creating
and reading all repositories. This method will scan all dependency for file
names and then scan all packages for matching files. If a filename has been
matched, it will be added to the provides list of the corresponding
package.

	void pool_addfileprovides_queue(Pool *pool, Queue *idq, Queue *idqinst);

Same as pool_addfileprovides, but the added Ids are returned in two Queues,
_idq_ for all repositories except the one containing the ``installed''
packages, _idqinst_ for the latter one. This information can be stored in
the meta section of the repositories to speed up the next time the
repository is loaded and addfileprovides is called

	void pool_flush_namespaceproviders(Pool *pool, Id ns, Id evr);

Clear the cache of the providers for namespace dependencies matching
namespace _ns_. If the _evr_ argument is non-zero, the namespace dependency
for exactly that dependency is cleared, otherwise all matching namespace
dependencies are cleared. See the section about Namespace dependencies
for further information.

	void pool_add_fileconflicts_deps(Pool *pool, Queue *conflicts);

Some package managers like rpm report conflicts when a package installation
overwrites a file of another installed package with different content. As
file content information is not stored in the repository metadata, those
conflicts can only be detected after the packages are downloaded. Libsolv
provides a function to check for such conflicts, pool_findfileconflicts().
If conflicts are found, they can be added as special *REL_FILECONFLICT*
provides dependencies, so that the solver will know about the conflict when
it is re-run.


Utility functions
-----------------
	char *pool_alloctmpspace(Pool *pool, int len);

Allocate space on the pool's temporary space area. This space has a limited
lifetime, it will be automatically freed after a fixed amount (currently
16) of other pool_alloctmpspace() calls are done.

	void pool_freetmpspace(Pool *pool, const char *space);

Give the space allocated with pool_alloctmpspace back to the system. You
do not have to use this function, as the space is automatically reclaimed,
but it can be useful to extend the lifetime of other pointers to the pool's
temporary space area.

	const char *pool_bin2hex(Pool *pool, const unsigned char *buf, int len);

Convert some binary data to hexadecimal, returning a string allocated in
the pool's temporary space area.

	char *pool_tmpjoin(Pool *pool, const char *str1, const char *str2, const char *str3);

Join three strings and return the result in the pool's temporary space
area. You can use NULL arguments if you just want to join less strings.

	char *pool_tmpappend(Pool *pool, const char *str1, const char *str2, const char *str3);

Like pool_tmpjoin(), but if the first argument is the last allocated space
in the pool's temporary space area, it will be replaced with the result of
the join and no new temporary space slot will be used.  Thus you can join
more than three strings by a combination of one pool_tmpjoin() and multiple
pool_tmpappend() calls. Note that the _str1_ pointer is no longer usable
after the call.


Data lookup
-----------
=== Constants ===

*SOLVID_POS*::
Use the data position stored in the pool for the lookup instead of looking
up the data of a solvable.

*SOLVID_META*::
Use the data stored in the meta section of a repository (or repodata
area) instead of looking up the data of a solvable. This constant does
not work for the pool's lookup functions, use it for the repo's or
repodata's lookup functions instead. It's just listed for completeness.

=== Functions ===
	const char *pool_lookup_str(Pool *pool, Id solvid, Id keyname);

Return the  string value stored under the attribute _keyname_ in solvable
_solvid_.

	unsigned long long pool_lookup_num(Pool *pool, Id solvid, Id keyname, unsigned long long notfound);

Return the 64bit unsigned number stored under the attribute _keyname_ in
solvable _solvid_. If no such number is found, the value of the _notfound_
argument is returned instead.

	Id pool_lookup_id(Pool *pool, Id solvid, Id keyname);

Return the Id stored under the attribute _keyname_ in solvable _solvid_.

	int pool_lookup_idarray(Pool *pool, Id solvid, Id keyname, Queue *q);

Fill the queue _q_ with the content of the Id array stored under the
attribute _keyname_ in solvable _solvid_. Returns ``1'' if an array was
found, otherwise the queue will be empty and ``0'' will be returned.

	int pool_lookup_void(Pool *pool, Id solvid, Id keyname);

Returns ``1'' if a void value is stored under the attribute _keyname_ in
solvable _solvid_, otherwise ``0''.

	const char *pool_lookup_checksum(Pool *pool, Id solvid, Id keyname, Id *typep);

Return the checksum that is stored under the attribute _keyname_ in
solvable _solvid_.  The type of the checksum will be returned over the
_typep_ pointer. If no such checksum is found, NULL will be returned and
the type will be set to zero. Note that the result is stored in the Pool's
temporary space area.

	const unsigned char *pool_lookup_bin_checksum(Pool *pool, Id solvid, Id keyname, Id *typep);

Return the checksum that is stored under the attribute _keyname_ in
solvable _solvid_.  Returns the checksum as binary data, you can use the
returned type to calculate the length of the checksum. No temporary space
area is needed.

	const char *pool_lookup_deltalocation(Pool *pool, Id solvid, unsigned int *medianrp);

This is a utility lookup function to return the delta location for a delta
rpm.  As solvables cannot store deltas, you have to use SOLVID_POS as
argument and set the Pool's datapos pointer to point to valid delta rpm
data.

	void pool_search(Pool *pool, Id solvid, Id keyname, const char *match, int flags, int (*callback)(void *cbdata, Solvable *s, Repodata *data, Repokey *key, KeyValue *kv), void *cbdata);

Perform a search on all data stored in the pool. You can limit the search
area by using the _solvid_ and _keyname_ arguments. The values can be
optionally matched against the _match_ argument, use NULL if you do not
want this matching. See the Dataiterator manpage about the possible matches
modes and the _flags_ argument. For all (matching) values, the callback
function is called with the _cbdata_ callback argument and the data
describing the value.


Job and Selection functions
---------------------------
A Job consists of two Ids, _how_ and _what_. The _how_ part describes the
action, the job flags, and the selection method while the _what_ part is
in input for the selection. A Selection is a queue consisting of multiple
jobs (thus the number of elements in the queue must be a multiple of two).
See the Solver manpage for more information about jobs.

	const char *pool_job2str(Pool *pool, Id how, Id what, Id flagmask);

Convert a job into a string. Useful for debugging purposes. The _flagmask_
can be used to mask the flags of the job, use ``0'' if you do not want to
see such flags, ``-1'' to see all flags, or a combination of the flags
you want to see.

	void pool_job2solvables(Pool *pool, Queue *pkgs, Id how, Id what);

Return a list of solvables that the specified job selects.

	int pool_isemptyupdatejob(Pool *pool, Id how, Id what);

Return ``1'' if the job is an update job that does not work with any
installed package, i.e. the job is basically a no-op. You can use this
to turn no-op update jobs into install jobs (as done by package managers
like ``zypper'').

	const char *pool_selection2str(Pool *pool, Queue *selection, Id flagmask);

Convert a selection into a string. Useful for debugging purposes. See the
pool_job2str() function for the _flagmask_ argument.


Odds and Ends
-------------
	void pool_freeallrepos(Pool *pool, int reuseids);

Free all repos from the pool (including all solvables). If _reuseids_ is
true, all Ids of the solvables are free to be reused the next time
solvables are created.

	void pool_clear_pos(Pool *pool);
	
Clear the data position stored in the pool.


Architecture Policies
---------------------
An architecture policy defines a list of architectures that can be
installed on the system, and also the relationship between them (i.e. the
ordering). Architectures can be delimited with three different characters:

*\':'*::
No relationship between the architectures. A package of one architecture
can not be replaced with one of the other architecture.

*\'>'*::
The first architecture is better than the second one. An installed package
of the second architecture may be replaced with one from the first
architecture and vice versa. The solver will select the better architecture
if the versions are the same.

*\'='*::
The two architectures are freely exchangeable. Used to define aliases
for architectures.

An example would be \'+x86_64:i686=athlon>i586+'. This means that x86_64
packages can only be replaced by other x86_64 packages, i686 packages
can be replaced by i686 and i586 packages (but i686 packages will be
preferred) and athlon is another name for the i686 architecture.

You can turn off the architecture replacement checks with the Solver's
SOLVER_FLAG_ALLOW_ARCHCHANGE flag.

Vendor Policies
---------------
Different vendors often compile packages with different features, so
Libsolv only replace installed packages of one vendor with packages coming
from the same vendor. Also, while the version of a package is normally
defined by the upstream project, the release part of the version is
set by the vendor's package maintainer, so it's not meaningful to
do version comparisons for packages coming from different vendors.

Vendor in this case means the SOLVABLE_VENDOR string stored in each
solvable. Sometimes a vendor changes names, or multiple vendors form a
group that coordinate their package building, so libsolv offers a way
to define that a group of vendors are compatible. You do that be
defining vendor equivalence classes, packages from a vendor from
one class may be replaced with packages from all the other vendors
in the class.

There can be multiple equivalence classes, the set of allowed vendor
changes for an installed package is calculated by building the union
of all of the equivalence classes the vendor of the installed package
is part of.

You can turn off the architecture replacement checks with the Solver's
SOLVER_FLAG_ALLOW_VENDORCHANGE flag.


Boolean Dependencies
--------------------
Boolean Dependencies allow one to build complex expressions from simple
dependencies. While rpm does not support boolean expressions in
dependencies and debian only allows an "OR" expression, libsolv
allows arbitrary complex expressions. The following basic types
are supported:

*REL_OR*::
The expression is true if either the first dependency or the second
one is true. This is useful for package dependencies like ``Requires'',
where you can specify that either one of the packages need to be
installed.

*REL_AND*::
The expression is true if both dependencies are true. The packages
fulfilling the dependencies may be different, i.e. 
``Supplements: perl AND python'' is true if both a package providing
perl and a package providing python are installed. The solver currently
only supports REL_AND in Supplements/Enhances dependencies, in other
types of dependencies it gets treated as REL_WITH.

*REL_WITH*::
The expression is true if both dependencies are true and are fulfilled by
the same package. Thus ``Supplements: perl AND python'' would only be true
if a package is installed that provides both dependencies (some kind
of multi-language interpreter).

*REL_COND*::
The expression is true if the first dependency is true or the second
dependency is false. Libsolv currently does not support this type of
dependency in the solver code.

Each sub-dependency of a boolean dependency can in turn be a boolean
dependency, so you can chain them to create complex dependencies.


Namespace Dependencies
----------------------
Namespace dependencies can be used to implement dependencies on
attributes external to libsolv. An example would be a dependency
on the language set by the user. This types of dependencies are
usually only used for ``Conflicts'' or ``Supplements'' dependencies,
as the underlying package manager does not know how to deal with
them.

If the library needs to evaluate a namespace dependency, it calls
the namespace callback function set in the pool. The callback
function can return a set of packages that ``provide'' the
dependency. If the dependency is provided by the system, the
returned set should consist of just the system solvable (Solvable
Id 1).

The returned set of packages must be returned as offset into
the whatprovidesdata array. You can use the pool_queuetowhatprovides
function to convert a queue into such an offset. To ease programming
the callback function, the return values ``0'' and ``1'' are not
interpreted as an offset. ``0'' means that no package is in the
return set, ``1'' means that just the system solvable is in the set.

The returned set is cached, so that for each namespace dependency
the callback is just called once. If you need to flush the cache (maybe
because the user has selected a different language), use the
pool_flush_namespaceproviders() function.


Author
------
Michael Schroeder <mls@suse.de>