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