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
39enum 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
47struct 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.  */
66void 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.  */
74void 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.  */
79void 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.  */
85void 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.  */
89void value_release(struct value *valp);
90
91/* Value resides in inferior, on given ADDRESS.  */
92void 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.  */
97void 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.  */
101void 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.  */
105unsigned 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.  */
110int 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.  */
114int 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.  */
118int 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.  */
122unsigned 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.  */
126unsigned 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.  */
130int 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.  */
136size_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.  */
140int 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.  */
145int 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.  */
150struct 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.  */
154int 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.  */
158int 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.  */
162int value_pass_by_reference(struct value *value);
163
164#endif /* VALUE_H */
165