@c o
@c G N A T _ RM o
@c o
-@c Copyright (C) 1995-2008, Free Software Foundation o
-@c o
-@c o
@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@setfilename gnat_rm.info
+@copying
+Copyright @copyright{} 1995-2008, Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``GNAT Reference
+Manual'', and with no Back-Cover Texts. A copy of the license is
+included in the section entitled ``GNU Free Documentation License''.
+@end copying
+
@set EDITION GNAT
@set DEFAULTLANGUAGEVERSION Ada 2005
@set NONDEFAULTLANGUAGEVERSION Ada 95
* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
@end direntry
-@copying
-Copyright @copyright{} 1995-2008, Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being ``GNU Free Documentation License'',
-with the Front-Cover Texts being ``GNAT Reference Manual'', and with
-no Back-Cover Texts. A copy of the license is included in the section
-entitled ``GNU Free Documentation License''.
-@end copying
-
@titlepage
@title GNAT Reference Manual
@subtitle GNAT, The GNU Ada Compiler
* Pragma Ada_2005::
* Pragma Annotate::
* Pragma Assert::
+* Pragma Assume_No_Invalid_Values::
* Pragma Ast_Entry::
* Pragma C_Pass_By_Copy::
* Pragma Check::
* Pragma Task_Info::
* Pragma Task_Name::
* Pragma Task_Storage::
+* Pragma Thread_Local_Storage::
* Pragma Time_Slice::
* Pragma Title::
* Pragma Unchecked_Union::
* AST_Entry::
* Bit::
* Bit_Position::
+* Compiler_Version::
* Code_Address::
* Default_Bit_Order::
* Elaborated::
* Wide_Text_IO::
* Wide_Wide_Text_IO::
* Stream_IO::
+* Text Translation::
* Shared Files::
* Filenames encoding::
* Open Modes::
* GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
* GNAT.Spitbol.Table_Integer (g-sptain.ads)::
* GNAT.Spitbol.Table_VString (g-sptavs.ads)::
+* GNAT.SSE (g-sse.ads)::
+* GNAT.SSE.Vector_Types (g-ssvety.ads)::
* GNAT.Strings (g-string.ads)::
* GNAT.String_Split (g-strspl.ads)::
* GNAT.Table (g-table.ads)::
* System.Pool_Local (s-pooloc.ads)::
* System.Restrictions (s-restri.ads)::
* System.Rident (s-rident.ads)::
+* System.Strings.Stream_Ops (s-ststop.ads)::
* System.Task_Info (s-tasinf.ads)::
* System.Wch_Cnv (s-wchcnv.ads)::
* System.Wch_Con (s-wchcon.ads)::
@noindent
Ada defines a set of pragmas that can be used to supply additional
information to the compiler. These language defined pragmas are
-implemented in GNAT and work as described in the Ada Reference
-Manual.
+implemented in GNAT and work as described in the Ada Reference Manual.
In addition, Ada allows implementations to define additional pragmas
whose meaning is defined by the implementation. GNAT provides a number
* Pragma Ada_2005::
* Pragma Annotate::
* Pragma Assert::
+* Pragma Assume_No_Invalid_Values::
* Pragma Ast_Entry::
* Pragma C_Pass_By_Copy::
* Pragma Check::
* Pragma Task_Info::
* Pragma Task_Name::
* Pragma Task_Storage::
+* Pragma Thread_Local_Storage::
* Pragma Time_Slice::
* Pragma Title::
* Pragma Unchecked_Union::
semantic correctness whether or not assertions are enabled, so turning
assertions on and off cannot affect the legality of a program.
+@node Pragma Assume_No_Invalid_Values
+@unnumberedsec Pragma Assume_No_Invalid_Values
+@findex Assume_No_Invalid_Values
+@cindex Invalid representations
+@cindex Invalid values
+@noindent
+Syntax:
+@smallexample @c ada
+pragma Assume_No_Invalid_Values (On | Off);
+@end smallexample
+
+@noindent
+This is a configuration pragma that controls the assumptions made by the
+compiler about the occurrence of invalid representations (invalid values)
+in the code.
+
+The default behavior (corresponding to an Off argument for this pragma), is
+to assume that values may in general be invalid unless the compiler can
+prove they are valid. Consider the following example:
+
+@smallexample @c ada
+V1 : Integer range 1 .. 10;
+V2 : Integer range 11 .. 20;
+...
+for J in V2 .. V1 loop
+ ...
+end loop;
+@end smallexample
+
+@noindent
+if V1 and V2 have valid values, then the loop is known at compile
+time not to execute since the lower bound must be greater than the
+upper bound. However in default mode, no such assumption is made,
+and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
+is given, the compiler will assume that any occurrence of a variable
+other than in an explicit @code{'Valid} test always has a valid
+value, and the loop above will be optimized away.
+
+The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
+you know your code is free of uninitialized variables and other
+possible sources of invalid representations, and may result in
+more efficient code. A program that accesses an invalid representation
+with this pragma in effect is erroneous, so no guarantees can be made
+about its behavior.
+
+It is peculiar though permissible to use this pragma in conjunction
+with validity checking (-gnatVa). In such cases, accessing invalid
+values will generally give an exception, though formally the program
+is erroneous so there are no guarantees that this will always be the
+case, and it is recommended that these two options not be used together.
+
@node Pragma Ast_Entry
@unnumberedsec Pragma Ast_Entry
@cindex OpenVMS
@noindent
Syntax:
@smallexample @c ada
-pragma Check_Policy ([Name =>] Identifier, POLICY_IDENTIFIER);
+pragma Check_Policy
+ ([Name =>] Identifier,
+ [Policy =>] POLICY_IDENTIFIER);
POLICY_IDENTIFIER ::= On | Off | Check | Ignore
@end smallexample
@noindent
The argument denotes an entity in the current declarative region that is
-declared as a tagged record type. It indicates that the type corresponds
-to an externally declared C++ class type, and is to be laid out the same
-way that C++ would lay out the type.
+declared as a record type. It indicates that the type corresponds to an
+externally declared C++ class type, and is to be laid out the same way
+that C++ would lay out the type. If the C++ class has virtual primitives
+then the record must be declared as a tagged record type.
Types for which @code{CPP_Class} is specified do not have assignment or
equality operators defined (such operations can be imported or declared
as subprograms as required). Initialization is allowed only by constructor
functions (see pragma @code{CPP_Constructor}). Such types are implicitly
limited if not explicitly declared as limited or derived from a limited
-type, and a warning is issued in that case.
+type, and an error is issued in that case.
Pragma @code{CPP_Class} is intended primarily for automatic generation
using an automatic binding generator tool.
@itemize @bullet
@item
+@code{function @var{Fname} return @var{T}}
+
+@itemize @bullet
+@item
@code{function @var{Fname} return @var{T}'Class}
@item
-@code{function @var{Fname} (@dots{}) return @var{T}'Class}
+@code{function @var{Fname} (@dots{}) return @var{T}}
@end itemize
-@noindent
-where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
-
-The first form is the default constructor, used when an object of type
-@var{T} is created on the Ada side with no explicit constructor. Other
-constructors (including the copy constructor, which is simply a special
-case of the second form in which the one and only argument is of type
-@var{T}), can only appear in two contexts:
-
-@itemize @bullet
-@item
-On the right side of an initialization of an object of type @var{T}.
@item
-In an extension aggregate for an object of a type derived from @var{T}.
+@code{function @var{Fname} (@dots{}) return @var{T}'Class}
@end itemize
@noindent
-Although the constructor is described as a function that returns a value
-on the Ada side, it is typically a procedure with an extra implicit
-argument (the object being initialized) at the implementation
-level. GNAT issues the appropriate call, whatever it is, to get the
-object properly initialized.
-
-In the case of derived objects, you may use one of two possible forms
-for declaring and creating an object:
-
-@itemize @bullet
-@item @code{New_Object : Derived_T}
-@item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})}
-@end itemize
+where @var{T} is a limited record type imported from C++ with pragma
+@code{Import} and @code{Convention} = @code{CPP}.
-@noindent
-In the first case the default constructor is called and extension fields
-if any are initialized according to the default initialization
-expressions in the Ada declaration. In the second case, the given
-constructor is called and the extension aggregate indicates the explicit
-values of the extension fields.
+The first two forms import the default constructor, used when an object
+of type @var{T} is created on the Ada side with no explicit constructor.
+The latter two forms cover all the non-default constructors of the type.
+See the GNAT users guide for details.
If no constructors are imported, it is impossible to create any objects
-on the Ada side. If no default constructor is imported, only the
-initialization forms using an explicit call to a constructor are
-permitted.
+on the Ada side and the type is implicitly declared abstract.
Pragma @code{CPP_Constructor} is intended primarily for automatic generation
using an automatic binding generator tool.
See @ref{Interfacing to C++} for more related information.
+Note: The use of functions returning class-wide types for constructors is
+currently obsolete. They are supported for backward compatibility. The
+use of functions returning the type T leave the Ada sources more clear
+because the imported C++ constructors always return an object of type T;
+that is, they never return an object whose type is a descendant of type T.
+
@node Pragma CPP_Virtual
@unnumberedsec Pragma CPP_Virtual
@cindex Interfacing to C++
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample
@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
+The default behavior for Export_Function is to accept either 64bit or
+32bit descriptors unless short_descriptor is specified, then only 32bit
+descriptors are accepted.
@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample
@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
+The default behavior for Export_Procedure is to accept either 64bit or
+32bit descriptors unless short_descriptor is specified, then only 32bit
+descriptors are accepted.
@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample
@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
+The default behavior for Export_Valued_Procedure is to accept either 64bit or
+32bit descriptors unless short_descriptor is specified, then only 32bit
+descriptors are accepted.
@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
@noindent
This is a configuration pragma that requests implicit packing for packed
arrays for which a size clause is given but no explicit pragma Pack or
-specification of Component_Size is present. Consider this example:
+specification of Component_Size is present. It also applies to records
+where no record representation clause is present. Consider this example:
@smallexample @c ada
type R is array (0 .. 7) of Boolean;
by the size in bits of the component type.
@cindex Array packing
+Similarly, the following example shows the use in the record case
+
+@smallexample @c ada
+type r is record
+ a, b, c, d, e, f, g, h : boolean;
+ chr : character;
+end record;
+for r'size use 16;
+@end smallexample
+
+@noindent
+Without a pragma Pack, each Boolean field requires 8 bits, so the
+minimum size is 72 bits, but with a pragma Pack, 16 bits would be
+sufficient. The use of pragma Implciit_Packing allows this record
+declaration to compile without an explicit pragma Pack.
@node Pragma Import_Exception
@unnumberedsec Pragma Import_Exception
@cindex OpenVMS
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
@end smallexample
@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
+The default behavior for Import_Function is to pass a 64bit descriptor
+unless short_descriptor is specified, then a 32bit descriptor is passed.
@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
It specifies that the designated parameter and all following parameters
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
@end smallexample
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
+| Short_Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
@end smallexample
Syntax:
@smallexample @c ada
-pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER);
+pragma Interrupt_State
+ ([Name =>] value,
+ [State =>] SYSTEM | RUNTIME | USER);
@end smallexample
@noindent
pragma Machine_Attribute (
[Entity =>] LOCAL_NAME,
[Attribute_Name =>] static_string_EXPRESSION
- [, [Info =>] static_string_EXPRESSION] );
+ [, [Info =>] static_EXPRESSION] );
@end smallexample
@noindent
@code{__attribute__((@var{attribute_name}))} (if @var{info} is not
specified) or @code{__attribute__((@var{attribute_name}(@var{info})))}
in GNU C, where @code{@var{attribute_name}} is recognized by the
-target macro @code{TARGET_ATTRIBUTE_TABLE} which is defined for each
-machine. The optional parameter @var{info} is transformed into an
-identifier, which may make this pragma unusable for some attributes
-(parameter of some attributes must be a number or a string).
-@xref{Target Attributes,, Defining target-specific uses of
-@code{__attribute__}, gccint, GNU Compiler Colletion (GCC) Internals},
-further information. It is not possible to specify
-attributes defined by other languages, only attributes defined by the
-machine the code is intended to run on.
+compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine
+specific macro. A string literal for the optional parameter @var{info}
+is transformed into an identifier, which may make this pragma unusable
+for some attributes. @xref{Target Attributes,, Defining target-specific
+uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC)
+Internals}, further information.
@node Pragma Main
@unnumberedsec Pragma Main
(MAIN_OPTION [, MAIN_OPTION]);
MAIN_OPTION ::=
- [STACK_SIZE =>] static_integer_EXPRESSION
-| [TASK_STACK_SIZE_DEFAULT =>] static_integer_EXPRESSION
-| [TIME_SLICING_ENABLED =>] static_boolean_EXPRESSION
+ [Stack_Size =>] static_integer_EXPRESSION
+| [Task_Stack_Size_Default =>] static_integer_EXPRESSION
+| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION
@end smallexample
@noindent
Syntax:
@smallexample @c ada
-pragma Obsolescent
- (Entity => NAME [, static_string_EXPRESSION [,Ada_05]]);
+pragma Obsolescent;
+
+pragma Obsolescent (
+ [Message =>] static_string_EXPRESSION
+[,[Version =>] Ada_05]]);
+
+pragma Obsolescent (
+ [Entity =>] NAME
+[,[Message =>] static_string_EXPRESSION
+[,[Version =>] Ada_05]] );
@end smallexample
@noindent
This pragma can occur immediately following a declaration of an entity,
-including the case of a record component, and usually the Entity name
-must match the name of the entity declared by this declaration.
-Alternatively, the pragma can immediately follow an
-enumeration type declaration, where the entity argument names one of the
-enumeration literals.
+including the case of a record component. If no Entity argument is present,
+then this declaration is the one to which the pragma applies. If an Entity
+parameter is present, it must either match the name of the entity in this
+declaration, or alternatively, the pragma can immediately follow an enumeration
+type declaration, where the Entity argument names one of the enumeration
+literals.
This pragma is used to indicate that the named entity
is considered obsolescent and should not be used. Typically this is
intermediate stage when the entity is still present, but will be
removed later.
-The effect of this pragma is to output a warning message on
-a call to a program thus marked that the
-subprogram is obsolescent if the appropriate warning option in the
-compiler is activated. If the string parameter is present, then a second
-warning message is given containing this text.
-In addition, a call to such a program is considered a violation of
-pragma Restrictions (No_Obsolescent_Features).
+The effect of this pragma is to output a warning message on a reference to
+an entity thus marked that the subprogram is obsolescent if the appropriate
+warning option in the compiler is activated. If the Message parameter is
+present, then a second warning message is given containing this text. In
+addition, a reference to the eneity is considered to be a violation of pragma
+Restrictions (No_Obsolescent_Features).
This pragma can also be used as a program unit pragma for a package,
in which case the entity name is the name of the package, and the
violates the restriction, and the @code{with} statement is
flagged with warnings if the warning option is set.
-If the optional third parameter is present (which must be exactly
+If the Version parameter is present (which must be exactly
the identifier Ada_05, no other argument is allowed), then the
indication of obsolescence applies only when compiling in Ada 2005
mode. This is primarily intended for dealing with the situations
@smallexample @c ada
package p is
- pragma Obsolescent
- (Entity => p, "use pp instead of p");
+ pragma Obsolescent (p, Message => "use pp instead of p");
end p;
package q is
procedure q2;
- pragma Obsolescent
- (Entity => q2, "use q2new instead");
+ pragma Obsolescent ("use q2new instead");
type R is new integer;
pragma Obsolescent
- (Entity => R, "use RR in Ada 2005", Ada_05);
+ (Entity => R,
+ Message => "use RR in Ada 2005",
+ Version => Ada_05);
type M is record
F1 : Integer;
F2 : Integer;
- pragma Obsolescent (Entity => F2);
+ pragma Obsolescent;
F3 : Integer;
end record;
@end smallexample
@noindent
-In an earlier version of GNAT, the Entity parameter was not required,
-and this form is still accepted for compatibility purposes. If the
-Entity parameter is omitted, then the pragma applies to the declaration
-immediately preceding the pragma (this form cannot be used for the
-enumeration literal case).
+Note that, as for all pragmas, if you use a pragma argument identifier,
+then all subsequent parameters must also use a pragma argument identifier.
+So if you specify "Entity =>" for the Entity argument, and a Message
+argument is present, it must be preceded by "Message =>".
@node Pragma Optimize_Alignment
@unnumberedsec Pragma Optimize_Alignment
The @code{Postcondition} pragma allows specification of automatic
postcondition checks for subprograms. These checks are similar to
assertions, but are automatically inserted just prior to the return
-statements of the subprogram with which they are associated.
-Furthermore, the boolean expression which is the condition which
+statements of the subprogram with which they are associated (including
+implicit returns at the end of procedure bodies and associated
+exception handlers).
+
+In addition, the boolean expression which is the condition which
must be true may contain references to function'Result in the case
of a function to refer to the returned value.
end Sort;
@end smallexample
+@noindent
+Note: postcondition pragmas associated with subprograms that are
+marked as Inline_Always, or those marked as Inline with front-end
+inlining (-gnatN option set) are accepted and legality-checked
+by the compiler, but are ignored at run-time even if postcondition
+checking is enabled.
+
@node Pragma Precondition
@unnumberedsec Pragma Precondition
@cindex Preconditions
end Math_Functions;
@end smallexample
-@code{Postcondition} pragmas may appear either immediate following the
+@noindent
+@code{Precondition} pragmas may appear either immediate following the
(separate) declaration of a subprogram, or at the start of the
declarations of a subprogram body. Only other pragmas may intervene
(that is appear between the subprogram declaration and its
postconditions, or appear before the postcondition in the
declaration sequence in a subprogram body).
+Note: postcondition pragmas associated with subprograms that are
+marked as Inline_Always, or those marked as Inline with front-end
+inlining (-gnatN option set) are accepted and legality-checked
+by the compiler, but are ignored at run-time even if postcondition
+checking is enabled.
+
+
+
@node Pragma Profile (Ravenscar)
@unnumberedsec Pragma Profile (Ravenscar)
@findex Ravenscar
@smallexample @c ada
pragma Source_File_Name (
[Unit_Name =>] unit_NAME,
- Spec_File_Name => STRING_LITERAL);
+ Spec_File_Name => STRING_LITERAL,
+ [Index => INTEGER_LITERAL]);
pragma Source_File_Name (
[Unit_Name =>] unit_NAME,
- Body_File_Name => STRING_LITERAL);
+ Body_File_Name => STRING_LITERAL,
+ [Index => INTEGER_LITERAL]);
@end smallexample
@noindent
the second argument is required, and indicates whether this is the file
name for the spec or for the body.
+The optional Index argument should be used when a file contains multiple
+units, and when you do not want to use @code{gnatchop} to separate then
+into multiple files (which is the recommended procedure to limit the
+number of recompilation that are needed when some sources change).
+For instance, if the source file @file{source.ada} contains
+
+@smallexample @c ada
+package B is
+...
+end B;
+
+with B;
+procedure A is
+begin
+ ..
+end A;
+@end smallexample
+
+you could use the following configuration pragmas:
+
+@smallexample @c ada
+pragma Source_File_Name
+ (B, Spec_File_Name => "source.ada", Index => 1);
+pragma Source_File_Name
+ (A, Body_File_Name => "source.ada", Index => 2);
+@end smallexample
+
+Note that the @code{gnatname} utility can also be used to generate those
+configuration pragmas.
+
Another form of the @code{Source_File_Name} pragma allows
the specification of patterns defining alternative file naming schemes
to apply to all files.
@smallexample @c ada
pragma Source_File_Name
- (Spec_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ ( [Spec_File_Name =>] STRING_LITERAL
+ [,[Casing =>] CASING_SPEC]
+ [,[Dot_Replacement =>] STRING_LITERAL]);
pragma Source_File_Name
- (Body_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ ( [Body_File_Name =>] STRING_LITERAL
+ [,[Casing =>] CASING_SPEC]
+ [,[Dot_Replacement =>] STRING_LITERAL]);
pragma Source_File_Name
- (Subunit_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ ( [Subunit_File_Name =>] STRING_LITERAL
+ [,[Casing =>] CASING_SPEC]
+ [,[Dot_Replacement =>] STRING_LITERAL]);
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
@end smallexample
@end smallexample
@noindent
-The effect is that if the value of an unbounded string is written to a
-stream, then the representation of the item in the stream is in the same
-format used for @code{Standard.String}, and this same representation is
-expected when a value of this type is read from the stream.
+The effect is that if the value of an unbounded string is written to a stream,
+then the representation of the item in the stream is in the same format that
+would be used for @code{Standard.String'Output}, and this same representation
+is expected when a value of this type is read from the stream. Note that the
+value written always includes the bounds, even for Unbounded_String'Write,
+since Unbounded_String is not an array type.
@node Pragma Style_Checks
@unnumberedsec Pragma Style_Checks
by suppressing range checks, but the specific use of @code{Alignment_Check}
allows suppression of alignment checks without suppressing other range checks.
+Note that pragma Suppress gives the compiler permission to omit
+checks, but does not require the compiler to omit checks. The compiler
+will generate checks if they are essentially free, even when they are
+suppressed. In particular, if the compiler can prove that a certain
+check will necessarily fail, it will generate code to do an
+unconditional ``raise'', even if checks are suppressed. The compiler
+warns in this case.
+
+Of course, run-time checks are omitted whenever the compiler can prove
+that they will not fail, whether or not checks are suppressed.
+
@node Pragma Suppress_All
@unnumberedsec Pragma Suppress_All
@findex Suppress_All
@code{Storage_Size} attribute definition clause is allowed for a task
type.
+@node Pragma Thread_Local_Storage
+@unnumberedsec Pragma Thread_Local_Storage
+@findex Thread_Local_Storage
+@cindex Task specific storage
+@cindex TLS (Thread Local Storage)
+Syntax:
+
+@smallexample @c ada
+pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
+@end smallexample
+
+@noindent
+This pragma specifies that the specified entity, which must be
+a variable declared in a library level package, is to be marked as
+"Thread Local Storage" (@code{TLS}). On systems supporting this (which
+include Solaris, GNU/Linux and VxWorks 6), this causes each thread
+(and hence each Ada task) to see a distinct copy of the variable.
+
+The variable may not have default initialization, and if there is
+an explicit initialization, it must be either @code{null} for an
+access variable, or a static expression for a scalar variable.
+This provides a low level mechanism similar to that provided by
+the @code{Ada.Task_Attributes} package, but much more efficient
+and is also useful in writing interface code that will interact
+with foreign threads.
+
+If this pragma is used on a system where @code{TLS} is not supported,
+then an error message will be generated and the program will be rejected.
+
@node Pragma Time_Slice
@unnumberedsec Pragma Time_Slice
@findex Time_Slice
.A turn off warnings for failing assertions
b turn on warnings for bad fixed value (not multiple of small)
B* turn off warnings for bad fixed value (not multiple of small)
+.b* turn on warnings for biased representation
+.B turn off warnings for biased representation
c turn on warnings for constant conditional
C* turn off warnings for constant conditional
.c turn on warnings for unrepped components
d turn on warnings for implicit dereference
D* turn off warnings for implicit dereference
e treat all warnings as errors
+.e turn on every optional warning
f turn on warnings for unreferenced formal
F* turn off warnings for unreferenced formal
g* turn on warnings for unrecognized pragma
.O* turn off warnings for out parameters assigned but not read
p turn on warnings for ineffective pragma Inline in frontend
P* turn off warnings for ineffective pragma Inline in frontend
+.p turn on warnings for parameter ordering
+.P* turn off warnings for parameter ordering
q* turn on warnings for questionable missing parentheses
Q turn off warnings for questionable missing parentheses
r turn on warnings for redundant construct
V turn off warnings for unassigned variable
w* turn on warnings for wrong low bound assumption
W turn off warnings for wrong low bound assumption
+.w turn on warnings for unnecessary Warnings Off pragmas
+.W* turn off warnings for unnecessary Warnings Off pragmas
x* turn on warnings for export/import
X turn off warnings for export/import
.x turn on warnings for non-local exceptions
The fourth form, with an On|Off parameter and a string, is used to
control individual messages, based on their text. The string argument
is a pattern that is used to match against the text of individual
-warning messages (not including the initial "warnings: " tag).
+warning messages (not including the initial "warning: " tag).
-The pattern may contain asterisks which match zero or more characters in
+The pattern may contain asterisks, which match zero or more characters in
the message. For example, you can use
@code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning
message @code{warning: 960 bits of "a" unused}. No other regular
* AST_Entry::
* Bit::
* Bit_Position::
+* Compiler_Version::
* Code_Address::
* Default_Bit_Order::
* Elaborated::
@var{C} and is independent of the alignment of
the containing record @var{R}.
+@node Compiler_Version
+@unnumberedsec Compiler_Version
+@findex Compiler_Version
+@noindent
+@code{Standard'Compiler_Version} (@code{Standard} is the only allowed
+prefix) yields a static string identifying the version of the compiler
+being used to compile the unit containing the attribute reference. A
+typical result would be something like "GNAT Pro 6.3.0w (20090221)".
+
@node Code_Address
@unnumberedsec Code_Address
@findex Code_Address
@item No_Direct_Boolean_Operators
@findex No_Direct_Boolean_Operators
-This restriction ensures that no logical (and/or/xor) or comparison
-operators are used on operands of type Boolean (or any type derived
+This restriction ensures that no logical (and/or/xor) are used on
+operands of type Boolean (or any type derived
from Boolean). This is intended for use in safety critical programs
where the certification protocol requires the use of short-circuit
(and then, or else) forms for all composite boolean operations.
an immediate call to the last chance handler, a routine that the user
must define with the following profile:
- procedure Last_Chance_Handler
- (Source_Location : System.Address; Line : Integer);
- pragma Export (C, Last_Chance_Handler,
- "__gnat_last_chance_handler");
+@smallexample @c ada
+procedure Last_Chance_Handler
+ (Source_Location : System.Address; Line : Integer);
+pragma Export (C, Last_Chance_Handler,
+ "__gnat_last_chance_handler");
+@end smallexample
- The parameter is a C null-terminated string representing a message to be
- associated with the exception (typically the source location of the raise
- statement generated by the compiler). The Line parameter when nonzero
- represents the line number in the source program where the raise occurs.
+The parameter is a C null-terminated string representing a message to be
+associated with the exception (typically the source location of the raise
+statement generated by the compiler). The Line parameter when nonzero
+represents the line number in the source program where the raise occurs.
@item No_Exception_Propagation
@findex No_Exception_Propagation
@item No_Streams
@findex No_Streams
This restriction ensures at compile/bind time that there are no
-stream objects created (and therefore no actual stream operations).
+stream objects created and no use of stream attributes.
This restriction does not forbid dependences on the package
@code{Ada.Streams}. So it is permissible to with
@code{Ada.Streams} (or another package that does so itself)
-as long as no actual stream objects are created.
+as long as no actual stream objects are created and no
+stream attributes are used.
+
+Note that the use of restriction allows optimization of tagged types,
+since they do not need to worry about dispatching stream operations.
+To take maximum advantage of this space-saving optimization, any
+unit declaring a tagged type should be compiled with the restriction,
+though this is not required.
@item No_Task_Attributes_Package
@findex No_Task_Attributes_Package
require four-byte alignment, and the Y component will be one byte. In this
case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
required to store a value of this type, and for example, it is permissible
-to have a component of type R in an outer record whose component size is
+to have a component of type R in an outer array whose component size is
specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
since it must be rounded up so that this value is a multiple of the
alignment (4 bytes = 32 bits).
@item Float
@code{Ada.Numerics.Complex_Elementary_Functions}
@item Long_Float
-@code{Ada.Numerics.
- Long_Complex_Elementary_Functions}
+@code{Ada.Numerics.Long_Complex_Elementary_Functions}
@end table
@item Ada.Numerics.Generic_Complex_Types
* Wide_Text_IO::
* Wide_Wide_Text_IO::
* Stream_IO::
+* Text Translation::
* Shared Files::
* Filenames encoding::
* Open Modes::
@noindent
where letters may be in upper or lower case, and there are no spaces
between values. The order of the entries is not important. Currently
-there are two keywords defined.
+the following keywords defined.
@smallexample
+TEXT_TRANSLATION=[YES|NO]
SHARED=[YES|NO]
WCEM=[n|h|u|s|e|8|b]
+ENCODING=[UTF8|8BITS]
@end smallexample
@noindent
manner described for stream attributes.
@end itemize
+@node Text Translation
+@section Text Translation
+
+@noindent
+@samp{Text_Translation=@var{xxx}} may be used as the Form parameter
+passed to Text_IO.Create and Text_IO.Open:
+@samp{Text_Translation=@var{Yes}} is the default, which means to
+translate LF to/from CR/LF on Windows systems.
+@samp{Text_Translation=@var{No}} disables this translation; i.e. it
+uses binary mode. For output files, @samp{Text_Translation=@var{No}}
+may be used to create Unix-style files on
+Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix
+systems.
+
@node Shared Files
@section Shared Files
@end itemize
In the absence of a @samp{encoding=@var{xxx}} form parameter, the
-value UTF-8 is used. This encoding form parameter is only supported on
-the Windows platform. On the other Operating Systems the runtime is
-supporting UTF-8 natively.
+encoding is controlled by the @samp{GNAT_CODE_PAGE} environment
+variable. And if not set @samp{utf8} is assumed.
+
+@table @samp
+@item CP_ACP
+The current system Windows ANSI code page.
+@item CP_UTF8
+UTF-8 encoding
+@end table
+
+This encoding form parameter is only supported on the Windows
+platform. On the other Operating Systems the run-time is supporting
+UTF-8 natively.
@node Open Modes
@section Open Modes
* GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
* GNAT.Spitbol.Table_Integer (g-sptain.ads)::
* GNAT.Spitbol.Table_VString (g-sptavs.ads)::
+* GNAT.SSE (g-sse.ads)::
+* GNAT.SSE.Vector_Types (g-ssvety.ads)::
* GNAT.Strings (g-string.ads)::
* GNAT.String_Split (g-strspl.ads)::
* GNAT.Table (g-table.ads)::
* System.Pool_Local (s-pooloc.ads)::
* System.Restrictions (s-restri.ads)::
* System.Rident (s-rident.ads)::
+* System.Strings.Stream_Ops (s-ststop.ads)::
* System.Task_Info (s-tasinf.ads)::
* System.Wch_Cnv (s-wchcnv.ads)::
* System.Wch_Con (s-wchcon.ads)::
a variable length string type, giving an implementation of general
maps from strings to strings.
+@node GNAT.SSE (g-sse.ads)
+@section @code{GNAT.SSE} (@file{g-sse.ads})
+@cindex @code{GNAT.SSE} (@file{g-sse.ads})
+
+@noindent
+Root of a set of units aimed at offering Ada bindings to a subset of
+the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
+targets. It exposes vector component types together with a general
+introduction to the binding contents and use.
+
+@node GNAT.SSE.Vector_Types (g-ssvety.ads)
+@section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
+@cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
+
+@noindent
+SSE vector types for use with SSE related intrinsics.
+
@node GNAT.Strings (g-string.ads)
@section @code{GNAT.Strings} (@file{g-string.ads})
@cindex @code{GNAT.Strings} (@file{g-string.ads})
since the necessary instantiation is included in
package System.Restrictions.
+@node System.Strings.Stream_Ops (s-ststop.ads)
+@section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
+@cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
+@cindex Stream operations
+@cindex String stream operations
+
+@noindent
+This package provides a set of stream subprograms for standard string types.
+It is intended primarily to support implicit use of such subprograms when
+stream attributes are applied to string types, but the subprograms in this
+package can be used directly by application programs.
+
@node System.Task_Info (s-tasinf.ads)
@section @code{System.Task_Info} (@file{s-tasinf.ads})
@cindex @code{System.Task_Info} (@file{s-tasinf.ads})
OSDN Git Service
