param.h

   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 /* int printf(string, pack(format, arg1)); */
  73 struct param {
  74         enum param_flavor flavor;
  75         union {
  76                 struct {
  77                         struct arg_type_info *type;
  78                         int own_type;
  79                 } type;
  80                 struct {
  81                         struct expr_node *args;
  82                         size_t nargs;
  83                         int own_args;
  84                         enum param_pack_flavor ppflavor;
  85
  86                         struct param_enum *(*init)(struct value *cb_args,
  87                                                    size_t nargs,
  88                                                    struct value_dict *arguments);
  89                         int (*next)(struct param_enum *self,
  90                                     struct arg_type_info *info,
  91                                     int *insert_stop);
  92                         enum param_status (*stop)(struct param_enum *self,
  93                                                   struct value *value);
  94                         void (*done)(struct param_enum *self);
  95                 } pack;
  96         } u;
  97 };
  98
  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);
 103
 104 /* Initialize a stop.  */
 105 void param_init_stop(struct param *param);
 106
 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.
 110  *
 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.
 114  *
 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.
 121  *
 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.
 126  *
 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,
 131                                                 size_t nargs,
 132                                                 struct value_dict *arguments),
 133                      int (*next)(struct param_enum *self,
 134                                  struct arg_type_info *infop,
 135                                  int *insert_stop),
 136                      enum param_status (*stop)(struct param_enum *self,
 137                                                struct value *value),
 138                      void (*done)(struct param_enum *self));
 139
 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);
 145
 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);
 150
 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);
 155
 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);
 159
 160 /* Destroy data held by PARAM, but not the PARAM pointer itself.  */
 161 void param_destroy(struct param *param);
 162
 163 #endif /* PARAM_H */