1 2libpkgconf `client` module 3========================== 4 5The libpkgconf `client` module implements the `pkgconf_client_t` "client" object. 6Client objects store all necessary state for libpkgconf allowing for multiple instances to run 7in parallel. 8 9Client objects are not thread safe, in other words, a client object should not be shared across 10thread boundaries. 11 12.. c:function:: void pkgconf_client_dir_list_build(pkgconf_client_t *client) 13 14 Bootstraps the package search paths. If the ``PKGCONF_PKG_PKGF_ENV_ONLY`` `flag` is set on the client, 15 then only the ``PKG_CONFIG_PATH`` environment variable will be used, otherwise both the 16 ``PKG_CONFIG_PATH`` and ``PKG_CONFIG_LIBDIR`` environment variables will be used. 17 18 :param pkgconf_client_t* client: The pkgconf client object to bootstrap. 19 :return: nothing 20 21.. c:function:: 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) 22 23 Initialise a pkgconf client object. 24 25 :param pkgconf_client_t* client: The client to initialise. 26 :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors. 27 :param void* error_handler_data: user data passed to optional error handler 28 :param pkgconf_cross_personality_t* personality: the cross-compile personality to use for defaults 29 :return: nothing 30 31.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality) 32 33 Allocate and initialise a pkgconf client object. 34 35 :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors. 36 :param void* error_handler_data: user data passed to optional error handler 37 :param pkgconf_cross_personality_t* personality: cross-compile personality to use 38 :return: A pkgconf client object. 39 :rtype: pkgconf_client_t* 40 41.. c:function:: void pkgconf_client_deinit(pkgconf_client_t *client) 42 43 Release resources belonging to a pkgconf client object. 44 45 :param pkgconf_client_t* client: The client to deinitialise. 46 :return: nothing 47 48.. c:function:: void pkgconf_client_free(pkgconf_client_t *client) 49 50 Release resources belonging to a pkgconf client object and then free the client object itself. 51 52 :param pkgconf_client_t* client: The client to deinitialise and free. 53 :return: nothing 54 55.. c:function:: const char *pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client) 56 57 Retrieves the client's sysroot directory (if any). 58 59 :param pkgconf_client_t* client: The client object being accessed. 60 :return: A string containing the sysroot directory or NULL. 61 :rtype: const char * 62 63.. c:function:: void pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir) 64 65 Sets or clears the sysroot directory on a client object. Any previous sysroot directory setting is 66 automatically released if one was previously set. 67 68 Additionally, the global tuple ``$(pc_sysrootdir)`` is set as appropriate based on the new setting. 69 70 :param pkgconf_client_t* client: The client object being modified. 71 :param char* sysroot_dir: The sysroot directory to set or NULL to unset. 72 :return: nothing 73 74.. c:function:: const char *pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client) 75 76 Retrieves the client's buildroot directory (if any). 77 78 :param pkgconf_client_t* client: The client object being accessed. 79 :return: A string containing the buildroot directory or NULL. 80 :rtype: const char * 81 82.. c:function:: void pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir) 83 84 Sets or clears the buildroot directory on a client object. Any previous buildroot directory setting is 85 automatically released if one was previously set. 86 87 Additionally, the global tuple ``$(pc_top_builddir)`` is set as appropriate based on the new setting. 88 89 :param pkgconf_client_t* client: The client object being modified. 90 :param char* buildroot_dir: The buildroot directory to set or NULL to unset. 91 :return: nothing 92 93.. c:function:: bool pkgconf_error(const pkgconf_client_t *client, const char *format, ...) 94 95 Report an error to a client-registered error handler. 96 97 :param pkgconf_client_t* client: The pkgconf client object to report the error to. 98 :param char* format: A printf-style format string to use for formatting the error message. 99 :return: true if the error handler processed the message, else false. 100 :rtype: bool 101 102.. c:function:: bool pkgconf_warn(const pkgconf_client_t *client, const char *format, ...) 103 104 Report an error to a client-registered warn handler. 105 106 :param pkgconf_client_t* client: The pkgconf client object to report the error to. 107 :param char* format: A printf-style format string to use for formatting the warning message. 108 :return: true if the warn handler processed the message, else false. 109 :rtype: bool 110 111.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *filename, size_t len, const char *funcname, const char *format, ...) 112 113 Report a message to a client-registered trace handler. 114 115 :param pkgconf_client_t* client: The pkgconf client object to report the trace message to. 116 :param char* filename: The file the function is in. 117 :param size_t lineno: The line number currently being executed. 118 :param char* funcname: The function name to use. 119 :param char* format: A printf-style format string to use for formatting the trace message. 120 :return: true if the trace handler processed the message, else false. 121 :rtype: bool 122 123.. c:function:: bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data) 124 125 The default pkgconf error handler. 126 127 :param char* msg: The error message to handle. 128 :param pkgconf_client_t* client: The client object the error originated from. 129 :param void* data: An opaque pointer to extra data associated with the client for error handling. 130 :return: true (the function does nothing to process the message) 131 :rtype: bool 132 133.. c:function:: unsigned int pkgconf_client_get_flags(const pkgconf_client_t *client) 134 135 Retrieves resolver-specific flags associated with a client object. 136 137 :param pkgconf_client_t* client: The client object to retrieve the resolver-specific flags from. 138 :return: a bitfield of resolver-specific flags 139 :rtype: uint 140 141.. c:function:: void pkgconf_client_set_flags(pkgconf_client_t *client, unsigned int flags) 142 143 Sets resolver-specific flags associated with a client object. 144 145 :param pkgconf_client_t* client: The client object to set the resolver-specific flags on. 146 :return: nothing 147 148.. c:function:: const char *pkgconf_client_get_prefix_varname(const pkgconf_client_t *client) 149 150 Retrieves the name of the variable that should contain a module's prefix. 151 In some cases, it is necessary to override this variable to allow proper path relocation. 152 153 :param pkgconf_client_t* client: The client object to retrieve the prefix variable name from. 154 :return: the prefix variable name as a string 155 :rtype: const char * 156 157.. c:function:: void pkgconf_client_set_prefix_varname(pkgconf_client_t *client, const char *prefix_varname) 158 159 Sets the name of the variable that should contain a module's prefix. 160 If the variable name is ``NULL``, then the default variable name (``prefix``) is used. 161 162 :param pkgconf_client_t* client: The client object to set the prefix variable name on. 163 :param char* prefix_varname: The prefix variable name to set. 164 :return: nothing 165 166.. c:function:: pkgconf_client_get_warn_handler(const pkgconf_client_t *client) 167 168 Returns the warning handler if one is set, else ``NULL``. 169 170 :param pkgconf_client_t* client: The client object to get the warn handler from. 171 :return: a function pointer to the warn handler or ``NULL`` 172 173.. c:function:: pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data) 174 175 Sets a warn handler on a client object or uninstalls one if set to ``NULL``. 176 177 :param pkgconf_client_t* client: The client object to set the warn handler on. 178 :param pkgconf_error_handler_func_t warn_handler: The warn handler to set. 179 :param void* warn_handler_data: Optional data to associate with the warn handler. 180 :return: nothing 181 182.. c:function:: pkgconf_client_get_error_handler(const pkgconf_client_t *client) 183 184 Returns the error handler if one is set, else ``NULL``. 185 186 :param pkgconf_client_t* client: The client object to get the error handler from. 187 :return: a function pointer to the error handler or ``NULL`` 188 189.. c:function:: pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data) 190 191 Sets a warn handler on a client object or uninstalls one if set to ``NULL``. 192 193 :param pkgconf_client_t* client: The client object to set the error handler on. 194 :param pkgconf_error_handler_func_t error_handler: The error handler to set. 195 :param void* error_handler_data: Optional data to associate with the error handler. 196 :return: nothing 197 198.. c:function:: pkgconf_client_get_trace_handler(const pkgconf_client_t *client) 199 200 Returns the error handler if one is set, else ``NULL``. 201 202 :param pkgconf_client_t* client: The client object to get the error handler from. 203 :return: a function pointer to the error handler or ``NULL`` 204 205.. c:function:: pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data) 206 207 Sets a warn handler on a client object or uninstalls one if set to ``NULL``. 208 209 :param pkgconf_client_t* client: The client object to set the error handler on. 210 :param pkgconf_error_handler_func_t trace_handler: The error handler to set. 211 :param void* trace_handler_data: Optional data to associate with the error handler. 212 :return: nothing 213