/usr/include/t3/key/t3key/key.h is in libt3key-dev 0.2.8-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 | /* Copyright (C) 2011,2018 G.P. Halkes
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef T3_KEY_H
#define T3_KEY_H
/** @defgroup t3key_other Functions, constants and enums. */
/** @addtogroup t3key_other */
/** @{ */
#include <stdlib.h>
#include <t3key/key_api.h>
#ifdef __cplusplus
extern "C" {
#endif
/** The version of libt3key encoded as a single integer.
The least significant 8 bits represent the patch level.
The second 8 bits represent the minor version.
The third 8 bits represent the major version.
At runtime, the value of T3_KEY_VERSION can be retrieved by calling
::t3_key_get_version.
@internal
The value 0 is an invalid value which should be replaced by the script
that builds the release package.
*/
#define T3_KEY_VERSION 0x000208
/* To allow modification of the structures within the key library, it defines
the macro T3_KEY_CONST as emtpy. However, for external use the structures
should be regarded as constant. This will prevent inadvertent modification
of these structures.
*/
#ifndef T3_KEY_CONST
#define T3_KEY_CONST const
#endif
typedef struct t3_key_node_t t3_key_node_t;
/** A structure which is part of a singly linked list and contains a single key definition. */
struct t3_key_node_t {
T3_KEY_CONST char *key; /**< The name of the key (with modifiers). */
T3_KEY_CONST char *string; /**< The character sequence associated with the key. */
T3_KEY_CONST size_t string_length; /**< The length in bytes of t3_key_node_t::string. */
T3_KEY_CONST t3_key_node_t
*next; /**< Pointer to the next ::t3_key_node_t in the singly-linked list. */
};
typedef struct t3_key_string_list_t t3_key_string_list_t;
/** A structure which is part of a singly linked list and contains a single string. */
struct t3_key_string_list_t {
T3_KEY_CONST char *string; /**< A string. */
T3_KEY_CONST t3_key_string_list_t
*next; /**< Pointer to the next ::t3_key_string_list_t in the singly-linked list. */
};
#include "key_errors.h"
/** @name Error codes (libt3key specific) */
/*@{*/
/** Error code: invalid key-database file format. */
#define T3_ERR_INVALID_FORMAT (-32)
/** Error code: Required terminfo key not found in terminfo database. */
#define T3_ERR_TERMINFO_UNKNOWN (-31)
/** Error code: Key database contains no maps. */
#define T3_ERR_NOMAP (-30)
/** Error code: Key database is truncated. */
#define T3_ERR_TRUNCATED_DB (-29)
/** Error code: Error reading key database. */
#define T3_ERR_READ_ERROR (-28)
/** Error code: Key database is of an unsupported version. */
#define T3_ERR_WRONG_VERSION (-27)
/*@}*/
/** Load a key map from database.
@param term The terminal name to use to find the key database.
@param map_name Name of the map to load for the terminal.
@param error Location to store the error code.
@return NULL on failure, a list of ::t3_key_node_t structures on success.
If @p term is @c NULL, the environment variable @c TERM is used to retrieve the
terminal name. The @p map_name parameter indicates which map to load. If
@p map_name is @c NULL, the map indicated by %best in the database is used.
Before calling this function, you must ensure that the terminfo database
has been initialised by calling one of @c setupterm, @c initscr, @c newterm,
@c setterm, or the @c t3_term_init function.
*/
T3_KEY_API T3_KEY_CONST t3_key_node_t *t3_key_load_map(const char *term, const char *map_name,
int *error);
/** Free a key map.
@param list The list of keys to free.
*/
T3_KEY_API void t3_key_free_map(T3_KEY_CONST t3_key_node_t *list);
/** Get map names from database.
@param term The terminal name to use to find the key database.
@param error Location to store the error code.
@return NULL on failure, a list of ::t3_key_string_list_t structures on success.
If @p term is @c NULL, the environment variable TERM is used to retrieve the
terminal name.
*/
T3_KEY_API T3_KEY_CONST t3_key_string_list_t *t3_key_get_map_names(const char *term, int *error);
/** Free a map names list.
@param list The list of map names to free.
*/
T3_KEY_API void t3_key_free_names(T3_KEY_CONST t3_key_string_list_t *list);
/** Get name of best map from database.
@param term The terminal name to use to find the key database.
@param error Location to store the error code.
@return NULL on failure, the name of the best map on success.
If @p term is @c NULL, the environment variable TERM is used to retrieve the
terminal name. The name is allocated using @c malloc.
*/
T3_KEY_API char *t3_key_get_best_map_name(const char *term, int *error);
/** Get a named node from a map.
@param map The map to search.
@param name The name of the node to search for, or @c NULL to continue the last search.
@return The ::t3_key_node_t with the given name, or @c NULL if no such node exists.
Multiple nodes may exist with the same name. To retrieve all of them, ::t3_key_get_named_node
may be called multiple times. The second and later calls @b must use the returned value
as the @p map parameter, and pass @c NULL as @p name.
*/
T3_KEY_API T3_KEY_CONST t3_key_node_t *t3_key_get_named_node(T3_KEY_CONST t3_key_node_t *map,
const char *name);
/** Get the value of ::T3_KEY_VERSION corresponding to the actual used library.
@ingroup t3window_other
@return The value of ::T3_KEY_VERSION.
This function can be useful to determine at runtime what version of the library
was linked to the program. Although currently there are no known uses for this
information, future library additions may prompt library users to want to operate
differently depending on the available features.
*/
T3_KEY_API long t3_key_get_version(void);
/** Get a string description for an error code.
@param error The error code returned by a function in libt3key.
@return An internationalized string description for the error code.
*/
T3_KEY_API const char *t3_key_strerror(int error);
#ifdef __cplusplus
} /* extern "C" */
#endif
/** @} */
#endif
|