1 /* 2 * This file is part of ltrace. 3 * Copyright (C) 2011,2012 Petr Machata, Red Hat Inc. 4 * 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. 9 * 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. 14 * 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 18 * 02110-1301 USA 19 */ 20 21 #ifndef PARAM_H 22 #define PARAM_H 23 24 #include "forward.h" 25 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: 29 * 30 * - simple types 31 * - parameter packs 32 * 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. */ 37 38 enum param_flavor { 39 PARAM_FLAVOR_TYPE, 40 PARAM_FLAVOR_PACK, 41 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" 45 * bunch. */ 46 PARAM_FLAVOR_STOP, 47 }; 48 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. */ 55 PARAM_PACK_ARGS, 56 57 /* This parameter pack represents a vararg argument. */ 58 PARAM_PACK_VARARGS, 59 }; 60 61 enum param_status { 62 PPCB_ERR = -1, /* An error occurred. */ 63 PPCB_STOP, /* Stop fetching the arguments. */ 64 PPCB_CONT, /* Display this argument and keep going. */ 65 }; 66 67 /* Each parameter enumerator defines its own context object. 68 * Definitions of these are in respective .c files of each 69 * enumerator. */ 70 struct param_enum; 71 72 struct param { 73 enum param_flavor flavor; 74 union { 75 struct { 76 struct arg_type_info *type; 77 int own_type; 78 } type; 79 struct { 80 struct expr_node *args; 81 size_t nargs; 82 int own_args; 83 enum param_pack_flavor ppflavor; 84 85 struct param_enum *(*init)(struct value *cb_args, 86 size_t nargs, 87 struct value_dict *arguments); 88 int (*next)(struct param_enum *self, 89 struct arg_type_info *info, 90 int *insert_stop); 91 enum param_status (*stop)(struct param_enum *self, 92 struct value *value); 93 void (*done)(struct param_enum *self); 94 } pack; 95 } u; 96 }; 97 98 /* Initialize simple type parameter. TYPE is owned and released by 99 * PARAM if OWN_TYPE. */ 100 void param_init_type(struct param *param, 101 struct arg_type_info *type, int own_type); 102 103 /* Initialize a stop. */ 104 void param_init_stop(struct param *param); 105 106 /* Initialize parameter pack PARAM. ARGS is an array of expressions 107 * with parameters. ARGS is owned and released by the pack if 108 * OWN_ARGS. NARGS is number of ARGS. 109 * 110 * When the parameter pack should be expanded, those expressions are 111 * evaluated and passed to the INIT callback. This has to return a 112 * non-NULL context object. 113 * 114 * The NEXT callback is then called repeatedly, and should initialize 115 * its INFOP argument to a type of the next parameter in the pack. 116 * When there are no more parameters in the pack, the NEXT callback 117 * will set INFOP to a VOID parameter. If the callback sets 118 * INSERT_STOP to a non-zero value, a stop parameter shall be inserted 119 * before this actual parameter. 120 * 121 * Core then uses the passed-in type to fetch the next argument, which 122 * is in turn passed to STOP callback. This callback then tells 123 * ltrace core what to do next: whether there are more arguments, and 124 * if not, whether this argument should be displayed. 125 * 126 * After the enumeration is ended, DONE callback is called. */ 127 void param_init_pack(struct param *param, enum param_pack_flavor ppflavor, 128 struct expr_node *args, size_t nargs, int own_args, 129 struct param_enum *(*init)(struct value *cb_args, 130 size_t nargs, 131 struct value_dict *arguments), 132 int (*next)(struct param_enum *self, 133 struct arg_type_info *infop, 134 int *insert_stop), 135 enum param_status (*stop)(struct param_enum *self, 136 struct value *value), 137 void (*done)(struct param_enum *self)); 138 139 /* Start enumerating types in parameter pack. This evaluates the 140 * parameter the pack arguments and calls the init callback. See the 141 * documentation of param_init_pack for details. */ 142 struct param_enum *param_pack_init(struct param *param, 143 struct value_dict *fargs); 144 145 /* Ask for next type in enumeration. See the documentation of 146 * param_init_pack for details. */ 147 int param_pack_next(struct param *param, struct param_enum *self, 148 struct arg_type_info *infop, int *insert_stop); 149 150 /* Ask whether we should stop enumerating. See the documentation of 151 * param_init_pack for details. */ 152 enum param_status param_pack_stop(struct param *param, 153 struct param_enum *self, struct value *value); 154 155 /* Finish enumerating types in parameter pack. See the documentation 156 * of param_init_pack for details. */ 157 void param_pack_done(struct param *param, struct param_enum *self); 158 159 /* Destroy data held by PARAM, but not the PARAM pointer itself. */ 160 void param_destroy(struct param *param); 161 162 #endif /* PARAM_H */ 163