2. Implementation Defined Attributes
Ada 95 defines (throughout the Ada 95 reference manual,
summarized in annex K),
a set of attributes that provide useful additional functionality in all
areas of the language. These language defined attributes are implemented
in GNAT and work as described in the Ada 95 Reference Manual.
In addition, Ada 95 allows implementations to define additional
attributes whose meaning is defined by the implementation. GNAT provides
a number of these implementation-dependent attributes which can be used
to extend and enhance the functionality of the compiler. This section of
the GNAT reference manual describes these additional attributes.
Note that any program using these attributes may not be portable to
other compilers (although GNAT implements this set of attributes on all
platforms). Therefore if portability to other compilers is an important
consideration, you should minimize the use of these attributes.
Abort_Signal
Standard'Abort_Signal (Standard is the only allowed
prefix) provides the entity for the special exception used to signal
task abort or asynchronous transfer of control. Normally this attribute
should only be used in the tasking runtime (it is highly peculiar, and
completely outside the normal semantics of Ada, for a user program to
intercept the abort exception).
Address_Size
Standard'Address_Size (Standard is the only allowed
prefix) is a static constant giving the number of bits in an
Address. It is the same value as System.Address'Size,
but has the advantage of being static, while a direct
reference to System.Address'Size is non-static because Address
is a private type.
Asm_Input
The Asm_Input attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
(e.g. what kind of register is required). The second argument is the
value to be used as the input argument. The possible values for the
constant are the same as those used in the RTL, and are dependent on
the configuration file used to built the GCC back end.
12.1 Machine Code Insertions
Asm_Output
The Asm_Output attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
constraint for the parameter (e.g. what kind of register is
required). The second argument is the variable to be updated with the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
either be omitted, or explicitly given as No_Output_Operands.
12.1 Machine Code Insertions
AST_Entry
This attribute is implemented only in OpenVMS versions of GNAT. Applied to
the name of an entry, it yields a value of the predefined type AST_Handler
(declared in the predefined package System, as extended by the use of
pragma Extend_System (Aux_DEC)). This value enables the given entry to
be called when an AST occurs. For further details, refer to the DEC Ada
Language Reference Manual, section 9.12a.
Bit
obj'Bit, where obj is any object, yields the bit
offset within the storage unit (byte) that contains the first bit of
storage allocated for the object. The value of this attribute is of the
type Universal_Integer, and is always a non-negative number not
exceeding the value of System.Storage_Unit.
For an object that is a variable or a constant allocated in a register,
the value is zero. (The use of this attribute does not force the
allocation of a variable to memory).
For an object that is a formal parameter, this attribute applies
to either the matching actual parameter or to a copy of the
matching actual parameter.
For an access object the value is zero. Note that
obj.all'Bit is subject to an Access_Check for the
designated object. Similarly for a record component
X.C'Bit is subject to a discriminant check and
X(I).Bit and X(I1..I2)'Bit
are subject to index checks.
This attribute is designed to be compatible with the DEC Ada 83 definition
and implementation of the Bit attribute.
Bit_Position
R.C'Bit, where R is a record object and C is one
of the fields of the record type, yields the bit
offset within the record contains the first bit of
storage allocated for the object. The value of this attribute is of the
type Universal_Integer. The value depends only on the field
C and is independent of the alignment of
the containing record R.
Code_Address
The 'Address
attribute may be applied to subprograms in Ada 95, but the
intended effect from the Ada 95 reference manual seems to be to provide
an address value which can be used to call the subprogram by means of
an address clause as in the following example:
| | procedure K is ...
procedure L;
for L'Address use K'Address;
pragma Import (Ada, L);
|
A call to L is then expected to result in a call to K.
In Ada 83, where there were no access-to-subprogram values, this was
a common work around for getting the effect of an indirect call.
GNAT implements the above use of Address and the technique
illustrated by the example code works correctly.
However, for some purposes, it is useful to have the address of the start
of the generated code for the subprogram. On some architectures, this is
not necessarily the same as the Address value described above.
For example, the Address value may reference a subprogram
descriptor rather than the subprogram itself.
The 'Code_Address attribute, which can only be applied to
subprogram entities, always returns the address of the start of the
generated code of the specified subprogram, which may or may not be
the same value as is returned by the corresponding 'Address
attribute.
Default_Bit_Order
Standard'Default_Bit_Order (Standard is the only
permissible prefix), provides the value System.Default_Bit_Order
as a Pos value (0 for High_Order_First, 1 for
Low_Order_First). This is used to construct the definition of
Default_Bit_Order in package System.
Elaborated
The prefix of the 'Elaborated attribute must be a unit name. The
value is a Boolean which indicates whether or not the given unit has been
elaborated. This attribute is primarily intended for internal use by the
generated code for dynamic elaboration checking, but it can also be used
in user programs. The value will always be True once elaboration of all
units has been completed. An exception is for units which need no
elaboration, the value is always False for such units.
Elab_Body
This attribute can only be applied to a program unit name. It returns
the entity for the corresponding elaboration procedure for elaborating
the body of the referenced unit. This is used in the main generated
elaboration procedure by the binder and is not normally used in any
other context. However, there may be specialized situations in which it
is useful to be able to call this elaboration procedure from Ada code,
e.g. if it is necessary to do selective re-elaboration to fix some
error.
Elab_Spec
This attribute can only be applied to a program unit name. It returns
the entity for the corresponding elaboration procedure for elaborating
the specification of the referenced unit. This is used in the main
generated elaboration procedure by the binder and is not normally used
in any other context. However, there may be specialized situations in
which it is useful to be able to call this elaboration procedure from
Ada code, e.g. if it is necessary to do selective re-elaboration to fix
some error.
Emax
The Emax attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Enum_Rep
For every enumeration subtype S, S'Enum_Rep denotes a
function with the following spec:
| | function S'Enum_Rep (Arg : S'Base)
return Universal_Integer;
|
It is also allowable to apply Enum_Rep directly to an object of an
enumeration type or to a non-overloaded enumeration
literal. In this case S'Enum_Rep is equivalent to
typ'Enum_Rep(S) where typ is the type of the
enumeration literal or object.
The function returns the representation value for the given enumeration
value. This will be equal to value of the Pos attribute in the
absence of an enumeration representation clause. This is a static
attribute (i.e. the result is static if the argument is static).
S'Enum_Rep can also be used with integer types and objects,
in which case it simply returns the integer value. The reason for this
is to allow it to be used for (<>) discrete formal arguments in
a generic unit that can be instantiated with either enumeration types
or integer types. Note that if Enum_Rep is used on a modular
type whose upper bound exceeds the upper bound of the largest signed
integer type, and the argument is a variable, so that the universal
integer calculation is done at run-time, then the call to Enum_Rep
may raise Constraint_Error.
Epsilon
The Epsilon attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Fixed_Value
For every fixed-point type S, S'Fixed_Value denotes a
function with the following specification:
| | function S'Fixed_Value (Arg : Universal_Integer)
return S;
|
The value returned is the fixed-point value V such that
The effect is thus similar to first converting the argument to the
integer type used to represent S, and then doing an unchecked
conversion to the fixed-point type. The difference is
that there are full range checks, to ensure that the result is in range.
This attribute is primarily intended for use in implementation of the
input-output functions for fixed-point values.
Has_Access_Values
The prefix of the Has_Access_Values attribute is a type. The result
is a Boolean value which is True if the is an access type, or is a composite
type with a component (at any nesting depth) that is an access type, and is
False otherwise.
The intended use of this attribute is in conjunction with generic
definitions. If the attribute is applied to a generic private type, it
indicates whether or not the corresponding actual type has access values.
Has_Discriminants
The prefix of the Has_Discriminants attribute is a type. The result
is a Boolean value which is True if the type has discriminants, and False
otherwise. The intended use of this attribute is in conjunction with generic
definitions. If the attribute is applied to a generic private type, it
indicates whether or not the corresponding actual type has discriminants.
Img
The Img attribute differs from Image in that it may be
applied to objects as well as types, in which case it gives the
Image for the subtype of the object. This is convenient for
debugging:
| | Put_Line ("X = " & X'Img);
|
has the same meaning as the more verbose:
| | Put_Line ("X = " & T'Image (X));
|
where T is the (sub)type of the object X.
Integer_Value
For every integer type S, S'Integer_Value denotes a
function with the following spec:
| | function S'Integer_Value (Arg : Universal_Fixed)
return S;
|
The value returned is the integer value V, such that
where T is the type of Arg.
The effect is thus similar to first doing an unchecked conversion from
the fixed-point type to its corresponding implementation type, and then
converting the result to the target integer type. The difference is
that there are full range checks, to ensure that the result is in range.
This attribute is primarily intended for use in implementation of the
standard input-output functions for fixed-point values.
Large
The Large attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Machine_Size
This attribute is identical to the Object_Size attribute. It is
provided for compatibility with the DEC Ada 83 attribute of this name.
Mantissa
The Mantissa attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Max_Interrupt_Priority
Standard'Max_Interrupt_Priority (Standard is the only
permissible prefix), provides the same value as
System.Max_Interrupt_Priority.
Max_Priority
Standard'Max_Priority (Standard is the only permissible
prefix) provides the same value as System.Max_Priority.
Maximum_Alignment
Standard'Maximum_Alignment (Standard is the only
permissible prefix) provides the maximum useful alignment value for the
target. This is a static value that can be used to specify the alignment
for an object, guaranteeing that it is properly aligned in all
cases.
Mechanism_Code
function'Mechanism_Code yields an integer code for the
mechanism used for the result of function, and
subprogram'Mechanism_Code (n) yields the mechanism
used for formal parameter number n (a static integer value with 1
meaning the first parameter) of subprogram. The code returned is:
- 1
- by copy (value)
- 2
- by reference
- 3
- by descriptor (default descriptor class)
- 4
- by descriptor (UBS: unaligned bit string)
- 5
- by descriptor (UBSB: aligned bit string with arbitrary bounds)
- 6
- by descriptor (UBA: unaligned bit array)
- 7
- by descriptor (S: string, also scalar access type parameter)
- 8
- by descriptor (SB: string with arbitrary bounds)
- 9
- by descriptor (A: contiguous array)
- 10
- by descriptor (NCA: non-contiguous array)
Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
Null_Parameter
A reference T'Null_Parameter denotes an imaginary object of
type or subtype T allocated at machine address zero. The attribute
is allowed only as the default expression of a formal parameter, or as
an actual expression of a subprogram call. In either case, the
subprogram must be imported.
The identity of the object is represented by the address zero in the
argument list, independent of the passing mechanism (explicit or
default).
This capability is needed to specify that a zero address should be
passed for a record or other composite object passed by reference.
There is no way of indicating this without the Null_Parameter
attribute.
Object_Size
The size of an object is not necessarily the same as the size of the type
of an object. This is because by default object sizes are increased to be
a multiple of the alignment of the object. For example,
Natural'Size is
31, but by default objects of type Natural will have a size of 32 bits.
Similarly, a record containing an integer and a character:
| | type Rec is record
I : Integer;
C : Character;
end record;
|
will have a size of 40 (that is Rec'Size will be 40. The
alignment will be 4, because of the
integer field, and so the default size of record objects for this type
will be 64 (8 bytes).
The type'Object_Size attribute
has been added to GNAT to allow the
default object size of a type to be easily determined. For example,
Natural'Object_Size is 32, and
Rec'Object_Size (for the record type in the above example) will be
64. Note also that, unlike the situation with the
Size attribute as defined in the Ada RM, the
Object_Size attribute can be specified individually
for different subtypes. For example:
| | type R is new Integer;
subtype R1 is R range 1 .. 10;
subtype R2 is R range 1 .. 10;
for R2'Object_Size use 8;
|
In this example, R'Object_Size and R1'Object_Size are both
32 since the default object size for a subtype is the same as the object size
for the parent subtype. This means that objects of type R
or R1 will
by default be 32 bits (four bytes). But objects of type
R2 will be only
8 bits (one byte), since R2'Object_Size has been set to 8.
Passed_By_Reference
type'Passed_By_Reference for any subtype type returns
a value of type Boolean value that is True if the type is
normally passed by reference and False if the type is normally
passed by copy in calls. For scalar types, the result is always False
and is static. For non-scalar types, the result is non-static.
Range_Length
type'Range_Length for any discrete type type yields
the number of values represented by the subtype (zero for a null
range). The result is static for static subtypes. Range_Length
applied to the index subtype of a one dimensional array always gives the
same result as Range applied to the array itself.
Safe_Emax
The Safe_Emax attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Safe_Large
The Safe_Large attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
Small
The Small attribute is defined in Ada 95 only for fixed-point types.
GNAT also allows this attribute to be applied to floating-point types
for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute when applied to floating-point types.
Storage_Unit
Standard'Storage_Unit (Standard is the only permissible
prefix) provides the same value as System.Storage_Unit.
Target_Name
Standard'Target_Name (Standard is the only permissible
prefix) provides a static string value that identifies the target
for the current compilation. For GCC implementations, this is the
standard gcc target name without the terminating slash (for
example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
Tick
Standard'Tick (Standard is the only permissible prefix)
provides the same value as System.Tick,
To_Address
The System'To_Address
(System is the only permissible prefix)
denotes a function identical to
System.Storage_Elements.To_Address except that
it is a static attribute. This means that if its argument is
a static expression, then the result of the attribute is a
static expression. The result is that such an expression can be
used in contexts (e.g. preelaborable packages) which require a
static expression and where the function call could not be used
(since the function call is always non-static, even if its
argument is static).
Type_Class
type'Type_Class for any type or subtype type yields
the value of the type class for the full type of type. If
type is a generic formal type, the value is the value for the
corresponding actual subtype. The value of this attribute is of type
System.Aux_DEC.Type_Class, which has the following definition:
| | type Type_Class is
(Type_Class_Enumeration,
Type_Class_Integer,
Type_Class_Fixed_Point,
Type_Class_Floating_Point,
Type_Class_Array,
Type_Class_Record,
Type_Class_Access,
Type_Class_Task,
Type_Class_Address);
|
Protected types yield the value Type_Class_Task, which thus
applies to all concurrent types. This attribute is designed to
be compatible with the DEC Ada 83 attribute of the same name.
UET_Address
The UET_Address attribute can only be used for a prefix which
denotes a library package. It yields the address of the unit exception
table when zero cost exception handling is used. This attribute is
intended only for use within the GNAT implementation. See the unit
Ada.Exceptions in files `a-except.ads' and `a-except.adb'
for details on how this attribute is used in the implementation.
Unconstrained_Array
The Unconstrained_Array attribute can be used with a prefix that
denotes any type or subtype. It is a static attribute that yields
True if the prefix designates an unconstrained array,
and False otherwise. In a generic instance, the result is
still static, and yields the result of applying this test to the
generic actual.
Universal_Literal_String
The prefix of Universal_Literal_String must be a named
number. The static result is the string consisting of the characters of
the number as defined in the original source. This allows the user
program to access the actual text of named numbers without intermediate
conversions and without the need to enclose the strings in quotes (which
would preclude their use as numbers). This is used internally for the
construction of values of the floating-point attributes from the file
`ttypef.ads', but may also be used by user programs.
Unrestricted_Access
The Unrestricted_Access attribute is similar to Access
except that all accessibility and aliased view checks are omitted. This
is a user-beware attribute. It is similar to
Address, for which it is a desirable replacement where the value
desired is an access type. In other words, its effect is identical to
first applying the Address attribute and then doing an unchecked
conversion to a desired access type. In GNAT, but not necessarily in
other implementations, the use of static chains for inner level
subprograms means that Unrestricted_Access applied to a
subprogram yields a value that can be called as long as the subprogram
is in scope (normal Ada 95 accessibility rules restrict this usage).
It is possible to use Unrestricted_Access for any type, but care
must be excercised if it is used to create pointers to unconstrained
objects. In this case, the resulting pointer has the same scope as the
context of the attribute, and may not be returned to some enclosing
scope. For instance, a function cannot use Unrestricted_Access
to create a unconstrained pointer and then return that value to the
caller.
VADS_Size
The 'VADS_Size attribute is intended to make it easier to port
legacy code which relies on the semantics of 'Size as implemented
by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
same semantic interpretation. In particular, 'VADS_Size applied
to a predefined or other primitive type with no Size clause yields the
Object_Size (for example, Natural'Size is 32 rather than 31 on
typical machines). In addition 'VADS_Size applied to an object
gives the result that would be obtained by applying the attribute to
the corresponding type.
Value_Size
type'Value_Size is the number of bits required to represent
a value of the given subtype. It is the same as type'Size,
but, unlike Size, may be set for non-first subtypes.
Wchar_T_Size
Standard'Wchar_T_Size (Standard is the only permissible
prefix) provides the size in bits of the C wchar_t type
primarily for constructing the definition of this type in
package Interfaces.C.
Word_Size
Standard'Word_Size (Standard is the only permissible
prefix) provides the value System.Word_Size.
This document was generated
by Mail Server on June, 15 2005
using texi2html