2 * This file is part of ltrace.
3 * Copyright (C) 2011,2012 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
26 /* The structure param holds information about a parameter of a
27 * function. It's used to configure a function prototype. There are
28 * two flavors of parameters:
33 * Parameter packs are used to describe various vararg constructs.
34 * They themselves are parametrized by ltrace expressions. Those will
35 * typically be references to other arguments, but constants might
36 * also make sense, and it principle, anything can be used. */
42 /* This is for emitting arguments in two bunches. This is
43 * where we should stop emitting "left" bunch. All that's
44 * after this parameter should be emitted in the "right"
49 enum param_pack_flavor {
50 /* This parameter pack expands to a list of ordinary
51 * arguments. For example if the last argument is sometimes
52 * ignored, that would be described by a PARAM_PACK_ARGS
53 * parameter pack. ioctl or ptrace are two examples that
54 * would benefit from this. */
57 /* This parameter pack represents a vararg argument. */
62 PPCB_ERR = -1, /* An error occurred. */
63 PPCB_STOP, /* Stop fetching the arguments. */
64 PPCB_CONT, /* Display this argument and keep going. */
67 /* Each parameter enumerator defines its own context object.
68 * Definitions of these are in respective .c files of each
72 /* int printf(string, pack(format, arg1)); */
74 enum param_flavor flavor;
77 struct arg_type_info *type;
81 struct expr_node *args;
84 enum param_pack_flavor ppflavor;
86 struct param_enum *(*init)(struct value *cb_args,
88 struct value_dict *arguments);
89 int (*next)(struct param_enum *self,
90 struct arg_type_info *info,
92 enum param_status (*stop)(struct param_enum *self,
94 void (*done)(struct param_enum *self);
99 /* Initialize simple type parameter. TYPE is owned and released by
100 * PARAM if OWN_TYPE. */
101 void param_init_type(struct param *param,
102 struct arg_type_info *type, int own_type);
104 /* Initialize a stop. */
105 void param_init_stop(struct param *param);
107 /* Initialize parameter pack PARAM. ARGS is an array of expressions
108 * with parameters. ARGS is owned and released by the pack if
109 * OWN_ARGS. NARGS is number of ARGS.
111 * When the parameter pack should be expanded, those expressions are
112 * evaluated and passed to the INIT callback. This has to return a
113 * non-NULL context object.
115 * The NEXT callback is then called repeatedly, and should initialize
116 * its INFOP argument to a type of the next parameter in the pack.
117 * When there are no more parameters in the pack, the NEXT callback
118 * will set INFOP to a VOID parameter. If the callback sets
119 * INSERT_STOP to a non-zero value, a stop parameter shall be inserted
120 * before this actual parameter.
122 * Core then uses the passed-in type to fetch the next argument, which
123 * is in turn passed to STOP callback. This callback then tells
124 * ltrace core what to do next: whether there are more arguments, and
125 * if not, whether this argument should be displayed.
127 * After the enumeration is ended, DONE callback is called. */
128 void param_init_pack(struct param *param, enum param_pack_flavor ppflavor,
129 struct expr_node *args, size_t nargs, int own_args,
130 struct param_enum *(*init)(struct value *cb_args,
132 struct value_dict *arguments),
133 int (*next)(struct param_enum *self,
134 struct arg_type_info *infop,
136 enum param_status (*stop)(struct param_enum *self,
137 struct value *value),
138 void (*done)(struct param_enum *self));
140 /* Start enumerating types in parameter pack. This evaluates the
141 * parameter the pack arguments and calls the init callback. See the
142 * documentation of param_init_pack for details. */
143 struct param_enum *param_pack_init(struct param *param,
144 struct value_dict *fargs);
146 /* Ask for next type in enumeration. See the documentation of
147 * param_init_pack for details. */
148 int param_pack_next(struct param *param, struct param_enum *self,
149 struct arg_type_info *infop, int *insert_stop);
151 /* Ask whether we should stop enumerating. See the documentation of
152 * param_init_pack for details. */
153 enum param_status param_pack_stop(struct param *param,
154 struct param_enum *self, struct value *value);
156 /* Finish enumerating types in parameter pack. See the documentation
157 * of param_init_pack for details. */
158 void param_pack_done(struct param *param, struct param_enum *self);
160 /* Destroy data held by PARAM, but not the PARAM pointer itself. */
161 void param_destroy(struct param *param);