From e5419804c42acf3b4c85130b48b935db03d29e90 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Mon, 1 May 2000 16:12:01 +0000 Subject: [PATCH] * gdbint.texinfo (RETURN_VALUE_ON_STACK): Document. --- gdb/doc/gdbint.texinfo | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 2b844d23b35..439eaeaec72 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -1875,6 +1875,43 @@ Convert the value of register @var{reg} from its virtual form to its raw form. @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. +@item RETURN_VALUE_ON_STACK(@var{type}) +@findex RETURN_VALUE_ON_STACK +@cindex returning structures by value +@cindex structures, returning by value + +Return non-zero if values of type TYPE are returned on the stack, using +the ``struct convention'' (i.e., the caller provides a pointer to a +buffer in which the callee should store the return value). This +controls how the @samp{finish} command finds a function's return value, +and whether an inferior function call reserves space on the stack for +the return value. + +The full logic @value{GDBN} uses here is kind of odd. +@itemize @bullet + +@item +If the type being returned by value is not a structure, union, or array, +and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN} +concludes the value is not returned using the struct convention. + +@item +Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below). +If that returns non-zero, @value{GDBN} assumes the struct convention is +in use. + +@end itemize + +In other words, to indicate that a given type is returned by value using +the struct convention, that type must be either a struct, union, array, +or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something +that @code{USE_STRUCT_CONVENTION} likes. + +Note that, in C and C++, arrays are never returned by value. In those +languages, these predicates will always see a pointer type, never an +array type. All the references above to arrays being returned by value +apply only to other languages. + @item SOFTWARE_SINGLE_STEP_P Define this as 1 if the target does not have a hardware single-step mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. -- 2.30.2