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

FreeBSD Manual Pages

  
 
  

home | help
DWARF_LOCLIST(3)       FreeBSD Library Functions Manual	      DWARF_LOCLIST(3)

NAME
     dwarf_loclist, dwarf_loclist_n -- retrieve	DWARF location expression in-
     formation

LIBRARY
     DWARF Access Library (libdwarf, -ldwarf)

SYNOPSIS
     #include <libdwarf.h>

     int
     dwarf_loclist(Dwarf_Attribute at, Dwarf_Locdesc **llbuf,
	 Dwarf_Signed *listlen,	Dwarf_Error *error);

     int
     dwarf_loclist_n(Dwarf_Attribute at, Dwarf_Locdesc ***llbuf,
	 Dwarf_Signed *listlen,	Dwarf_Error *error);

DESCRIPTION
     These functions retrieve the location expressions associated with a DWARF
     attribute.

     Note: function dwarf_loclist() is deprecated.  New	application code
     should instead use	function dwarf_loclist_n()

     Function dwarf_loclist_n()	retrieves the list of location expressions as-
     sociated with a DWARF attribute.  Argument	at should reference a valid
     DWARF attribute.  Argument	llbuf should point to a	location which will
     hold a returned array of pointers to Dwarf_Locdesc	descriptors.  Argument
     listlen should point to a location	which will be set to the number	of el-
     ements contained in the returned array.  If argument err is not NULL, it
     will be used to store error information in	case of	an error.

     Function dwarf_loclist() retrieves	the first location expression associ-
     ated with an attribute.  Argument at should reference a valid DWARF at-
     tribute.  Argument	llbuf should point to a	location which will hold the
     returned pointer to a Dwarf_Locdesc descriptor.  Argument listlen should
     point to a	location which will be always set to 1.	 If argument err is
     not NULL, it will be used to store	error information in case of an	error.

     Dwarf_Locdesc descriptors are defined in the header file <libdwarf.h>,
     and consist of following fields:

     ld_lopc   The lowest program counter address covered by the descriptor.
	       This field will be set to 0 if the descriptor is	not associated
	       with an address range.
     ld_hipc   The highest program counter address covered by the descriptor.
	       This field will be set to 0 if the descriptor is	not associated
	       with an address range.
     ld_cents  The number of entries returned in ld_s field.
     ld_s      Pointer to an array of Dwarf_Loc	descriptors.

     Each Dwarf_Loc descriptor represents one operation	of a location expres-
     sion.  These descriptors are defined in the header	file <libdwarf.h>, and
     consist of	following fields:

     lr_atom	 The operator name, one	of the DW_OP_* constants defined in
		 the header file <dwarf.h>.
     lr_number	 The first operand of this operation.
     lr_number2	 The second operand of this operation.
     lr_offset	 The byte offset of this operation within the containing loca-
		 tion expression.

   Memory Management
     The memory	area used for the descriptor array returned in argument	llbuf
     is	allocated by the DWARF Access Library (libdwarf, -ldwarf).  When the
     descriptor	array is no longer needed, application code should use func-
     tion dwarf_dealloc(3) to free the memory area in the following manner:

     1.	  First, the ld_s field	of each	Dwarf_Locdesc descriptor should	be de-
	  allocated using the allocation type DW_DLA_LOC_BLOCK.

     2.	  Then,	the application	should free each Dwarf_Locdesc descriptor us-
	  ing the allocation type DW_DLA_LOCDESC.

     3.	  Finally, the llbuf pointer should be deallocated using the alloca-
	  tion type DW_DLA_LIST.

RETURN VALUES
     On	success, these functions returns DW_DLV_OK.  In	case of	an error, they
     return DW_DLV_ERROR and set the argument err.

EXAMPLES
     To	retrieve the location list associated with an attribute, use:

	   Dwarf_Attribute at;
	   Dwarf_Locdesc **llbuf;
	   Dwarf_Signed	lcnt;
	   Dwarf_Loc *lr;
	   Dwarf_Error de;
	   int i;

	   if (dwarf_loclist_n(at, &llbuf, &lcnt, &de) != DW_DLV_OK)
		   errx(EXIT_FAILURE, "dwarf_loclist_n failed: %s",
		       dwarf_errmsg(de));

	   for (i = 0; i < lcnt; i++) {
		   /* ... Use llbuf[i] ... */
		   for (j = 0; (Dwarf_Half) j <	llbuf[i]->ld_cents; j++) {
			   lr =	&llbuf[i]->ld_s[j];
			   /* ... Use each Dwarf_Loc descriptor	... */
		   }
		   dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK);
		   dwarf_dealloc(dbg, llbuf[i],	DW_DLA_LOCDESC);
	   }
	   dwarf_dealloc(dbg, llbuf, DW_DLA_LIST);

ERRORS
     These functions can fail with:

     [DW_DLE_ARGUMENT]	One of the arguments at, llbuf or listlen was NULL.

     [DW_DLE_ARGUMENT]	The attribute provided by argument at does not contain
			a location expression or is not	associated with	a lo-
			cation expression list.

SEE ALSO
     dwarf(3), dwarf_dealloc(3), dwarf_get_loclist_entry(3),
     dwarf_loclist_from_expr(3), dwarf_loclist_from_expr_a(3)

FreeBSD	13.0		       November	9, 2011			  FreeBSD 13.0

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

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

home | help