gcc: Return Address

1 
1 6.49 Getting the Return or Frame Address of a Function
1 ======================================================
1 
1 These functions may be used to get information about the callers of a
1 function.
1 
1  -- Built-in Function: void * __builtin_return_address (unsigned int
1           LEVEL)
1      This function returns the return address of the current function,
1      or of one of its callers.  The LEVEL argument is number of frames
1      to scan up the call stack.  A value of '0' yields the return
1      address of the current function, a value of '1' yields the return
1      address of the caller of the current function, and so forth.  When
1      inlining the expected behavior is that the function returns the
1      address of the function that is returned to.  To work around this
1      behavior use the 'noinline' function attribute.
1 
1      The LEVEL argument must be a constant integer.
1 
1      On some machines it may be impossible to determine the return
1      address of any function other than the current one; in such cases,
1      or when the top of the stack has been reached, this function
1      returns an unspecified value.  In addition,
1      '__builtin_frame_address' may be used to determine if the top of
1      the stack has been reached.
1 
1      Additional post-processing of the returned value may be needed, see
1      '__builtin_extract_return_addr'.
1 
1      The stored representation of the return address in memory may be
1      different from the address returned by '__builtin_return_address'.
1      For example, on AArch64 the stored address may be mangled with
1      return address signing whereas the address returned by
1      '__builtin_return_address' is not.
1 
1      Calling this function with a nonzero argument can have
1      unpredictable effects, including crashing the calling program.  As
1      a result, calls that are considered unsafe are diagnosed when the
1      '-Wframe-address' option is in effect.  Such calls should only be
1      made in debugging situations.
1 
1      On targets where code addresses are representable as 'void *',
1           void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
1      gives the code address where the current function would return.
1      For example, such an address may be used with 'dladdr' or other
1      interfaces that work with code addresses.
1 
1  -- Built-in Function: void * __builtin_extract_return_addr (void *ADDR)
1      The address as returned by '__builtin_return_address' may have to
1      be fed through this function to get the actual encoded address.
1      For example, on the 31-bit S/390 platform the highest bit has to be
1      masked out, or on SPARC platforms an offset has to be added for the
1      true next instruction to be executed.
1 
1      If no fixup is needed, this function simply passes through ADDR.
1 
1  -- Built-in Function: void * __builtin_frob_return_address (void *ADDR)
1      This function does the reverse of '__builtin_extract_return_addr'.
1 
1  -- Built-in Function: void * __builtin_frame_address (unsigned int
1           LEVEL)
1      This function is similar to '__builtin_return_address', but it
1      returns the address of the function frame rather than the return
1      address of the function.  Calling '__builtin_frame_address' with a
1      value of '0' yields the frame address of the current function, a
1      value of '1' yields the frame address of the caller of the current
1      function, and so forth.
1 
1      The frame is the area on the stack that holds local variables and
1      saved registers.  The frame address is normally the address of the
1      first word pushed on to the stack by the function.  However, the
1      exact definition depends upon the processor and the calling
1      convention.  If the processor has a dedicated frame pointer
1      register, and the function has a frame, then
1      '__builtin_frame_address' returns the value of the frame pointer
1      register.
1 
1      On some machines it may be impossible to determine the frame
1      address of any function other than the current one; in such cases,
1      or when the top of the stack has been reached, this function
1      returns '0' if the first frame pointer is properly initialized by
1      the startup code.
1 
1      Calling this function with a nonzero argument can have
1      unpredictable effects, including crashing the calling program.  As
1      a result, calls that are considered unsafe are diagnosed when the
1      '-Wframe-address' option is in effect.  Such calls should only be
1      made in debugging situations.
1