1.\"	$NetBSD: dwarf_def_macro.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_def_macro.3 2122 2011-11-09 15:35:14Z jkoshy
28.\"
29.Dd November 9, 2011
30.Os
31.Dt DWARF_DEF_MACRO 3
32.Sh NAME
33.Nm dwarf_def_macro
34.Nd add a macro definition to a DWARF producer instance
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft "int"
40.Fo dwarf_def_macro
41.Fa "Dwarf_P_Debug dbg"
42.Fa "Dwarf_Unsigned lineno"
43.Fa "char *name"
44.Fa "char *value"
45.Fa "Dwarf_Error *err"
46.Fc
47.Sh DESCRIPTION
48Function
49.Fn dwarf_def_macro
50adds a macro definition to a DWARF producer instance.
51.Pp
52Argument
53.Ar dbg
54should reference a DWARF producer instance allocated using
55.Xr dwarf_producer_init 3
56or
57.Xr dwarf_producer_init_b 3 .
58.Pp
59Argument
60.Ar lineno
61specifies the line number of the source line where the macro is
62defined.
63A line number of zero is used for macros that are defined
64before any source file is read.
65.Pp
66Argument
67.Ar name
68should point to a NUL-terminated string containing the name
69of the macro.
70For function-like macros this parameter should also include
71parentheses and parameter names if any.
72.Pp
73Argument
74.Ar value
75should point to a NUL-terminated string containing the value
76of the macro.
77If the macro doesn't have a value, argument
78.Ar value
79should be set to NULL.
80.Pp
81If argument
82.Ar err
83is not NULL, it will be used to store error information in case of an
84error.
85.Sh RETURN VALUES
86On success, function
87.Fn dwarf_def_macro
88returns
89.Dv DW_DLV_OK .
90In case of an error, function
91.Fn dwarf_def_macro
92returns
93.Dv DW_DLV_ERROR
94and sets the argument
95.Ar err .
96.Sh EXAMPLE
97To record the fact that a macro named
98.Dv _STDIO_H_
99was defined at line 20 of the current macro file, use:
100.Bd -literal -offset indent
101Dwarf_P_Debug dbg;
102Dwarf_Error de;
103
104/* ... Assume 'dbg' refers to a DWARF producer instance... */
105if (dwarf_def_macro(dbg, 20, "_STDIO_H_", NULL, &de) != DW_DLV_OK)
106	errx(EXIT_FAILURE, "dwarf_def_macro failed: %s",
107	    dwarf_errmsg(-1));
108.Ed
109.Sh ERRORS
110Function
111.Fn dwarf_def_macro
112can fail with:
113.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
114.It Bq Er DW_DLE_ARGUMENT
115Either arguments
116.Ar dbg
117or
118.Ar name
119was NULL.
120.It Bq Er DW_DLE_MEMORY
121An out of memory condition was encountered during the execution of the
122function.
123.El
124.Sh SEE ALSO
125.Xr dwarf 3 ,
126.Xr dwarf_end_macro_file 3 ,
127.Xr dwarf_producer_init 3 ,
128.Xr dwarf_producer_init_b 3 ,
129.Xr dwarf_start_macro_file 3 ,
130.Xr dwarf_undef_macro 3 ,
131.Xr dwarf_vendor_ext 3
132