--- name: "unw_create_addr_space" 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_create_addr_space" --- # unw\_create\_addr\_space(3) ## NAME unw\_create\_addr\_space -- create address space for remote unwinding ## SYNOPSIS \#include \\ unw\_addr\_space\_t unw\_create\_addr\_space(unw\_accessors\_t \*ap, int byteorder);\ ## DESCRIPTION The unw\_create\_addr\_space() routine creates a new unwind address space and initializes it based on the callback routines passed via the ap pointer and the specified byteorder. The callback routines are described in detail below. The byteorder can be set to 0 to request the default byte order of the unwind target. To request a particular byte order, byteorder can be set to any constant defined by \. In particular, UNW\_LITTLE\_ENDIAN would request little-endian byte order and UNW\_BIG\_ENDIAN would request big-endian byte order. Whether or not a particular byte order is supported depends on the target platform. ## CALLBACK ROUTINES Libunwind uses a set of callback routines to access the information it needs to unwind a chain of stack frames. These routines are specified via the ap argument, which points to a variable of type unw\_accessors\_t. The contents of this variable is copied into the newly created address space, so the variable must remain valid only for the duration of the call to unw\_create\_addr\_space(). The first argument to every callback routine is an address space identifier (as) and the last argument is an arbitrary, application specified void pointer (arg). When invoking a callback routine, libunwind sets the as argument to the address space on whose behalf the invocation is made and the arg argument to the value that was specified when unw\_init\_remote(3libunwind) was called. The synopsis and a detailed description of every callback routine follows below. ### CALLBACK ROUTINE SYNOPSIS int find\_proc\_info(unw\_addr\_space\_t as,\ unw\_word\_t ip, unw\_proc\_info\_t \*pip,\ int need\_unwind\_info, void \*arg);\ void put\_unwind\_info(unw\_addr\_space\_t as,\ unw\_proc\_info\_t \*pip, void \*arg);\ int get\_dyn\_info\_list\_addr(unw\_addr\_space\_t as,\ unw\_word\_t \*dilap, void \*arg);\ int access\_mem(unw\_addr\_space\_t as,\ unw\_word\_t addr, unw\_word\_t \*valp,\ int write, void \*arg);\ int access\_reg(unw\_addr\_space\_t as,\ unw\_regnum\_t regnum, unw\_word\_t \*valp,\ int write, void \*arg);\ int access\_fpreg(unw\_addr\_space\_t as,\ unw\_regnum\_t regnum, unw\_fpreg\_t \*fpvalp,\ int write, void \*arg);\ int resume(unw\_addr\_space\_t as,\ unw\_cursor\_t \*cp, void \*arg);\ int get\_proc\_name(unw\_addr\_space\_t as,\ unw\_word\_t addr, char \*bufp,\ size\_t buf\_len, unw\_word\_t \*offp,\ void \*arg);\ ### FIND\_PROC\_INFO Libunwind invokes the find\_proc\_info() callback to locate the information need to unwind a particular procedure. The ip argument is an instruction address inside the procedure whose information is needed. The pip argument is a pointer to the variable used to return the desired information. The type of this variable is unw\_proc\_info\_t. See unw\_get\_proc\_info(3libunwind) for details. Argument need\_unwind\_info is zero if the callback does not need to provide values for the following members in the unw\_proc\_info\_t structure: format, unwind\_info\_size, and unwind\_info. If need\_unwind\_info is non-zero, valid values need to be returned in these members. Furthermore, the contents of the memory addressed by the unwind\_info member must remain valid until the info is released via the put\_unwind\_info callback (see below). On successful completion, the find\_proc\_info() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. In particular, this callback may return -UNW\_ESTOPUNWIND to signal the end of the frame chain. ### PUT\_UNWIND\_INFO Libunwind invokes the put\_unwind\_info() callback to release the resources (such as memory) allocated by a previous call to find\_proc\_info() with the need\_unwind\_info argument set to a non-zero value. The pip argument has the same value as the argument of the same name in the previous matching call to find\_proc\_info(). Note that libunwind does *not* invoke put\_unwind\_info for calls to find\_proc\_info() with a zero need\_unwind\_info argument. ### GET\_DYN\_INFO\_LIST\_ADDR Libunwind invokes the get\_dyn\_info\_list\_addr() callback to obtain the address of the head of the dynamic unwind info registration list. The variable stored at the returned address must have a type of unw\_dyn\_info\_list\_t (see \_U\_dyn\_register(3libunwind)). The dliap argument is a pointer to a variable of type unw\_word\_t which is used to return the address of the dynamic unwind info registration list. If no dynamic unwind info registration list exist, the value pointed to by dliap must be cleared to zero. Libunwind will cache the value returned by get\_dyn\_info\_list\_addr() if caching is enabled for the given address space. The cache can be cleared with a call to unw\_flush\_cache(). On successful completion, the get\_dyn\_info\_list\_addr() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. ### ACCESS\_MEM Libunwind invokes the access\_mem() callback to read from or write to a word of memory in the target address space. The address of the word to be accessed is passed in argument addr. To read memory, libunwind sets argument write to zero and valp to point to the word that receives the read value. To write memory, libunwind sets argument write to a non-zero value and valp to point to the word that contains the value to be written. The word that valp points to is always in the byte order of the host platform, regardless of the byte order of the target. In other words, it is the responsibility of the callback routine to convert between the target's and the host's byte order, if necessary. On successful completion, the access\_mem() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. ### ACCESS\_REG Libunwind invokes the access\_reg() callback to read from or write to a scalar (non-floating-point) CPU register. The index of the register to be accessed is passed in argument regnum. To read a register, libunwind sets argument write to zero and valp to point to the word that receives the read value. To write a register, libunwind sets argument write to a non-zero value and valp to point to the word that contains the value to be written. The word that valp points to is always in the byte order of the host platform, regardless of the byte order of the target. In other words, it is the responsibility of the callback routine to convert between the target's and the host's byte order, if necessary. On successful completion, the access\_reg() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. ### ACCESS\_FPREG Libunwind invokes the access\_fpreg() callback to read from or write to a floating-point CPU register. The index of the register to be accessed is passed in argument regnum. To read a register, libunwind sets argument write to zero and fpvalp to point to a variable of type unw\_fpreg\_t that receives the read value. To write a register, libunwind sets argument write to a non-zero value and fpvalp to point to the variable of type unw\_fpreg\_t that contains the value to be written. The word that fpvalp points to is always in the byte order of the host platform, regardless of the byte order of the target. In other words, it is the responsibility of the callback routine to convert between the target's and the host's byte order, if necessary. On successful completion, the access\_fpreg() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. ### RESUME Libunwind invokes the resume() callback to resume execution in the target address space. Argument cp is the unwind cursor that identifies the stack frame in which execution should resume. By the time libunwind invokes the resume callback, it has already established the desired machine and memory state via calls to the access\_reg(), access\_fpreg, and access\_mem() callbacks. Thus, all the callback needs to do is perform whatever action is needed to actually resume execution. The resume callback is invoked only in response to a call to unw\_resume(3libunwind), so applications which never invoke unw\_resume(3libunwind) need not define the resume callback. On successful completion, the resume() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. As a special case, when resuming execution in the local address space, the callback will not return on success. ### GET\_PROC\_NAME Libunwind invokes the get\_proc\_name() callback to obtain the procedure name of a static (not dynamically generated) procedure. Argument addr is an instruction address within the procedure whose name is to be obtained. The bufp argument is a pointer to a character buffer used to return the procedure name. The size of this buffer is specified in argument buf\_len. The returned name must be terminated by a NUL character. If the procedure's name is longer than buf\_len bytes, it must be truncated to buf\_len-1 bytes, with the last byte in the buffer set to the NUL character and -UNW\_ENOMEM must be returned. Argument offp is a pointer to a word which is used to return the byte offset relative to the start of the procedure whose name is being returned. For example, if procedure foo() starts at address 0x40003000, then invoking get\_proc\_name() with addr set to 0x40003080 should return a value of 0x80 in the word pointed to by offp (assuming the procedure is at least 0x80 bytes long). On successful completion, the get\_proc\_name() callback must return zero. Otherwise, the negative value of one of the unw\_error\_t error codes may be returned. ## RETURN VALUE On successful completion, unw\_create\_addr\_space() returns a non-NULL value that represents the newly created address space. Otherwise, NULL is returned. ## THREAD AND SIGNAL SAFETY unw\_create\_addr\_space() is thread-safe but *not* safe to use from a signal handler. ## SEE ALSO \_U\_dyn\_register(3libunwind), libunwind(3libunwind), unw\_destroy\_addr\_space(3libunwind), unw\_get\_proc\_info(3libunwind), unw\_init\_remote(3libunwind), unw\_resume(3libunwind) ## AUTHOR David Mosberger-Tang\ Email: **dmosberger@gmail.com**\ WWW: **http://www.nongnu.org/libunwind/**.