AptPolicy

AptPolicy — Package pinning.

Synopsis

#include <apt.h>

#define             APT_POLICY_ERROR
enum                AptPolicyError;


                    AptPolicy;
AptPolicy *         apt_policy_new                      (AptCache *cache,
                                                         GCompareFunc compare_versions);
AptPolicy *         apt_policy_ref                      (AptPolicy *policy);
void                apt_policy_unref                    (AptPolicy *policy);
AptPackage *        apt_policy_get_candidate            (AptPolicy *policy,
                                                         const gchar *name,
                                                         const gchar *architecture);
gint                apt_policy_get_priority             (AptPolicy *policy,
                                                         AptPackage *package);
gint                apt_policy_get_index_priority       (AptPolicy *policy,
                                                         guint8 index);
void                apt_policy_set_default_release      (AptPolicy *policy,
                                                         const gchar *release);
gboolean            apt_policy_parse_file               (AptPolicy *policy,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            apt_policy_parse_dir                (AptPolicy *policy,
                                                         const gchar *dirname,
                                                         GError **error);

Description

This section documents the package pinning functionality in APT2. In APT, priorities are assigned to indexes (represented by AptIndex) and packages (represented by AptPackage). A priority can be any 16-bit integer except for 0 (which is used for unset priorities).

The pin priority of a package is determined by looking at the specific pin first. If the priority of this pin is not 0, the priority is found. If it is 0, the pin priority of the package equals the maximum pin priority of all indexes this package belongs to.

The pin priorities are used when packages should be installed. Given a set of packages which can satisfy a request, the one with the highest priority is the 'candidate' that shall be installed.

Details

APT_POLICY_ERROR

#define APT_POLICY_ERROR apt_policy_error_quark()

The error domain of the policy handling.

enum AptPolicyError

typedef enum {
    APT_POLICY_ERROR_MISSING_FIELD,
    APT_POLICY_ERROR_INVALID_PIN
} AptPolicyError;

Possible errors of the apt preferences file parser.

APT_POLICY_ERROR_MISSING_FIELD

 One of the fields 'Pin', 'Pin-Priority' is missing; 'Package' and 'Source' are both given; neither 'Package' nor 'Source' is given.

APT_POLICY_ERROR_INVALID_PIN

 The pin is invalid. This can have various reasons such as unknown pin types, invalid attributes or combinining a 'Pin: version' with 'Package *'.

AptPolicy

typedef struct _AptPolicy AptPolicy;

AptPolicy is an opaque data structure that may only be accessed using the following functions.

apt_policy_new ()

AptPolicy *         apt_policy_new                      (AptCache *cache,
                                                         GCompareFunc compare_versions);

Creates a new AptPolicy. The created AptPolicy holds a reference to cache.

cache :

 The AptCache the policy belongs to.

compare_versions :

 A function to compare version strings.

Returns :

 A newly allocated AptPolicy.

apt_policy_ref ()

AptPolicy *         apt_policy_ref                      (AptPolicy *policy);

Increments the reference count of policy.

policy :

 An AptPolicy

Returns :

 policy.

apt_policy_unref ()

void                apt_policy_unref                    (AptPolicy *policy);

Decrements the reference count of policy. If the reference count drops to 0, frees the memory allocated by policy.

policy :

 An AptPolicy

apt_policy_get_candidate ()

AptPackage *        apt_policy_get_candidate            (AptPolicy *policy,
                                                         const gchar *name,
                                                         const gchar *architecture);

Gets the AptPackage with the name name and the architecture architecture that has the highest priority. Only packages with a priority >= 0 will be considered a valid candidate. If there is no package with a priority >= 0, NULL is returned. If there are two packages with equal priority, the one with the higher version number is chosen.

If a matching package is installed, it will be preferred to packages with lower versions, unless those packages have a priority greater than 1000.

policy :

 An AptPolicy

name :

 The name of the package to retrieve.

architecture :

 The architecture of the package to retrieve.

Returns :

 The best AptPackage or NULL.

apt_policy_get_priority ()

gint                apt_policy_get_priority             (AptPolicy *policy,
                                                         AptPackage *package);

Gets the priority of the given package.

policy :

 An AptPolicy

package :

 The AptPackage for which the policy shall be retrieved.

apt_policy_get_index_priority ()

gint                apt_policy_get_index_priority       (AptPolicy *policy,
                                                         guint8 index);

Gets the priority assigned to the index.

policy :

 An AptPolicy

index :

 The id of the index.

Returns :

 The priority.

apt_policy_set_default_release ()

void                apt_policy_set_default_release      (AptPolicy *policy,
                                                         const gchar *release);

Sets the priority of all packages belonging to the release to 990. For this to be effective as documented in apt_preferences(5), you must call this function before any of the parser functions, as already existing priorities are not changed. If you use AptSession, this function will be called for the value defined in the configuration variable 'APT::Default-Release'.

policy :

 An AptPolicy

release :

 The codename or archive of the release

apt_policy_parse_file ()

gboolean            apt_policy_parse_file               (AptPolicy *policy,
                                                         const gchar *filename,
                                                         GError **error);

Parses the file located at filename and adds the new pins the file defines into policy.

policy :

 An AptPolicy

filename :

 The name of the file that shall be parsed.

error :

 Location to store an error.

Returns :

 TRUE if the file could be parsed, FALSE if not.

apt_policy_parse_dir ()

gboolean            apt_policy_parse_dir                (AptPolicy *policy,
                                                         const gchar *dirname,
                                                         GError **error);

Parses all the files in the directory at dirname by calling apt_policy_parse_file() for every file. The function stops immediately if it encounters an invalid file.

policy :

 An AptPolicy

dirname :

 The path to the directory.

error :

 Location to store an error.

Returns :

 TRUE if all files could be parsed, FALSE otherwise.
Generated by GTK-Doc V1.17