1/* External declarations for the libdebuginfod client library. 2 Copyright (C) 2019-2020 Red Hat, Inc. 3 This file is part of elfutils. 4 5 This file is free software; you can redistribute it and/or modify 6 it under the terms of either 7 8 * the GNU Lesser General Public License as published by the Free 9 Software Foundation; either version 3 of the License, or (at 10 your option) any later version 11 12 or 13 14 * the GNU General Public License as published by the Free 15 Software Foundation; either version 2 of the License, or (at 16 your option) any later version 17 18 or both in parallel, as here. 19 20 elfutils is distributed in the hope that it will be useful, but 21 WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 General Public License for more details. 24 25 You should have received copies of the GNU General Public License and 26 the GNU Lesser General Public License along with this program. If 27 not, see <http://www.gnu.org/licenses/>. */ 28 29#ifndef _DEBUGINFOD_CLIENT_H 30#define _DEBUGINFOD_CLIENT_H 1 31 32/* Names of environment variables that control the client logic. */ 33#define DEBUGINFOD_URLS_ENV_VAR "DEBUGINFOD_URLS" 34#define DEBUGINFOD_CACHE_PATH_ENV_VAR "DEBUGINFOD_CACHE_PATH" 35#define DEBUGINFOD_TIMEOUT_ENV_VAR "DEBUGINFOD_TIMEOUT" 36#define DEBUGINFOD_PROGRESS_ENV_VAR "DEBUGINFOD_PROGRESS" 37#define DEBUGINFOD_VERBOSE_ENV_VAR "DEBUGINFOD_VERBOSE" 38#define DEBUGINFOD_RETRY_LIMIT_ENV_VAR "DEBUGINFOD_RETRY_LIMIT" 39#define DEBUGINFOD_MAXSIZE_ENV_VAR "DEBUGINFOD_MAXSIZE" 40#define DEBUGINFOD_MAXTIME_ENV_VAR "DEBUGINFOD_MAXTIME" 41#define DEBUGINFOD_HEADERS_FILE_ENV_VAR "DEBUGINFOD_HEADERS_FILE" 42 43/* The libdebuginfod soname. */ 44#define DEBUGINFOD_SONAME "@LIBDEBUGINFOD_SONAME@" 45 46/* Handle for debuginfod-client connection. */ 47#ifndef _ELFUTILS_DEBUGINFOD_CLIENT_TYPEDEF 48typedef struct debuginfod_client debuginfod_client; 49#define _ELFUTILS_DEBUGINFOD_CLIENT_TYPEDEF 1 50#endif 51 52#ifdef __cplusplus 53extern "C" { 54#endif 55 56/* Create a handle for a new debuginfod-client session. */ 57debuginfod_client *debuginfod_begin (void); 58 59/* Query the urls contained in $DEBUGINFOD_URLS for a file with 60 the specified type and build id. If build_id_len == 0, the 61 build_id is supplied as a lowercase hexadecimal string; otherwise 62 it is a binary blob of given length. 63 64 If successful, return a file descriptor to the target, otherwise 65 return a posix error code. If successful, set *path to a 66 strdup'd copy of the name of the same file in the cache. 67 Caller must free() it later. */ 68 69int debuginfod_find_debuginfo (debuginfod_client *client, 70 const unsigned char *build_id, 71 int build_id_len, 72 char **path); 73 74int debuginfod_find_executable (debuginfod_client *client, 75 const unsigned char *build_id, 76 int build_id_len, 77 char **path); 78 79int debuginfod_find_source (debuginfod_client *client, 80 const unsigned char *build_id, 81 int build_id_len, 82 const char *filename, 83 char **path); 84 85int debuginfod_find_section (debuginfod_client *client, 86 const unsigned char *build_id, 87 int build_id_len, 88 const char *section, 89 char **path); 90 91typedef int (*debuginfod_progressfn_t)(debuginfod_client *c, long a, long b); 92void debuginfod_set_progressfn(debuginfod_client *c, 93 debuginfod_progressfn_t fn); 94 95void debuginfod_set_verbose_fd(debuginfod_client *c, int fd); 96 97/* Set the user parameter. */ 98void debuginfod_set_user_data (debuginfod_client *client, void *value); 99 100/* Get the user parameter. */ 101void* debuginfod_get_user_data (debuginfod_client *client); 102 103/* Get the current or last active URL, if known. */ 104const char* debuginfod_get_url (debuginfod_client *client); 105 106/* Returns set of x-debuginfod* header lines received from current or 107 last active transfer, \n separated, if known. */ 108const char* debuginfod_get_headers(debuginfod_client *client); 109 110/* Add an outgoing HTTP request "Header: Value". Copies string. */ 111int debuginfod_add_http_header (debuginfod_client *client, const char* header); 112 113/* Release debuginfod client connection context handle. */ 114void debuginfod_end (debuginfod_client *client); 115 116#ifdef __cplusplus 117} 118#endif 119 120 121#endif /* _DEBUGINFOD_CLIENT_H */ 122