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

FreeBSD Manual Pages

  
 
  

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

NAME
       unw_resume -- resume execution in a particular stack frame

SYNOPSIS
       #include	<libunwind.h>

       int unw_resume(unw_cursor_t *cp);

DESCRIPTION
       The  unw_resume()  routine resumes execution at the stack frame identi-
       fied by cp.  The	behavior of this routine differs  slightly  for	 local
       and remote unwinding.

       For  local  unwinding, unw_resume() restores the	machine	state and then
       directly	resumes	execution in the target	stack frame. Thus unw_resume()
       does  not return	in this	case. Restoring	the machine state normally in-
       volves restoring	the ``preserved'' (callee-saved)  registers.  However,
       if  execution  in  any of the stack frames younger (more	deeply nested)
       than the	one identified by cp was interrupted by	a signal, then unw_re-
       sume()  will restore all	registers as well as the signal	mask. Attempt-
       ing to call unw_resume()	on a cursor which identifies the  stack	 frame
       of  another thread results in undefined behavior	(e.g., the program may
       crash).

       For remote unwinding, unw_resume() installs the machine	state  identi-
       fied  by	the cursor by calling the access_reg and access_fpreg accessor
       callbacks as needed. Once that is  accomplished,	 the  resume  accessor
       callback	is invoked. The	unw_resume routine then	returns	normally (that
       is, unlikely for	local unwinding, unw_resume will always	return for re-
       mote unwinding).

       Most  platforms	reserve	 some registers	to pass	arguments to exception
       handlers	(e.g., IA-64 uses r15-r18 for this purpose).  These  registers
       are  normally treated like ``scratch'' registers. However, if libunwind
       is used to set an exception argument register  to  a  particular	 value
       (e.g., via unw_set_reg()), then unw_resume() will install this value as
       the contents of the register. In	other words,  the  exception  handling
       arguments  are  installed  even in cases	where normally only the	``pre-
       served''	registers are restored.

       Note that unw_resume() does not invoke any unwind handlers (aka,	``per-
       sonality	routines''). If	a program needs	this, it will have to do so on
       its own by obtaining the	unw_proc_info_t	of each	unwound	frame and  ap-
       propriately  processing	its  unwind handler and	language-specific data
       area (lsda). These steps	are generally dependent	on the target-platform
       and are regulated by the	processor-specific ABI (application-binary in-
       terface).

RETURN VALUE
       For local unwinding, unw_resume() does not return on success.  For  re-
       mote unwinding, it returns 0 on success.	On failure, the	negative value
       of one of the errors below is returned.

THREAD AND SIGNAL SAFETY
       unw_resume()  is	 thread-safe.  If  cursor  cp  is  in  the  local  ad-
       dress-space, this routine is also safe to use from a signal handler.

ERRORS
       UNW_EUNSPEC
	       An unspecified error occurred.

       UNW_EBADREG
	       A register needed by unw_resume() wasn't	accessible.

       UNW_EINVALIDIP
	       The instruction pointer identified by cp	is not valid.

       UNW_BADFRAME
	       The stack frame identified by cp	is not valid.

SEE ALSO
       libunwind(3), unw_set_reg(3), sigprocmask(2)

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

Programming Library		16 August 2007			 UNW_RESUME(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | THREAD AND SIGNAL SAFETY | ERRORS | SEE ALSO | AUTHOR

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

home | help