value.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 VALUE_H
  22 #define VALUE_H
  23
  24 #include "forward.h"
  25 #include "sysdep.h"
  26
  27 /* Values are objects that capture data fetched from an inferior.
  28  * Typically a value is attached to a single inferior where it was
  29  * extracted from, but it is possible to create a detached value.
  30  * Each value is typed.  Values support a number of routines, such as
  31  * dereferencing if the value is of pointer type, array or structure
  32  * access, etc.
  33  *
  34  * A value can be uninitialized, abstract or reified.  Abstract values
  35  * are just references into inferior, no transfer has taken place yet.
  36  * Reified values have been copied out of the corresponding inferior,
  37  * or otherwise set to some value.  */
  38
  39 enum value_location_t {
  40         VAL_LOC_NODATA = 0,     /* Uninitialized.  */
  41         VAL_LOC_INFERIOR,       /* Value is in the inferior process.  */
  42         VAL_LOC_COPY,           /* Value was copied out of the inferior.  */
  43         VAL_LOC_SHARED,         /* Like VAL_LOC_COPY, but don't free.  */
  44         VAL_LOC_WORD,           /* Like VAL_LOC_COPY, but small enough.  */
  45 };
  46
  47 struct value {
  48         struct arg_type_info *type;
  49         struct process *inferior;
  50         struct value *parent;
  51         size_t size;
  52         union {
  53                 void *address;  /* VAL_LOC_COPY, VAL_LOC_SHARED */
  54                 arch_addr_t inf_address;  /* VAL_LOC_INFERIOR */
  55                 long value;     /* VAL_LOC_WORD */
  56                 unsigned char buf[0];
  57         } u;
  58         enum value_location_t where;
  59         int own_type;
  60 };
  61
  62 /* Initialize VALUE.  INFERIOR must not be NULL.  PARENT is parental
  63  * value, in case of compound types.  It may be NULL.  TYPE is a type
  64  * of the value.  It may be NULL if the type is not yet known.  If
  65  * OWN_TYPE, the passed-in type is owned and released by value.  */
  66 void value_init(struct value *value, struct process *inferior,
  67                 struct value *parent, struct arg_type_info *type,
  68                 int own_type);
  69
  70 /* Initialize VALUE.  This is like value_init, except that inferior is
  71  * NULL.  VALP is initialized as a detached value, without assigned
  72  * process.  You have to be careful not to use VAL_LOC_INFERIOR
  73  * values if the value is detached.  */
  74 void value_init_detached(struct value *value, struct value *parent,
  75                          struct arg_type_info *type, int own_type);
  76
  77 /* Set TYPE.  This releases old type if it was owned.  TYPE is owned
  78  * and released if OWN_TYPE.  */
  79 void value_set_type(struct value *value,
  80                     struct arg_type_info *type, int own_type);
  81
  82 /* Transfers the ownership of VALUE's type, if any, to the caller.
  83  * This doesn't reset the VALUE's type, but gives up ownership if
  84  * there was one.  Previous ownership is passed in OWN_TYPE.  */
  85 void value_take_type(struct value *value,
  86                      struct arg_type_info **type, int *own_type);
  87
  88 /* Release the data held by VALP, if any, but not the type.  */
  89 void value_release(struct value *valp);
  90
  91 /* Value resides in inferior, on given ADDRESS.  */
  92 void value_in_inferior(struct value *valp, arch_addr_t address);
  93
  94 /* Destroy the value.  This is like value_release, but it additionally
  95  * frees the value type, if it's own_type.  It doesn't free the VAL
  96  * pointer itself.  */
  97 void value_destroy(struct value *val);
  98
  99 /* Set the data held by VALP to VALUE.  This also sets the value's
 100  * where to VAL_LOC_WORD.  */
 101 void value_set_word(struct value *valp, long value);
 102
 103 /* Set the data held by VALP to a buffer of size SIZE.  This buffer
 104  * may be allocated by malloc.  Returns NULL on failure.  */
 105 unsigned char *value_reserve(struct value *valp, size_t size);
 106
 107 /* Access ELEMENT-th field of the compound value VALP, and store the
 108  * result into the value RET_VAL.  Returns 0 on success, or negative
 109  * value on failure.  */
 110 int value_init_element(struct value *ret_val, struct value *valp, size_t element);
 111
 112 /* De-reference pointer value, and store the result into the value
 113  * RET_VAL.  Returns 0 on success, or negative value on failure.  */
 114 int value_init_deref(struct value *ret_val, struct value *valp);
 115
 116 /* If value is in inferior, copy it over to ltrace.  Return 0 for
 117  * success or negative value for failure.  */
 118 int value_reify(struct value *val, struct value_dict *arguments);
 119
 120 /* Return a pointer to the data of the value.  This copies the data
 121  * from the inferior to the tracer.  Returns NULL on failure.  */
 122 unsigned char *value_get_data(struct value *val, struct value_dict *arguments);
 123
 124 /* Return a pointer to the raw data of the value.  This shall not be
 125  * called on a VAL_LOC_INFERIOR value.  */
 126 unsigned char *value_get_raw_data(struct value *val);
 127
 128 /* Copy value VAL into the area pointed-to by RETP.  Return 0 on
 129  * success or a negative value on failure.  */
 130 int value_clone(struct value *retp, const struct value *val);
 131
 132 /* Give a size of given value.  Return (size_t)-1 for error.  This is
 133  * a full size of the value.  In particular for arrays, it returns
 134  * actual length of the array, as computed by the length
 135  * expression.  */
 136 size_t value_size(struct value *val, struct value_dict *arguments);
 137
 138 /* Extract at most word-sized datum from the value.  Return 0 on
 139  * success or negative value on failure.  */
 140 int value_extract_word(struct value *val, long *retp,
 141                        struct value_dict *arguments);
 142
 143 /* Copy contents of VAL to DATA.  The buffer must be large enough to
 144  * hold all the data inside.  */
 145 int value_extract_buf(struct value *val, unsigned char *data,
 146                       struct value_dict *arguments);
 147
 148 /* Find the most enclosing parental value that is a struct.  Return
 149  * NULL when there is no such parental value.  */
 150 struct value *value_get_parental_struct(struct value *val);
 151
 152 /* Determine whether this is all-zero value.  Returns >0 if it is, ==0
 153  * if it isn't, <0 on error.  */
 154 int value_is_zero(struct value *val, struct value_dict *arguments);
 155
 156 /* Compare two values for byte-by-byte equality.  Returns >0 if they
 157  * are equal, ==0 if they are not, and <0 on error.  */
 158 int value_equal(struct value *val1, struct value *val2,
 159                 struct value_dict *arguments);
 160
 161 /* Convert a structure type to pointer to that structure type.  */
 162 int value_pass_by_reference(struct value *value);
 163
 164 #endif /* VALUE_H */