libpkgconf client module

The libpkgconf client module implements the pkgconf_client_t “client” object. Client objects store all necessary state for libpkgconf allowing for multiple instances to run in parallel.

Client objects are not thread safe, in other words, a client object should not be shared across thread boundaries.

void pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler)

Initialise a pkgconf client object.

Parameters:
  • client (pkgconf_client_t*) – The client to initialise.
  • error_handler (pkgconf_error_handler_func_t) – An optional error handler to use for logging errors.
  • error_handler_data (void*) – user data passed to optional error handler
Returns:

nothing

pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler)

Allocate and initialise a pkgconf client object.

Parameters:
  • error_handler (pkgconf_error_handler_func_t) – An optional error handler to use for logging errors.
  • error_handler_data (void*) – user data passed to optional error handler
Returns:

A pkgconf client object.

Return type:

pkgconf_client_t*

void pkgconf_client_deinit(pkgconf_client_t *client)

Release resources belonging to a pkgconf client object.

Parameters:
  • client (pkgconf_client_t*) – The client to deinitialise.
Returns:

nothing

void pkgconf_client_free(pkgconf_client_t *client)

Release resources belonging to a pkgconf client object and then free the client object itself.

Parameters:
  • client (pkgconf_client_t*) – The client to deinitialise and free.
Returns:

nothing

const char *pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client)

Retrieves the client’s sysroot directory (if any).

Parameters:
  • client (pkgconf_client_t*) – The client object being accessed.
Returns:

A string containing the sysroot directory or NULL.

Return type:

const char *

void pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir)

Sets or clears the sysroot directory on a client object. Any previous sysroot directory setting is automatically released if one was previously set.

Additionally, the global tuple $(pc_sysrootdir) is set as appropriate based on the new setting.

Parameters:
  • client (pkgconf_client_t*) – The client object being modified.
  • sysroot_dir (char*) – The sysroot directory to set or NULL to unset.
Returns:

nothing

const char *pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client)

Retrieves the client’s buildroot directory (if any).

Parameters:
  • client (pkgconf_client_t*) – The client object being accessed.
Returns:

A string containing the buildroot directory or NULL.

Return type:

const char *

void pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir)

Sets or clears the buildroot directory on a client object. Any previous buildroot directory setting is automatically released if one was previously set.

Additionally, the global tuple $(pc_top_builddir) is set as appropriate based on the new setting.

Parameters:
  • client (pkgconf_client_t*) – The client object being modified.
  • buildroot_dir (char*) – The buildroot directory to set or NULL to unset.
Returns:

nothing

bool pkgconf_error(const pkgconf_client_t *client, const char *format, ...)

Report an error to a client-registered error handler.

Parameters:
  • client (pkgconf_client_t*) – The pkgconf client object to report the error to.
  • format (char*) – A printf-style format string to use for formatting the error message.
Returns:

true if the error handler processed the message, else false.

Return type:

bool

bool pkgconf_warn(const pkgconf_client_t *client, const char *format, ...)

Report an error to a client-registered warn handler.

Parameters:
  • client (pkgconf_client_t*) – The pkgconf client object to report the error to.
  • format (char*) – A printf-style format string to use for formatting the warning message.
Returns:

true if the warn handler processed the message, else false.

Return type:

bool

bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)

Report a message to a client-registered trace handler.

Parameters:
  • client (pkgconf_client_t*) – The pkgconf client object to report the trace message to.
  • format (char*) – A printf-style format string to use for formatting the trace message.
Returns:

true if the trace handler processed the message, else false.

Return type:

bool

bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data)

The default pkgconf error handler.

Parameters:
  • msg (char*) – The error message to handle.
  • client (pkgconf_client_t*) – The client object the error originated from.
  • data (void*) – An opaque pointer to extra data associated with the client for error handling.
Returns:

true (the function does nothing to process the message)

Return type:

bool

unsigned int pkgconf_client_get_flags(const pkgconf_client_t *client)

Retrieves resolver-specific flags associated with a client object.

Parameters:
  • client (pkgconf_client_t*) – The client object to retrieve the resolver-specific flags from.
Returns:

a bitfield of resolver-specific flags

Return type:

uint

void pkgconf_client_set_flags(pkgconf_client_t *client, unsigned int flags)

Sets resolver-specific flags associated with a client object.

Parameters:
  • client (pkgconf_client_t*) – The client object to set the resolver-specific flags on.
Returns:

nothing

const char *pkgconf_client_get_prefix_varname(const pkgconf_client_t *client)

Retrieves the name of the variable that should contain a module’s prefix. In some cases, it is necessary to override this variable to allow proper path relocation.

Parameters:
  • client (pkgconf_client_t*) – The client object to retrieve the prefix variable name from.
Returns:

the prefix variable name as a string

Return type:

const char *

void pkgconf_client_set_prefix_varname(pkgconf_client_t *client, const char *prefix_varname)

Sets the name of the variable that should contain a module’s prefix. If the variable name is NULL, then the default variable name (prefix) is used.

Parameters:
  • client (pkgconf_client_t*) – The client object to set the prefix variable name on.
  • prefix_varname (char*) – The prefix variable name to set.
Returns:

nothing

pkgconf_client_get_warn_handler(const pkgconf_client_t *client)

Returns the warning handler if one is set, else NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to get the warn handler from.
Returns:

a function pointer to the warn handler or NULL

pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data)

Sets a warn handler on a client object or uninstalls one if set to NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to set the warn handler on.
  • warn_handler (pkgconf_error_handler_func_t) – The warn handler to set.
  • warn_handler_data (void*) – Optional data to associate with the warn handler.
Returns:

nothing

pkgconf_client_get_error_handler(const pkgconf_client_t *client)

Returns the error handler if one is set, else NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to get the error handler from.
Returns:

a function pointer to the error handler or NULL

pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data)

Sets a warn handler on a client object or uninstalls one if set to NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to set the error handler on.
  • error_handler (pkgconf_error_handler_func_t) – The error handler to set.
  • error_handler_data (void*) – Optional data to associate with the error handler.
Returns:

nothing

pkgconf_client_get_trace_handler(const pkgconf_client_t *client)

Returns the error handler if one is set, else NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to get the error handler from.
Returns:

a function pointer to the error handler or NULL

pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data)

Sets a warn handler on a client object or uninstalls one if set to NULL.

Parameters:
  • client (pkgconf_client_t*) – The client object to set the error handler on.
  • trace_handler (pkgconf_error_handler_func_t) – The error handler to set.
  • trace_handler_data (void*) – Optional data to associate with the error handler.
Returns:

nothing