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_dir_list_build
(pkgconf_client_t *client)¶ Bootstraps the package search paths. If the
PKGCONF_PKG_PKGF_ENV_ONLY
flag is set on the client, then only thePKG_CONFIG_PATH
environment variable will be used, otherwise both thePKG_CONFIG_PATH
andPKG_CONFIG_LIBDIR
environment variables will be used.Parameters: - client (pkgconf_client_t*) – The pkgconf client object to bootstrap.
Returns: nothing
-
void
pkgconf_client_init
(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)¶ 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
- personality (pkgconf_cross_personality_t*) – the cross-compile personality to use for defaults
Returns: nothing
-
pkgconf_client_t*
pkgconf_client_new
(pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)¶ 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
- personality (pkgconf_cross_personality_t*) – cross-compile personality to use
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 *filename, size_t len, const char *funcname, 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.
- filename (char*) – The file the function is in.
- lineno (size_t) – The line number currently being executed.
- funcname (char*) – The function name to use.
- 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