Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DWARF_GET_MACRO_DETAI... BSD Library Functions Manual DWARF_GET_MACRO_DETAI...

NAME
     dwarf_get_macro_details --	retrieve macro information

LIBRARY
     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS
     #include <libdwarf.h>

     int
     dwarf_get_macro_details(Dwarf_Debug dbg, Dwarf_Off	offset,
	 Dwarf_Unsigned	max_count, Dwarf_Signed	*entry_cnt,
	 Dwarf_Macro_Details **details,	Dwarf_Error *err);

DESCRIPTION
     Function dwarf_get_macro_details()	retrieves information about macros as-
     sociated with a DWARF debug context.  Information about macro entries are
     returned as an array of descriptors of type Dwarf_Macro_Details, with
     each Dwarf_Macro_Details descriptor describing one	macro information en-
     try.

     Argument dbg should reference a DWARF debug context allocated using
     dwarf_init(3).  Argument offset is	an offset, relative to the
     ".debug_macinfo" section, to the start of the desired macro information.
     Argument max_count	specifies the maximum number of	macro information en-
     tries to be returned, or 0	if all entries are to be returned.  Argument
     entry_cnt should point to a location that will be set to the number of
     entries actually returned.	 Argument details should point to a location
     that will be set to a pointer to an array of Dwarf_Macro_Details descrip-
     tors.  If argument	err is not NULL, it will be used to store error	infor-
     mation in case of an error.

     Dwarf_Macro_Details descriptors are defined in the	header file
     <libdwarf.h>, and consist of the following	fields:
     dmd_offset	    The	section-relative offset	within the ".debug_macinfo"
		    section of the macro information entry being described.
     dmd_type	    The	type code of this macro	information entry; one of the
		    DW_MACINFO_* constants defined by the DWARF	specification.
     dmd_lineno	    The	line number associated with the	macro information en-
		    try, or 0 if there is no applicable	line number.
     dmd_fileindex  The	source file index for the macro	information entry.
		    This field is only meaningful when dmd_type	field is set
		    to DW_MACINFO_start_file.
     dmd_macro	    The	contents of this field is a pointer to a NUL-termi-
		    nated string whose meaning depends on the value of the
		    dmd_type field:
		    DW_MACINFO_define	   The returned	string contains	the
					   macro name and value.
		    DW_MACINFO_undef	   The string holds the	macro name.
		    DW_MACINFO_vendor_ext  The dmd_macro field points to a
					   vendor defined string.
		    The	field is NULL for other	values of dmd_type.

   Memory Management
     The memory	area used for the array	of Dwarf_Macro_Details descriptors re-
     turned in argument	details	is owned by the	DWARF Access Library
     (libdwarf,	-ldwarf).  The application should not attempt to directly free
     this pointer.  Portable code should instead use dwarf_dealloc() with the
     allocation	type DW_DLA_STRING to indicate that the	memory may be freed.

RETURN VALUES
     Function dwarf_get_macro_details()	returns	DW_DLV_OK when it succeeds.
     It	returns	DW_DLV_NO_ENTRY	if there is no more macro information at the
     specified offset offset.  In case of an error, it returns DW_DLV_ERROR
     and sets the argument err.

ERRORS
     Function dwarf_get_macro_details()	can fail with:

     [DW_DLE_ARGUMENT]	One of the arguments dbg, entry_cnt or details was
			NULL.

     [DW_DLE_NO_ENTRY]	There is no more macro information at the specified
			offset offset.

EXAMPLE
     To	loop through all the macro information entries associated with a DWARF
     debug context:

	   Dwarf_Debug dbg;
	   Dwarf_Unsigned offset;
	   Dwarf_Signed	cnt;
	   Dwarf_Macro_Details *md;
	   Dwarf_Error de;

	   offset = 0;
	   while (dwarf_get_macro_details(dbg, offset, 0,
	       &cnt, &md, &de) == DW_DLV_OK) {
		   for (i = 0; i < cnt;	i++) {
			   /* Access fields of md[i] ... */
		   }
		   offset = md[cnt - 1].dmd_offset + 1;
	   }

SEE ALSO
     dwarf(3), dwarf_dealloc(3), dwarf_find_macro_value_start(3),
     dwarf_init(3)

BSD				March 20, 2011				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dwarf_get_macro_details&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help