4.1.7 Returning Data

A standard function must return its function value by one of the following mechanisms:

• Immediate value
  
  
• Reference
  
  
• Descriptor

These mechanisms are the only standard means available for returning function values, and they support the important language-independent data types. Functions that return values by any mechanism other than those specified here are nonstandard, language-specific functions.

Function Value Return by Immediate Value

This section describes the two types of immediate value function return.

Nonfloating Function Value Return by Immediate Value

A function value is returned by immediate value in register R0 only if the type of function value is one of the following:

• Nonfloating-point scalar data type with size known (at compile time) to be ≤≤ 64 bits
  
  
• Record with size known (at compile time) to be ≤≤ 64 bits
  
  
• Set, implemented as a bit vector, with size known (at compile time) to be ≤≤ 64 bits

No form of string or array may be returned by immediate value.

Two separate 32-bit entities cannot be returned in R0.

A function value <64 bits returned in R0 must have its unoccupied bits extended, as appropriate, to a full quadword, depending on the data type. (See Table 4-2, Unused Bits in Passed Data for more details.)

Floating Function Value Return by Immediate Value

A function value is returned by immediate value in register F0 if, and only if, it is a noncomplex single- or double-precision floating-point value (F,D,G,S,or T).

A function value is returned by immediate value in registers F0..F1 if, and only if, it is a complex single- or double-precision floating-point value (complex F,D,G,S,or T). The real part is in F0 and the imaginary part is in F1.

Function Value Return by Reference

A function value is returned by reference only if the function value satisfies both of the following criteria:

• Its size is known to both the calling procedure and the called procedure, but the value cannot be returned by immediate value (because the function value requires more than 64 bits, the data type is a string or an array type, and so on).
  
  
• It can be returned in a contiguous region of storage.

The actual-argument list and the formal-argument list are shifted to the right by one argument item. The new, first argument item is reserved for the address of the function value. The calling procedure must provide the required contiguous storage and pass the address of the storage as the first argument. This address must specify storage that is naturally aligned according to the data type of the function value. The called function must write the function value to the storage described by the first argument.

Function Value Return by Descriptor

A function value is returned by descriptor only if the function value satisfies all of the following criteria:

• It cannot be returned by immediate value (because the function value requires more than 64 bits, the data type is a string or an array type, and so on).
  
  
• Its size is not known to either the calling procedure or the called procedure.
  
  
• It can be returned in a contiguous region of storage.

Function results may not be returned by descriptor in a standard call.

Typically, the called routine creates the return object on its stack and leaves it there on return. This is referred to as the stack return mechanism. The exit code of the called routine does not restore SP to its value before the call (otherwise the return value would be left unprotected in memory below SP). The calling routine must be prepared for SP to have a different value after the call.