---
name: "unw_reg_states_iterate"
section: "3"
platform: "linux"
package: "libunwind"
version: "1.8.3-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/unw_reg_states_iterate"
---

# unw\_reg\_states\_iterate(3)

## NAME

unw\_reg\_states\_iterate -- get register state info on current procedure

## SYNOPSIS

\#include \<libunwind.h\>\

int unw\_reg\_states\_iterate(unw\_cursor\_t \*cp, unw\_reg\_states\_callbackcb, void \*token);\

## DESCRIPTION

The unw\_reg\_states\_iterate() routine provides  information about the procedure that created the stack frame  identified by argument cp. The cb argument is a pointer  to a function of type unw\_reg\_states\_callback which is used to  return the information. The function unw\_reg\_states\_callback has the  following definition:

int ( \*unw\_reg\_states\_callback)(void \*token, void \*reg\_states\_data, size\_t reg\_states\_data\_size, unw\_word\_t start\_ip, unw\_word\_t end\_ip);

The callback function may be invoked several times for each call of unw\_reg\_states\_iterate. Each call is associated with an instruction address range and a set of instructions on how to update register values when returning from the procedure in that address range. For each invocation, the arguments to the callback function are:

- void \* token

   The token value passed to unw\_reg\_states\_callback.\

- void \* reg\_states\_data

   A pointer to data about  updating register values. This data, or a copy of it, can be passed  to unw\_apply\_reg\_state.\

- int reg\_states\_data\_size

   The size of the register update data. \

- unw\_word\_t start\_ip

   The address of the first  instruction of the address range. \

- unw\_word\_t end\_ip

   The address of the first  instruction *beyond* the end of the address range. \

## RETURN VALUE

On successful completion, unw\_reg\_states\_iterate() returns  0. If the callback function returns a nonzero value, that indicates  failure and the function returns immediately. Otherwise the negative  value of one of the error codes below is returned.

## THREAD AND SIGNAL SAFETY

unw\_reg\_states\_iterate() is thread safe. If cursor cp is  in the local address space, this routine is also safe to use from a  signal handler.

## ERRORS

- UNW\_EUNSPEC

   An unspecified error occurred.

- UNW\_ENOINFO

   Libunwind was unable to locate  unwind-info for the procedure.

- UNW\_EBADVERSION

   The unwind-info for the procedure has  version or format that is not understood by libunwind.

In addition, unw\_reg\_states\_iterate() may return any error  returned by the access\_mem() call-back (see  unw\_create\_addr\_space(3libunwind)).

## SEE ALSO

libunwind(3libunwind), unw\_apply\_reg\_state(3libunwind)

## AUTHOR

David Mosberger-Tang\
 Email: **dmosberger@gmail.com**\
 WWW: **http://www.nongnu.org/libunwind/**.