1.\"	$NetBSD: dwarf_add_expr_gen.3,v 1.2 2014/03/09 16:58:03 christos Exp $
2.\"
3.\" Copyright (c) 2011 Kai Wang
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" Id: dwarf_add_expr_gen.3 2072 2011-10-27 03:26:49Z jkoshy
28.\"
29.Dd September 9, 2011
30.Os
31.Dt DWARF_ADD_EXPR_GEN 3
32.Sh NAME
33.Nm dwarf_add_expr_gen
34.Nd add an operator to a location expression descriptor
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft "Dwarf_Unsigned"
40.Fo dwarf_add_expr_gen
41.Fa "Dwarf_P_Expr expr"
42.Fa "Dwarf_Small opcode"
43.Fa "Dwarf_Unsigned val1"
44.Fa "Dwarf_Unsigned val2"
45.Fa "Dwarf_Error *err"
46.Fc
47.Sh DESCRIPTION
48Function
49.Fn dwarf_add_expr_gen
50adds a location expression operator to the location expression
51descriptor referenced by argument
52.Ar expr .
53.Pp
54Argument
55.Ar expr
56should reference a location expression descriptor allocated using
57the function
58.Xr dwarf_new_expr 3 .
59.Pp
60Argument
61.Ar opcode
62specifies the operation code of the location expression operator.
63Valid values for this argument are those denoted by the
64.Dv DW_OP_ Ns *
65constants defined in
66.In libdwarf.h .
67.Pp
68To generate a
69.Dv DW_OP_addr
70operation, application code should instead use
71.Xr dwarf_add_expr_addr_b 3 .
72.Pp
73Argument
74.Ar val1
75specifies the first operand of the location expression operator.
76.Pp
77Argument
78.Ar val2
79specifies the second operand of the location expression operator.
80.Pp
81If argument
82.Ar err
83is not NULL, it will be used to store error information in case
84of an error.
85.Sh RETURN VALUES
86On success, function
87.Fn dwarf_add_expr_gen
88returns the size in bytes of the location expression byte stream
89generated.
90In case of an error, function
91.Fn dwarf_add_expr_gen
92returns
93.Dv DW_DLV_NOCOUNT
94and sets the argument
95.Ar err .
96.Sh ERRORS
97Function
98.Fn dwarf_add_expr_gen
99can fail with:
100.Bl -tag -width ".Bq Er DW_DLE_LOC_EXPR_BAD"
101.It Bq Er DW_DLE_ARGUMENT
102Argument
103.Ar expr
104was NULL.
105.It Bq Er DW_DLE_LOC_EXPR_BAD
106The operation code specified in argument
107.Ar opcode
108was invalid.
109.It Bq Er DW_DLE_MEMORY
110An out of memory condition was encountered during the execution of
111the function.
112.El
113.Sh SEE ALSO
114.Xr dwarf 3 ,
115.Xr dwarf_add_AT_location_expr 3 ,
116.Xr dwarf_add_expr_addr 3 ,
117.Xr dwarf_add_expr_addr_b 3 ,
118.Xr dwarf_expr_current_offset 3 ,
119.Xr dwarf_expr_into_block 3 ,
120.Xr dwarf_new_expr 3
121