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

FreeBSD Manual Pages

  
 
  

home | help
UNW_CR...R_SPACE(3libunwind) Programming Library  UNW_CR...R_SPACE(3libunwind)

NAME
       unw_create_addr_space --	create address space for remote	unwinding

SYNOPSIS
       #include	<libunwind.h>

       unw_addr_space_t	 unw_create_addr_space(unw_accessors_t	*ap, int byte-
       order);

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  de-
       scribed	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 <endian.h>.  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_acces-
       sors_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	 iden-
       tifier  (as)  and the last argument is an arbitrary, application	speci-
       fied void pointer (arg).	 When invoking a callback  routine,  libunwind
       sets  the  as argument to the address space on whose behalf the invoca-
       tion 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 fol-
       lows 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  informa-
       tion  need  to unwind a particular procedure. The ip argument is	an in-
       struction 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  ad-
       dressed	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 re-
       sources	(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 li-
       bunwind 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 argu-
       ment is a pointer to a variable of type unw_word_t which	is used	to re-
       turn 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 be-
       tween 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,	libun-
       wind sets argument write	to zero	and valp to point to the word that re-
       ceives 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  rou-
       tine to convert between the target's and	the host's byte	order, if nec-
       essary.

       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 argu-
       ment  write  to	zero  and  fpvalp  to  point  to  a  variable  of type
       unw_fpreg_t that	receives the read value. To write a  register,	libun-
       wind 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 tar-
       get address space. Argument cp is the unwind cursor that	identifies the
       stack frame in which execution should resume. By	the time libunwind in-
       vokes  the  resume callback, it has already established the desired ma-
       chine 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_re-
       sume(3libunwind), so applications which never invoke unw_resume(3libun-
       wind) need not define the resume	callback.

       On successful completion, the resume() callback must return zero.  Oth-
       erwise, 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 ad-
       dress 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  ob-
       tained.	The  bufp  argument is a pointer to a character	buffer used to
       return the procedure name. The size of this buffer is specified in  ar-
       gument  buf_len.	 The returned name must	be terminated by a NUL charac-
       ter. 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 sig-
       nal handler.

SEE ALSO
       _U_dyn_register(3libunwind),	  libunwind(3libunwind),       unw_de-
       stroy_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/.

Programming Library		29 August 2023	  UNW_CR...R_SPACE(3libunwind)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=unw_create_addr_space&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help