debuginfod client API: add get/set user_data functions

Add a pair of functions to associate a void* parameter with a client
object.  Requested by GDB team as a way to pass file names and such
user-interface data through to a progressfn callback.

Signed-off-by: Frank Ch. Eigler <fche@redhat.com>

10 files changed, 82 insertions, 9 deletions

diff --git a/debuginfod/ChangeLog b/debuginfod/ChangeLog
index ab32b523..a26f6b27 100644
--- a/debuginfod/ChangeLog
+++ b/debuginfod/ChangeLog
@@ -1,3 +1,9 @@
+2020-03-22  Frank Ch. Eigler  <fche@redhat.com>
+
+	* debuginfod.h, libdebuginfod.map: New functions for _get/set_user().
+	* debuginfod-client.c: Implement them.
+	* debuginfod-find.c: Include a token call just for testing them.
+
 2020-03-03  Aaron Merey  <amerey@redhat.com>
 
 	* debuginfod-client.c (debuginfod_query_server): Update
diff --git a/debuginfod/debuginfod-client.c b/debuginfod/debuginfod-client.c
index 8923099f..2730dbf7 100644
--- a/debuginfod/debuginfod-client.c
+++ b/debuginfod/debuginfod-client.c
@@ -79,6 +79,9 @@ struct debuginfod_client
   /* Progress/interrupt callback function. */
   debuginfod_progressfn_t progressfn;
 
+  /* Stores user data. */
+  void* user_data;
+
   /* Can contain all other context, like cache_path, server_urls,
      timeout or other info gotten from environment variables, the
      handle data, etc. So those don't have to be reparsed and
@@ -903,6 +906,19 @@ debuginfod_begin (void)
 }
 
 void
+debuginfod_set_user_data(debuginfod_client *client,
+                         void *data)
+{
+  client->user_data = data;
+}
+
+void *
+debuginfod_get_user_data(debuginfod_client *client)
+{
+  return client->user_data;
+}
+
+void
 debuginfod_end (debuginfod_client *client)
 {
   free (client);
diff --git a/debuginfod/debuginfod-find.c b/debuginfod/debuginfod-find.c
index 8bd3a3db..0b1ca9cf 100644
--- a/debuginfod/debuginfod-find.c
+++ b/debuginfod/debuginfod-find.c
@@ -91,6 +91,9 @@ main(int argc, char** argv)
       return 1;
     }
 
+  /* Exercise user data pointer, to support testing only. */
+  debuginfod_set_user_data (client, (void *)"Progress");
+
   int remaining;
   (void) argp_parse (&argp, argc, argv, ARGP_IN_ORDER|ARGP_NO_ARGS, &remaining, NULL);
 
@@ -130,6 +133,8 @@ main(int argc, char** argv)
       return 1;
     }
 
+  debuginfod_end (client);
+
   if (rc < 0)
     {
       fprintf(stderr, "Server query failed: %s\n", strerror(-rc));
@@ -137,9 +142,7 @@ main(int argc, char** argv)
     }
 
   printf("%s\n", cache_name);
-
   free (cache_name);
-  debuginfod_end (client);
 
   return 0;
 }
diff --git a/debuginfod/debuginfod.h b/debuginfod/debuginfod.h
index b4b6a3d2..fe72f16e 100644
--- a/debuginfod/debuginfod.h
+++ b/debuginfod/debuginfod.h
@@ -1,5 +1,5 @@
 /* External declarations for the libdebuginfod client library.
-   Copyright (C) 2019 Red Hat, Inc.
+   Copyright (C) 2019-2020 Red Hat, Inc.
    This file is part of elfutils.
 
    This file is free software; you can redistribute it and/or modify
@@ -54,7 +54,7 @@ debuginfod_client *debuginfod_begin (void);
    return a posix error code.  If successful, set *path to a
    strdup'd copy of the name of the same file in the cache.
    Caller must free() it later. */
