From b40e25568333a80b3f1f3cb7dd2e2a2caf880dcb Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Thu, 19 Mar 2020 20:27:11 -0400 Subject: [PATCH] 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 --- debuginfod/ChangeLog | 6 ++++++ debuginfod/debuginfod-client.c | 16 ++++++++++++++++ debuginfod/debuginfod-find.c | 7 +++++-- debuginfod/debuginfod.h | 10 ++++++++-- debuginfod/libdebuginfod.map | 5 +++++ doc/ChangeLog | 6 ++++++ doc/Makefile.am | 11 +++++++++-- doc/debuginfod_find_debuginfo.3 | 28 +++++++++++++++++++++++++--- doc/debuginfod_get_user_data.3 | 1 + doc/debuginfod_set_user_data.3 | 1 + 10 files changed, 82 insertions(+), 9 deletions(-) create mode 100644 doc/debuginfod_get_user_data.3 create mode 100644 doc/debuginfod_set_user_data.3 diff --git a/debuginfod/ChangeLog b/debuginfod/ChangeLog index ab32b5236..a26f6b271 100644 --- a/debuginfod/ChangeLog +++ b/debuginfod/ChangeLog @@ -1,3 +1,9 @@ +2020-03-22 Frank Ch. Eigler + + * 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 * debuginfod-client.c (debuginfod_query_server): Update diff --git a/debuginfod/debuginfod-client.c b/debuginfod/debuginfod-client.c index 8923099fd..2730dbf7a 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 @@ -902,6 +905,19 @@ debuginfod_begin (void) return client; } +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) { diff --git a/debuginfod/debuginfod-find.c b/debuginfod/debuginfod-find.c index 8bd3a3dba..0b1ca9cf1 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 b4b6a3d2a..fe72f16e9 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 0d26f93e0..a919630da 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 764454121..16b0e99f6 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2020-03-22 Frank Ch. Eigler + + * 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 * debuginfod.8: Note that -R works just like -Z.rpm . diff --git a/doc/Makefile.am b/doc/Makefile.am index b5db01ff7..87d1fee03 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 f9e770b0c..29706513b 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 .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 000000000..16279936e --- /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 000000000..16279936e --- /dev/null +++ b/doc/debuginfod_set_user_data.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 -- 2.47.3