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

FreeBSD Manual Pages

  
 
  

home | help
UNW_CREATE_ADDR_SPACE(3)     Programming Library      UNW_CREATE_ADDR_SPACE(3)

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 call-back routines passed via	the ap
       pointer and the specified byteorder.  The call-back  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, __LITTLE_ENDIAN would request  little-endian  byte-order
       and  __BIG_ENDIAN would request big-endian byte-order. Whether or not a
       particular byte-order is	supported depends on the target	platform.

CALL-BACK ROUTINES
       Libunwind uses a	set of call-back 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 call-back routine is	an address-space iden-
       tifier (as) and the last	argument is an	arbitrary,  application-speci-
       fied  void-pointer (arg).  When invoking	a call-back 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(3) was called.

       The synopsis and	a detailed description of every	call-back routine fol-
       lows below.

   CALL-BACK 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() call-back	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(3) for	details. Argument need_unwind_info is zero  if
       the call-back does not need to provide values for the following members
       in the unw_proc_info_t structure:  format,  unwind_info_size,  and  un-
       wind_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	call-back (see below).

       On successful completion, the find_proc_info()  call-back  must	return
       zero.  Otherwise,  the  negative	 value	of  one	of the unw_error_t er-
       ror-codes may be	returned. In particular,  this	call-back  may	return
       -UNW_ESTOPUNWIND	to signal the end of the frame-chain.

   PUT_UNWIND_INFO
       Libunwind  invokes  the	put_unwind_info() call-back 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() call-back 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(3)).  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 un-
       wind-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 ad-
       dress-space. The	cache can be cleared with a call to unw_flush_cache().

       On successful completion, the get_dyn_info_list_addr()  call-back  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() call-back 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 call-back	routine	to convert be-
       tween the target's and the host's byte-order, if	necessary.

       On  successful completion, the access_mem() call-back 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() call-back 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	call-back rou-
       tine to convert between the target's and	the host's byte-order, if nec-
       essary.

       On  successful completion, the access_reg() call-back 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() call-back 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 call-back	routine	to convert be-
       tween the target's and the host's byte-order, if	necessary.

       On  successful  completion,  the	 access_fpreg()	 call-back must	return
       zero. Otherwise,	the negative value  of	one  of	 the  unw_error_t  er-
       ror-codes may be	returned.

   RESUME
       Libunwind  invokes  the	resume()  call-back 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 call-back, it	has already  established  the  desired
       machine-	 and memory-state via calls to the access_reg(), access_fpreg,
       and access_mem()	call-backs. Thus, all the call-back  needs  to	do  is
       perform whatever	action is needed to actually resume execution.

       The  resume  call-back is invoked only in response to a call to unw_re-
       sume(3),	so applications	which never invoke unw_resume(3) need not  de-
       fine the	resume callback.

       On successful completion, the resume() call-back	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	call-back will not return on success.

   GET_PROC_NAME
       Libunwind invokes the get_proc_name() call-back to  obtain  the	proce-
       dure-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  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()  call-back  must	return
       zero.  Otherwise,  the  negative	 value	of  one	of the unw_error_t er-
       ror-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(3),	 libunwind(3),	    unw_destroy_addr_space(3),
       unw_get_proc_info(3), unw_init_remote(3), unw_resume(3)

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

Programming Library		16 August 2007	      UNW_CREATE_ADDR_SPACE(3)

NAME | SYNOPSIS | DESCRIPTION | CALL-BACK ROUTINES | RETURN VALUE | THREAD AND SIGNAL SAFETY | SEE ALSO | AUTHOR

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

home | help