-  
+
 int debuginfod_find_debuginfo (debuginfod_client *client,
 			       const unsigned char *build_id,
                                int build_id_len,
@@ -75,6 +75,12 @@ typedef int (*debuginfod_progressfn_t)(debuginfod_client *c, long a, long b);
 void debuginfod_set_progressfn(debuginfod_client *c,
 			       debuginfod_progressfn_t fn);
 
+/* Set the user parameter.  */
+void debuginfod_set_user_data (debuginfod_client *client, void *value);
+
+/* Get the user parameter.  */
+void* debuginfod_get_user_data (debuginfod_client *client);
+
 /* Release debuginfod client connection context handle.  */
 void debuginfod_end (debuginfod_client *client);
 
diff --git a/debuginfod/libdebuginfod.map b/debuginfod/libdebuginfod.map
index 0d26f93e..a919630d 100644
--- a/debuginfod/libdebuginfod.map
+++ b/debuginfod/libdebuginfod.map
@@ -8,3 +8,8 @@ ELFUTILS_0.178 {
   debuginfod_find_source;
   debuginfod_set_progressfn;
 } ELFUTILS_0;
+ELFUTILS_0.179 {
+  global:
+  debuginfod_set_user_data;
+  debuginfod_get_user_data;
+};
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 76445412..16b0e99f 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2020-03-22  Frank Ch. Eigler  <fche@redhat.com>
+
+	* debuginfod_get_user.3, _set_user.3: New functions, documented ...
+	* debuginfod_find_debuginfo.3: ... here.
+	* Makefile.am (notrans_dist_*_man3): List all debuginfod .3 functions.
+
 2020-02-25  Frank Ch. Eigler  <fche@redhat.com>
 
 	* debuginfod.8: Note that -R works just like -Z.rpm .
diff --git a/doc/Makefile.am b/doc/Makefile.am
index b5db01ff..87d1fee0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,7 @@
 ## Process this file with automake to create Makefile.in
 ## Configure input file for elfutils.
 ##
-## Copyright (C) 1996-2001, 2002, 2005, 2019 Red Hat, Inc.
+## Copyright (C) 1996-2001, 2002, 2005, 2019-2020 Red Hat, Inc.
 ## This file is part of elfutils.
 ##
 ## This file is free software; you can redistribute it and/or modify
@@ -24,7 +24,14 @@ notrans_dist_man1_MANS=
 
 if DEBUGINFOD
 notrans_dist_man8_MANS += debuginfod.8
-notrans_dist_man3_MANS += debuginfod_find_debuginfo.3 debuginfod_find_source.3 debuginfod_find_executable.3 debuginfod_set_progressfn.3
+notrans_dist_man3_MANS += debuginfod_begin.3
+notrans_dist_man3_MANS += debuginfod_end.3
+notrans_dist_man3_MANS += debuginfod_find_debuginfo.3
+notrans_dist_man3_MANS += debuginfod_find_executable.3
+notrans_dist_man3_MANS += debuginfod_find_source.3
+notrans_dist_man3_MANS += debuginfod_get_user_data.3
+notrans_dist_man3_MANS += debuginfod_set_progressfn.3
+notrans_dist_man3_MANS += debuginfod_set_user_data.3
 notrans_dist_man1_MANS += debuginfod-find.1
 endif
 
diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3
index f9e770b0..29706513 100644
--- a/doc/debuginfod_find_debuginfo.3
+++ b/doc/debuginfod_find_debuginfo.3
@@ -21,9 +21,15 @@ debuginfod_find_debuginfo \- request debuginfo from debuginfod
 .nf
 .B #include <elfutils/debuginfod.h>
 .PP
+Link with \fB-ldebuginfod\fP.
+
+CONNECTION HANDLE
+
 .BI "debuginfod_client *debuginfod_begin(void);"
 .BI "void debuginfod_end(debuginfod_client *" client ");"
 
+LOOKUP FUNCTIONS
+
 .BI "int debuginfod_find_debuginfo(debuginfod_client *" client ","
 .BI "                              const unsigned char *" build_id ","
 .BI "                              int " build_id_len ","
@@ -38,12 +44,15 @@ debuginfod_find_debuginfo \- request debuginfo from debuginfod
 .BI "                           const char *" filename ","
 .BI "                           char ** " path ");"
 
+OPTIONAL FUNCTIONS
+
 .BI "typedef int (*debuginfod_progressfn_t)(debuginfod_client *" client ","
 .BI "                                       long a, long b);"
 .BI "void debuginfod_set_progressfn(debuginfod_client *" client ","
 .BI "                               debuginfod_progressfn_t " progressfn ");"
-
-Link with \fB-ldebuginfod\fP.
+.BI "void debuginfod_set_user_data(debuginfod_client *" client ","
+.BI "                              void *" data ");"
+.BI "void* debuginfod_get_user_data(debuginfod_client *" client ");"
 
 .SH DESCRIPTION
 
@@ -102,7 +111,12 @@ to the client cache and a file descriptor to that file is returned.
 The caller needs to \fBclose\fP() this descriptor.  Otherwise, a
 negative error code is returned.
 
-.SH "PROGRESS CALLBACK"
+.SH "OPTIONAL FUNCTIONS"
+
+A small number of optional functions are available to tune or query
+the operation of the debuginfod client.
+
+.SS "PROGRESS CALLBACK"
 
 As the \fBdebuginfod_find_*\fP() functions may block for seconds or
 longer, a progress callback function is called periodically, if
@@ -125,6 +139,14 @@ continue the work, or any other value to stop work as soon as
 possible.  Consequently, the \fBdebuginfod_find_*\fP() function will
 likely return with an error, but might still succeed.
 
+.SS "USER DATA POINTER"
+
+A single \fIvoid *\fP pointer associated with the connection handle
+may be set any time via
+.BR \%debuginfod_set_user_data () ,
+and retrieved via
+.BR \%debuginfod_get_user_data () .
+The value is undefined if unset.
 
 .SH "CACHE"
 If the query is successful, the \fBdebuginfod_find_*\fP() functions save
diff --git a/doc/debuginfod_get_user_data.3 b/doc/debuginfod_get_user_data.3
new file mode 100644
index 00000000..16279936
--- /dev/null
+++ b/doc/debuginfod_get_user_data.3
@@ -0,0 +1 @@
+.so man3/debuginfod_find_debuginfo.3
diff --git a/doc/debuginfod_set_user_data.3 b/doc/debuginfod_set_user_data.3
new file mode 100644
index 00000000..16279936
--- /dev/null
+++ b/doc/debuginfod_set_user_data.3
@@ -0,0 +1 @@
+.so man3/debuginfod_find_debuginfo.3