2 * This file is part of ltrace.
3 * Copyright (C) 2012, 2013 Petr Machata, Red Hat Inc.
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License as
7 * published by the Free Software Foundation; either version 2 of the
8 * License, or (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
30 /* Function prototype. */
32 /* Vector of struct param. */
35 struct arg_type_info *return_info;
36 int own_return_info : 1;
39 /* Initialize a prototype PROTO. The name will be NAME, and the
40 * corresponding string will be owned and freed on destroy if
42 void prototype_init(struct prototype *proto);
44 /* Destroy PROTO (but don't free the memory block pointed-to by
46 void prototype_destroy(struct prototype *proto);
48 /* Add new parameter PARAM to PROTO. The structure contents are
49 * copied and PARAM pointer itself is not owned by PROTO. */
50 int prototype_push_param(struct prototype *proto, struct param *param);
52 /* Return number of parameters of prototype. */
53 size_t prototype_num_params(struct prototype *proto);
55 /* Destroy N-th parameter from PROTO. N shall be smaller than the
56 * number of parameters. */
57 void prototype_destroy_nth_param(struct prototype *proto, size_t n);
59 /* Get N-th parameter of PROTO. N shall be smaller than the number of
61 struct param *prototype_get_nth_param(struct prototype *proto, size_t n);
63 /* Iterate through the parameters of PROTO. See callback.h for notes
64 * on iteration interfaces. */
65 struct param *prototype_each_param
66 (struct prototype *proto, struct param *start_after,
67 enum callback_status (*cb)(struct prototype *, struct param *, void *),
70 /* For storing type aliases. */
72 struct arg_type_info *info;
77 /* Initialize a named type INFO, which, if OWN_TYPE, is destroyed when
78 * named_type_destroy is called. */
79 void named_type_init(struct named_type *named,
80 struct arg_type_info *info, int own_type);
82 void named_type_destroy(struct named_type *named);
84 /* One prototype library. */
86 /* Other libraries to look through if the definition is not
87 * found here. Note that due to the way imports are stored,
88 * there is no way to distinguish where exactly (at which
89 * place of the config file) the import was made. */
92 /* Dictionary of name->struct prototype. */
93 struct dict prototypes;
95 /* Dictionary of name->struct named_type. */
96 struct dict named_types;
98 /* Reference count. */
102 /* Initialize PLIB. */
103 void protolib_init(struct protolib *plib);
106 void protolib_destroy(struct protolib *plib);
108 /* Push IMPORT to PLIB. Returns 0 on success or a negative value on
109 * failure. In particular, -2 is returned if mutual import is
111 int protolib_add_import(struct protolib *plib, struct protolib *import);
113 /* Add a prototype PROTO to PLIB. Returns 0 on success or a negative
114 * value on failure. NAME is owned and released on PLIB destruction
116 int protolib_add_prototype(struct protolib *plib,
117 const char *name, int own_name,
118 struct prototype *proto);
120 /* Add a named type NAMED to PLIB. Returns 0 on success or a negative
121 * value on failure. NAME is owned and released on PLIB destruction
122 * if OWN_NAME. NAMED _pointer_ is copied to PLIB. */
123 int protolib_add_named_type(struct protolib *plib,
124 const char *name, int own_name,
125 struct named_type *named);
127 /* Lookup prototype named NAME in PLIB. If none is found and IMPORTS
128 * is true, look recursively in each of the imports. Returns the
129 * corresponding prototype, or NULL if none was found. */
130 struct prototype *protolib_lookup_prototype(struct protolib *plib,
131 const char *name, bool imports);
133 /* Add a named type NAMED to PLIB. Returns 0 on success or a negative
134 * value on failure. */
135 int protolib_add_type(struct protolib *plib, struct named_type *named);
137 /* Lookup type named NAME in PLIB. If none is found and IMPORTS is
138 * true, look recursively in each of the imports. Returns the
139 * corresponding type, or NULL if none was found. */
140 struct named_type *protolib_lookup_type(struct protolib *plib,
141 const char *name, bool imports);
143 /* A cache of prototype libraries. Can load prototype libraries on
146 * XXX ltrace should open one config per ABI, which maps long, int,
147 * etc. to uint32_t etc. It would also map char to either of
148 * {u,}int8_t. Other protolibs would have this as implicit import.
149 * That would mean that the cache needs ABI tagging--each ABI should
150 * have a separate prototype cache, because the types will potentially
151 * differ between the ABI's. protolib cache would then naturally be
152 * stored in the ABI object, when this is introduced. */
153 struct protolib_cache {
154 /* Dictionary of filename->protolib*. */
155 struct dict protolibs;
157 /* Fake module for implicit imports. This is populated by all
158 * files coming from -F. When -F is empty, it also contains
159 * either $HOME/.ltrace.conf, or /etc/ltrace.conf (whichever
161 struct protolib imports;
163 /* For tracking uses of cache during cache's own
168 /* Initialize CACHE. Returns 0 on success or a negative value on
170 int protolib_cache_init(struct protolib_cache *cache,
171 struct protolib *import);
174 void protolib_cache_destroy(struct protolib_cache *cache);
176 /* Get protolib corresponding to KEY from CACHE. KEY would typically
177 * be the soname of a library for which a protolib should be obtained.
178 * If none has been loaded yet, load a new protolib, cache and return
179 * it. Returns NULL for failures.
181 * Protolibs are loaded from a config directory. If -F contains
182 * directory names, those are checked first. Next, os_get_config_dirs
183 * callback is used to get a list of directories to look into. In the
184 * first round, if ALLOW_PRIVATE, ltrace looks in user's private
185 * directories. If the config file wasn't found, the second round is
186 * made through system directories. In each directory, ltrace looks
187 * and reads the file named KEY.conf.
189 * If the config file still wasn't found, an empty (but non-NULL)
190 * protolib is provided instead. That is augmented with the following
194 * - The IMPORT argument passed to protolib_cache_init, if non-NULL
195 * - $HOME/.ltrace.conf if available
196 * - @sysconfdir@/ltrace.conf if available
197 * - Any configure _files_ passed in -F
199 * This function returns either the loaded protolib, or NULL when
200 * there was an error. */
201 struct protolib *protolib_cache_load(struct protolib_cache *cache,
202 const char *key, int own_key,
205 /* This is similar to protolib_cache_load, except that if a protolib
206 * is not found NULL is returned instead of a default module.
208 * It returns 0 for success and a negative value for failure, and the
209 * actual return value is passed via *RET.*/
210 int protolib_cache_maybe_load(struct protolib_cache *cache,
211 const char *key, int own_key,
213 struct protolib **ret);
215 /* This is similar to protolib_cache_load, but instead of looking for
216 * the file to load in directories, the filename is given. */
217 struct protolib *protolib_cache_file(struct protolib_cache *cache,
218 const char *filename, int own_filename);
220 /* This caches a default module. This is what protolib_cache_load
221 * calls if it fails to find the actual protolib. Returns default
222 * protolib or NULL if there was an error. */
223 struct protolib *protolib_cache_default(struct protolib_cache *cache,
224 const char *key, int own_key);
226 /* This is similar to protolib_cache_file, but the library to cache is
227 * given in argument. Returns 0 on success or a negative value on
228 * failure. PLIB is thereafter owned by CACHE. */
229 int protolib_cache_protolib(struct protolib_cache *cache,
230 const char *filename, int own_filename,
231 struct protolib *plib);
233 /* Single global prototype cache.
235 * XXX Eventually each ABI should have its own cache. The idea is
236 * that there's one per-ABI config file that all others use for
237 * elementary typedefs (long, char, size_t). Ltrace then only deals
238 * in fixed-width integral types (and pointers etc.). */
239 extern struct protolib_cache g_protocache;
241 void init_global_config(void);
243 #endif /* _PROTOTYPE_H_ */