---
name: "dwarf_loclist_n"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/dwarf_loclist"
---

# dwarf\_loclist\_n(3)

retrieve DWARF location expression information

Part of [dwarf\_loclist(3)](/dwarf_loclist/3.md).

## NAME

**dwarf\_loclist**, **dwarf\_loclist\_n** – retrieve DWARF location expression information

## LIBRARY

library “libdwarf”

## 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 associated 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 elements 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 associated with an attribute. Argument *at* should reference a valid DWARF attribute. 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 expression. 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 location expression.

### Memory Management

The memory area used for the descriptor array returned in argument *llbuf* is allocated by the library “libdwarf”. When the descriptor array is no longer needed, application code should use function [dwarf\_dealloc(3)](/dwarf_dealloc/3.md) to free the memory area in the following manner:

1. First, the *ld\_s* field of each *Dwarf\_Locdesc* descriptor should be deallocated using the allocation type DW\_DLA\_LOC\_BLOCK.

2. Then, the application should free each *Dwarf\_Locdesc* descriptor using the allocation type DW\_DLA\_LOCDESC.

3. Finally, the *llbuf* pointer should be deallocated using the allocation 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 location expression list.

## SEE ALSO

[dwarf(3)](/dwarf/3.md), [dwarf\_dealloc(3)](/dwarf_dealloc/3.md), [dwarf\_get\_loclist\_entry(3)](/dwarf_get_loclist_entry/3.md), [dwarf\_loclist\_from\_expr(3)](/dwarf_loclist_from_expr/3.md), [dwarf\_loclist\_from\_expr\_a(3)](/dwarf_loclist_from_expr_a/3.md)