libpkgconf: client: add trace logging too

doc/libpkgconf-client.rst

@@ -97,6 +97,15 @@ thread boundaries.
    :return: true if the warn handler processed the message, else false.
    :rtype: bool
 
+.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)
+
+   Report a message to a client-registered trace handler.
+
+   :param pkgconf_client_t* client: The pkgconf client object to report the trace message to.
+   :param char* format: A printf-style format string to use for formatting the trace message.
+   :return: true if the trace handler processed the message, else false.
+   :rtype: bool
+
 .. c:function:: bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data)
 
    The default pkgconf error handler.
@@ -171,3 +180,19 @@ thread boundaries.
    :param pkgconf_error_handler_func_t error_handler: The error handler to set.
    :param void* error_handler_data: Optional data to associate with the error handler.
    :return: nothing
+
+.. c:function:: pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
+
+   Returns the error handler if one is set, else ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to get the error handler from.
+   :return: a function pointer to the error handler or ``NULL``
+
+.. c:function:: 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``.
+
+   :param pkgconf_client_t* client: The client object to set the error handler on.
+   :param pkgconf_error_handler_func_t trace_handler: The error handler to set.
+   :param void* trace_handler_data: Optional data to associate with the error handler.
+   :return: nothing

libpkgconf/client.c

@@ -54,6 +54,7 @@ pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error
 
 	pkgconf_client_set_error_handler(client, error_handler, error_handler_data);
 	pkgconf_client_set_warn_handler(client, NULL, NULL);
+	pkgconf_client_set_trace_handler(client, NULL, NULL);
 
 	pkgconf_path_build_from_environ("PKG_CONFIG_SYSTEM_LIBRARY_PATH", SYSTEM_LIBDIR, &client->filter_libdirs, false);
 	pkgconf_path_build_from_environ("PKG_CONFIG_SYSTEM_INCLUDE_PATH", SYSTEM_INCLUDEDIR, &client->filter_includedirs, false);
@@ -269,6 +270,31 @@ pkgconf_warn(const pkgconf_client_t *client, const char *format, ...)
 	return client->warn_handler(errbuf, client, client->warn_handler_data);
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)
+ *
+ *    Report a message to a client-registered trace handler.
+ *
+ *    :param pkgconf_client_t* client: The pkgconf client object to report the trace message to.
+ *    :param char* format: A printf-style format string to use for formatting the trace message.
+ *    :return: true if the trace handler processed the message, else false.
+ *    :rtype: bool
+ */
+bool
+pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)
+{
+	char errbuf[PKGCONF_BUFSIZE];
+	va_list va;
+
+	va_start(va, format);
+	vsnprintf(errbuf, sizeof errbuf, format, va);
+	va_end(va);
+
+	return client->trace_handler(errbuf, client, client->trace_handler_data);
+}
+
 /*
  * !doc
  *
@@ -442,3 +468,41 @@ pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler
 	if (client->error_handler == NULL)
 		client->error_handler = pkgconf_default_error_handler;
 }
+
+/*
+ * !doc
+ *
+ * .. c:function:: pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
+ *
+ *    Returns the error handler if one is set, else ``NULL``.
+ *
+ *    :param pkgconf_client_t* client: The client object to get the error handler from.
+ *    :return: a function pointer to the error handler or ``NULL``
+ */
+pkgconf_error_handler_func_t
+pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
+{
+	return client->trace_handler;
+}
+
+/*
+ * !doc
+ *
+ * .. c:function:: 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``.
+ *
+ *    :param pkgconf_client_t* client: The client object to set the error handler on.
+ *    :param pkgconf_error_handler_func_t trace_handler: The error handler to set.
+ *    :param void* trace_handler_data: Optional data to associate with the error handler.
+ *    :return: nothing
+ */
+void
+pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data)
+{
+	client->trace_handler = trace_handler;
+	client->trace_handler_data = trace_handler_data;
+
+	if (client->trace_handler == NULL)
+		client->trace_handler = pkgconf_default_error_handler;
+}

libpkgconf/libpkgconf.h

@@ -146,9 +146,11 @@ struct pkgconf_client_ {
 
 	void *error_handler_data;
 	void *warn_handler_data;
+	void *trace_handler_data;
 
 	pkgconf_error_handler_func_t error_handler;
 	pkgconf_error_handler_func_t warn_handler;
+	pkgconf_error_handler_func_t trace_handler;
 
 	FILE *auditf;
 
@@ -177,6 +179,8 @@ pkgconf_error_handler_func_t pkgconf_client_get_warn_handler(const pkgconf_clien
 void pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data);
 pkgconf_error_handler_func_t pkgconf_client_get_error_handler(const pkgconf_client_t *client);
 void pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data);
+pkgconf_error_handler_func_t pkgconf_client_get_trace_handler(const pkgconf_client_t *client);
+void pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data);
 
 #define PKGCONF_IS_MODULE_SEPARATOR(c) ((c) == ',' || isspace ((unsigned int)(c)))
 #define PKGCONF_IS_OPERATOR_CHAR(c) ((c) == '<' || (c) == '>' || (c) == '!' || (c) == '=')
@@ -214,6 +218,7 @@ void pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_ha
 
 bool pkgconf_error(const pkgconf_client_t *client, const char *format, ...) PRINTFLIKE(2, 3);
 bool pkgconf_warn(const pkgconf_client_t *client, const char *format, ...) PRINTFLIKE(2, 3);
+bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...) PRINTFLIKE(2, 3);
 bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data);
 
 pkgconf_pkg_t *pkgconf_pkg_ref(const pkgconf_client_t *client, pkgconf_pkg_t *pkg);