include/elfutils/debuginfod.h

0001 /* External declarations for the libdebuginfod client library.
0002    Copyright (C) 2019-2020 Red Hat, Inc.
0003    This file is part of elfutils.
0004
0005    This file is free software; you can redistribute it and/or modify
0006    it under the terms of either
0007
0008    * the GNU Lesser General Public License as published by the Free
0009        Software Foundation; either version 3 of the License, or (at
0010        your option) any later version
0011
0012    or
0013
0014    * the GNU General Public License as published by the Free
0015        Software Foundation; either version 2 of the License, or (at
0016        your option) any later version
0017
0018    or both in parallel, as here.
0019
0020    elfutils is distributed in the hope that it will be useful, but
0021    WITHOUT ANY WARRANTY; without even the implied warranty of
0022    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0023    General Public License for more details.
0024
0025    You should have received copies of the GNU General Public License and
0026    the GNU Lesser General Public License along with this program.  If
0027    not, see <http://www.gnu.org/licenses/>.  */
0028
0029 #ifndef _DEBUGINFOD_CLIENT_H
0030 #define _DEBUGINFOD_CLIENT_H 1
0031
0032 /* Names of environment variables that control the client logic. */
0033 #define DEBUGINFOD_URLS_ENV_VAR "DEBUGINFOD_URLS"
0034 #define DEBUGINFOD_CACHE_PATH_ENV_VAR "DEBUGINFOD_CACHE_PATH"
0035 #define DEBUGINFOD_TIMEOUT_ENV_VAR "DEBUGINFOD_TIMEOUT"
0036 #define DEBUGINFOD_PROGRESS_ENV_VAR "DEBUGINFOD_PROGRESS"
0037 #define DEBUGINFOD_VERBOSE_ENV_VAR "DEBUGINFOD_VERBOSE"
0038 #define DEBUGINFOD_RETRY_LIMIT_ENV_VAR "DEBUGINFOD_RETRY_LIMIT"
0039 #define DEBUGINFOD_MAXSIZE_ENV_VAR "DEBUGINFOD_MAXSIZE"
0040 #define DEBUGINFOD_MAXTIME_ENV_VAR "DEBUGINFOD_MAXTIME"
0041 #define DEBUGINFOD_HEADERS_FILE_ENV_VAR "DEBUGINFOD_HEADERS_FILE"
0042 #define DEBUGINFOD_IMA_CERT_PATH_ENV_VAR "DEBUGINFOD_IMA_CERT_PATH"
0043
0044 /* The libdebuginfod soname.  */
0045 #define DEBUGINFOD_SONAME "libdebuginfod.so.1"
0046
0047 /* Handle for debuginfod-client connection.  */
0048 #ifndef _ELFUTILS_DEBUGINFOD_CLIENT_TYPEDEF
0049 typedef struct debuginfod_client debuginfod_client;
0050 #define _ELFUTILS_DEBUGINFOD_CLIENT_TYPEDEF 1
0051 #endif
0052
0053 #ifdef __cplusplus
0054 extern "C" {
0055 #endif
0056
0057 /* Create a handle for a new debuginfod-client session.  */
0058 debuginfod_client *debuginfod_begin (void);
0059
0060 /* Query the urls contained in $DEBUGINFOD_URLS for a file with
0061    the specified type and build id.  If build_id_len == 0, the
0062    build_id is supplied as a lowercase hexadecimal string; otherwise
0063    it is a binary blob of given length.
0064
0065    If successful, return a file descriptor to the target, otherwise
0066    return a negative POSIX error code.  If successful, set *path to a
0067    strdup'd copy of the name of the same file in the cache.  Caller
0068    must free() it later. */
0069
0070 int debuginfod_find_debuginfo (debuginfod_client *client,
0071                    const unsigned char *build_id,
0072                                int build_id_len,
0073                                char **path);
0074
0075 int debuginfod_find_executable (debuginfod_client *client,
0076                 const unsigned char *build_id,
0077                                 int build_id_len,
0078                                 char **path);
0079
0080 int debuginfod_find_source (debuginfod_client *client,
0081                 const unsigned char *build_id,
0082                             int build_id_len,
0083                             const char *filename,
0084                             char **path);
0085
0086 int debuginfod_find_section (debuginfod_client *client,
0087                  const unsigned char *build_id,
0088                  int build_id_len,
0089                  const char *section,
0090                  char **path);
0091
0092 /* Query the urls contained in $DEBUGINFOD_URLS for metadata
0093    with given query key/value.
0094
0095    If successful, return a file descriptor to the JSON document
0096    describing matches, otherwise return a negative POSIX error code.  If
0097    successful, set *path to a strdup'd copy of the name of the same
0098    file in the cache.  Caller must free() it later.
0099
0100    See the debuginfod-find(1) man page for examples of the supported types
0101    of key/value queries and their JSON results.
0102    */
0103 int debuginfod_find_metadata (debuginfod_client *client,
0104                               const char *key,
0105                               const char* value,
0106                               char **path);
0107
0108 typedef int (*debuginfod_progressfn_t)(debuginfod_client *c, long a, long b);
0109 void debuginfod_set_progressfn(debuginfod_client *c,
0110                    debuginfod_progressfn_t fn);
0111
0112 void debuginfod_set_verbose_fd(debuginfod_client *c, int fd);
0113
0114 /* Set the user parameter.  */
0115 void debuginfod_set_user_data (debuginfod_client *client, void *value);
0116
0117 /* Get the user parameter.  */
0118 void* debuginfod_get_user_data (debuginfod_client *client);
0119
0120 /* Get the current or last active URL, if known.  */
0121 const char* debuginfod_get_url (debuginfod_client *client);
0122
0123 /* Returns set of x-debuginfod* header lines received from current or
0124    last active transfer, \n separated, if known. */
0125 const char* debuginfod_get_headers(debuginfod_client *client);
0126
0127 /* Add an outgoing HTTP request  "Header: Value".  Copies string.  */
0128 int debuginfod_add_http_header (debuginfod_client *client, const char* header);
0129
0130 /* Release debuginfod client connection context handle.  */
0131 void debuginfod_end (debuginfod_client *client);
0132
0133 #ifdef __cplusplus
0134 }
0135 #endif
0136
0137
0138 #endif /* _DEBUGINFOD_CLIENT_H */