@c o
@c G N A T _ RM o
@c o
-@c Copyright (C) 1995-2007, 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-2007, 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 Check_Name::
+* Pragma Check_Policy::
* Pragma Comment::
* Pragma Common_Object::
* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
+* Pragma Compiler_Unit::
* Pragma Complete_Representation::
* Pragma Complex_Representation::
* Pragma Component_Alignment::
* Pragma No_Strict_Aliasing ::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
* Pragma Passive::
* Pragma Persistent_BSS::
* Pragma Polling::
+* Pragma Postcondition::
+* Pragma Precondition::
* Pragma Profile (Ravenscar)::
* Pragma Profile (Restricted)::
* Pragma Psect_Object::
* Pragma Pure_Function::
* Pragma Restriction_Warnings::
* Pragma Shared::
+* Pragma Short_Circuit_And_Or::
* Pragma Source_File_Name::
* Pragma Source_File_Name_Project::
* Pragma Source_Reference::
* Pragma Task_Info::
* Pragma Task_Name::
* Pragma Task_Storage::
+* Pragma Thread_Local_Storage::
* Pragma Time_Slice::
* Pragma Title::
* Pragma Unchecked_Union::
* Pragma Unimplemented_Unit::
* Pragma Universal_Aliasing ::
* Pragma Universal_Data::
+* Pragma Unmodified::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* AST_Entry::
* Bit::
* Bit_Position::
+* Compiler_Version::
* Code_Address::
* Default_Bit_Order::
* Elaborated::
* Emax::
* Enabled::
* Enum_Rep::
+* Enum_Val::
* Epsilon::
* Fixed_Value::
* Has_Access_Values::
* Has_Discriminants::
* Img::
* Integer_Value::
+* Invalid_Value::
* Large::
* Machine_Size::
* Mantissa::
* Mechanism_Code::
* Null_Parameter::
* Object_Size::
+* Old::
* Passed_By_Reference::
* Pool_Address::
* Range_Length::
+* Result::
* Safe_Emax::
* Safe_Large::
* Small::
* Wide_Text_IO::
* Wide_Wide_Text_IO::
* Stream_IO::
+* Text Translation::
* Shared Files::
* Filenames encoding::
* Open Modes::
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
+* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Command_Line.Response_File (a-clrefi.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
* Ada.Exceptions.Traceback (a-exctra.ads)::
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
+* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
+* Ada.Wide_Characters.Unicode (a-wichun.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
+* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
* GNAT.Altivec (g-altive.ads)::
* GNAT.Altivec.Conversions (g-altcon.ads)::
* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
* GNAT.Most_Recent_Exception (g-moreex.ads)::
* GNAT.OS_Lib (g-os_lib.ads)::
* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
-* GNAT.Random_Numbers (g-rannum.ads)
+* GNAT.Random_Numbers (g-rannum.ads)::
* GNAT.Regexp (g-regexp.ads)::
* GNAT.Registry (g-regist.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.Serial_Communications (g-sercom.ads)::
* GNAT.SHA1 (g-sha1.ads)::
+* GNAT.SHA224 (g-sha224.ads)::
+* GNAT.SHA256 (g-sha256.ads)::
+* GNAT.SHA384 (g-sha384.ads)::
+* GNAT.SHA512 (g-sha512.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
* 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)::
* GNAT.Task_Lock (g-tasloc.ads)::
* GNAT.Threads (g-thread.ads)::
+* GNAT.Time_Stamp (g-timsta.ads)::
* GNAT.Traceback (g-traceb.ads)::
* GNAT.Traceback.Symbolic (g-trasym.ads)::
* GNAT.UTF_32 (g-utf_32.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Os2lib (i-os2lib.ads)::
-* Interfaces.Os2lib.Errors (i-os2err.ads)::
-* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
-* Interfaces.Os2lib.Threads (i-os2thr.ads)::
* Interfaces.Packed_Decimal (i-pacdec.ads)::
* Interfaces.VxWorks (i-vxwork.ads)::
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
* System.Assertions (s-assert.ads)::
* System.Memory (s-memory.ads)::
* System.Partition_Interface (s-parint.ads)::
+* System.Pool_Global (s-pooglo.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 Check_Name::
+* Pragma Check_Policy::
* Pragma Comment::
* Pragma Common_Object::
* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
+* Pragma Compiler_Unit::
* Pragma Complete_Representation::
* Pragma Complex_Representation::
* Pragma Component_Alignment::
* Pragma No_Strict_Aliasing::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
* Pragma Passive::
* Pragma Persistent_BSS::
* Pragma Polling::
+* Pragma Postcondition::
+* Pragma Precondition::
* Pragma Profile (Ravenscar)::
* Pragma Profile (Restricted)::
* Pragma Psect_Object::
* Pragma Pure_Function::
* Pragma Restriction_Warnings::
* Pragma Shared::
+* Pragma Short_Circuit_And_Or::
* Pragma Source_File_Name::
* Pragma Source_File_Name_Project::
* Pragma Source_Reference::
* Pragma Task_Info::
* Pragma Task_Name::
* Pragma Task_Storage::
+* Pragma Thread_Local_Storage::
* Pragma Time_Slice::
* Pragma Title::
* Pragma Unchecked_Union::
* Pragma Unimplemented_Unit::
* Pragma Universal_Aliasing ::
* Pragma Universal_Data::
+* Pragma Unmodified::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
@noindent
Syntax:
@smallexample @c ada
-pragma Annotate (IDENTIFIER @{, ARG@});
+pragma Annotate (IDENTIFIER [,IDENTIFIER] @{, ARG@});
ARG ::= NAME | EXPRESSION
@end smallexample
@noindent
This pragma is used to annotate programs. @var{identifier} identifies
the type of annotation. GNAT verifies that it is an identifier, but does
-not otherwise analyze it. The @var{arg} argument
-can be either a string literal or an
-expression. String literals are assumed to be of type
-@code{Standard.String}. Names of entities are simply analyzed as entity
-names. All other expressions are analyzed as expressions, and must be
+not otherwise analyze it. The second optional identifier is also left
+unanalyzed, and by convention is used to control the action of the tool to
+which the annotation is addressed. The remaining @var{arg} arguments
+can be either string literals or more generally expressions.
+String literals are assumed to be either of type
+@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
+depending on the character literals they contain.
+All other kinds of arguments are analyzed as expressions, and must be
unambiguous.
The analyzed pragma is retained in the tree, but not otherwise processed
@smallexample @c ada
pragma Assert (
boolean_EXPRESSION
- [, static_string_EXPRESSION]);
+ [, string_EXPRESSION]);
@end smallexample
@noindent
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
@code{Import} and @code{Export} pragmas, which allow specification of
passing mechanisms on a parameter by parameter basis.
+@node Pragma Check
+@unnumberedsec Pragma Check
+@cindex Assertions
+@cindex Named assertions
+@findex Check
+@noindent
+Syntax:
+@smallexample @c ada
+pragma Check (
+ [Name =>] Identifier,
+ [Check =>] Boolean_EXPRESSION
+ [, [Message =>] string_EXPRESSION] );
+@end smallexample
+
+@noindent
+This pragma is similar to the predefined pragma @code{Assert} except that an
+extra identifier argument is present. In conjunction with pragma
+@code{Check_Policy}, this can be used to define groups of assertions that can
+be independently controlled. The identifier @code{Assertion} is special, it
+refers to the normal set of pragma @code{Assert} statements. The identifiers
+@code{Precondition} and @code{Postcondition} correspond to the pragmas of these
+names, so these three names would normally not be used directly in a pragma
+@code{Check}.
+
+Checks introduced by this pragma are normally deactivated by default. They can
+be activated either by the command line option @option{-gnata}, which turns on
+all checks, or individually controlled using pragma @code{Check_Policy}.
+
@node Pragma Check_Name
@unnumberedsec Pragma Check_Name
@cindex Defining check names
This is a configuration pragma that defines a new implementation
defined check name (unless IDENTIFIER matches one of the predefined
check names, in which case the pragma has no effect). Check names
-are global to a partition, so if two more more configuration pragmas
+are global to a partition, so if two or more configuration pragmas
are present in a partition mentioning the same name, only one new
check name is introduced.
is part of the dependency set of the current unit (e.g., units that
are mentioned in @code{with} clauses).
+@node Pragma Check_Policy
+@unnumberedsec Pragma Check_Policy
+@cindex Controlling assertions
+@cindex Assertions, control
+@cindex Check pragma control
+@cindex Named assertions
+@findex Check
+@noindent
+Syntax:
+@smallexample @c ada
+pragma Check_Policy
+ ([Name =>] Identifier,
+ [Policy =>] POLICY_IDENTIFIER);
+
+POLICY_IDENTIFIER ::= On | Off | Check | Ignore
+@end smallexample
+
+@noindent
+This pragma is similar to the predefined pragma @code{Assertion_Policy},
+except that it controls sets of named assertions introduced using the
+@code{Check} pragmas. It can be used as a configuration pragma or (unlike
+@code{Assertion_Policy}) can be used within a declarative part, in which case
+it controls the status to the end of the corresponding construct (in a manner
+identical to pragma @code{Suppress)}.
+
+The identifier given as the first argument corresponds to a name used in
+associated @code{Check} pragmas. For example, if the pragma:
+
+@smallexample @c ada
+pragma Check_Policy (Critical_Error, Off);
+@end smallexample
+
+@noindent
+is given, then subsequent @code{Check} pragmas whose first argument is also
+@code{Critical_Error} will be disabled. The special identifier @code{Assertion}
+controls the behavior of normal @code{Assert} pragmas (thus a pragma
+@code{Check_Policy} with this identifier is similar to the normal
+@code{Assertion_Policy} pragma except that it can appear within a
+declarative part).
+
+The special identifiers @code{Precondition} and @code{Postcondition} control
+the status of preconditions and postconditions. If a @code{Precondition} pragma
+is encountered, it is ignored if turned off by a @code{Check_Policy} specifying
+that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use
+of the name @code{Postcondition} controls whether @code{Postcondition} pragmas
+are recognized.
+
+The check policy is @code{Off} to turn off corresponding checks, and @code{On}
+to turn on corresponding checks. The default for a set of checks for which no
+@code{Check_Policy} is given is @code{Off} unless the compiler switch
+@option{-gnata} is given, which turns on all checks by default.
+
+The check policy settings @code{Check} and @code{Ignore} are also recognized
+as synonyms for @code{On} and @code{Off}. These synonyms are provided for
+compatibility with the standard @code{Assertion_Policy} pragma.
+
@node Pragma Comment
@unnumberedsec Pragma Comment
@findex Comment
@noindent
Same as pragma Compile_Time_Error, except a warning is issued instead
-of an error message.
+of an error message. Note that if this pragma is used in a package that
+is with'ed by a client, the client will get the warning even though it
+is issued by a with'ed package (normally warnings in with'ed units are
+suppressed, but this is a special exception to that rule).
+
+One typical use is within a generic where compile time known characteristics
+of formal parameters are tested, and warnings given appropriately. Another use
+with a first parameter of True is to warn a client about use of a package,
+for example that it is not fully implemented.
+
+@node Pragma Compiler_Unit
+@unnumberedsec Pragma Compiler_Unit
+@findex Compiler_Unit
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Compiler_Unit;
+@end smallexample
+
+@noindent
+This pragma is intended only for internal use in the GNAT run-time library.
+It indicates that the unit is used as part of the compiler build. The effect
+is to disallow constructs (raise with message, conditional expressions etc)
+that would cause trouble when bootstrapping using an older version of GNAT.
+For the exact list of restrictions, see the compiler sources and references
+to Is_Compiler_Unit.
@node Pragma Complete_Representation
@unnumberedsec Pragma Complete_Representation
@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.
+where @var{T} is a limited record type imported from C++ with pragma
+@code{Import} and @code{Convention} = @code{CPP}.
-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
-
-@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
Note that certain signals on many operating systems cannot be caught and
handled by applications. In such cases, the pragma is ignored. See the
operating system documentation, or the value of the array @code{Reserved}
-declared in the specification of package @code{System.OS_Interface}.
+declared in the spec of package @code{System.OS_Interface}.
Overriding the default state of signals used by the Ada runtime may interfere
with an application's runtime behavior in the cases of the synchronous signals,
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
+@findex Optimize_Alignment
+@cindex Alignment, default settings
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Optimize_Alignment (TIME | SPACE | OFF);
+@end smallexample
+
+@noindent
+This is a configuration pragma which affects the choice of default alignments
+for types where no alignment is explicitly specified. There is a time/space
+trade-off in the selection of these values. Large alignments result in more
+efficient code, at the expense of larger data space, since sizes have to be
+increased to match these alignments. Smaller alignments save space, but the
+access code is slower. The normal choice of default alignments (which is what
+you get if you do not use this pragma, or if you use an argument of OFF),
+tries to balance these two requirements.
+
+Specifying SPACE causes smaller default alignments to be chosen in two cases.
+First any packed record is given an alignment of 1. Second, if a size is given
+for the type, then the alignment is chosen to avoid increasing this size. For
+example, consider:
+
+@smallexample @c ada
+ type R is record
+ X : Integer;
+ Y : Character;
+ end record;
+
+ for R'Size use 5*8;
+@end smallexample
+
+@noindent
+In the default mode, this type gets an alignment of 4, so that access to the
+Integer field X are efficient. But this means that objects of the type end up
+with a size of 8 bytes. This is a valid choice, since sizes of objects are
+allowed to be bigger than the size of the type, but it can waste space if for
+example fields of type R appear in an enclosing record. If the above type is
+compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
+
+Specifying TIME causes larger default alignments to be chosen in the case of
+small types with sizes that are not a power of 2. For example, consider:
+
+@smallexample @c ada
+ type R is record
+ A : Character;
+ B : Character;
+ C : Boolean;
+ end record;
+
+ pragma Pack (R);
+ for R'Size use 17;
+@end smallexample
+
+@noindent
+The default alignment for this record is normally 1, but if this type is
+compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
+to 4, which wastes space for objects of the type, since they are now 4 bytes
+long, but results in more efficient access when the whole record is referenced.
+
+As noted above, this is a configuration pragma, and there is a requirement
+that all units in a partition be compiled with a consistent setting of the
+optimization setting. This would normally be achieved by use of a configuration
+pragma file containing the appropriate setting. The exception to this rule is
+that units with an explicit configuration pragma in the same file as the source
+unit are excluded from the consistency check, as are all predefined units. The
+latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
+pragma appears at the start of the file.
@node Pragma Passive
@unnumberedsec Pragma Passive
@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
details.
+@node Pragma Postcondition
+@unnumberedsec Pragma Postcondition
+@cindex Postconditions
+@cindex Checks, postconditions
+@findex Postconditions
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Postcondition (
+ [Check =>] Boolean_Expression
+ [,[Message =>] String_Expression]);
+@end smallexample
+
+@noindent
+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 (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.
+
+@code{Postcondition} 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). In the case of a
+postcondition appearing after a subprogram declaration, the
+formal arguments of the subprogram are visible, and can be
+referenced in the postcondition expressions.
+
+The postconditions are collected and automatically tested just
+before any return (implicit or explicit) in the subprogram body.
+A postcondition is only recognized if postconditions are active
+at the time the pragma is encountered. The compiler switch @option{gnata}
+turns on all postconditions by default, and pragma @code{Check_Policy}
+with an identifier of @code{Postcondition} can also be used to
+control whether postconditions are active.
+
+The general approach is that postconditions are placed in the spec
+if they represent functional aspects which make sense to the client.
+For example we might have:
+
+@smallexample @c ada
+ function Direction return Integer;
+ pragma Postcondition
+ (Direction'Result = +1
+ or else
+ Direction'Result = -1);
+@end smallexample
+
+@noindent
+which serves to document that the result must be +1 or -1, and
+will test that this is the case at run time if postcondition
+checking is active.
+
+Postconditions within the subprogram body can be used to
+check that some internal aspect of the implementation,
+not visible to the client, is operating as expected.
+For instance if a square root routine keeps an internal
+counter of the number of times it is called, then we
+might have the following postcondition:
+
+@smallexample @c ada
+ Sqrt_Calls : Natural := 0;
+
+ function Sqrt (Arg : Float) return Float is
+ pragma Postcondition
+ (Sqrt_Calls = Sqrt_Calls'Old + 1);
+ ...
+ end Sqrt
+@end smallexample
+
+@noindent
+As this example, shows, the use of the @code{Old} attribute
+is often useful in postconditions to refer to the state on
+entry to the subprogram.
+
+Note that postconditions are only checked on normal returns
+from the subprogram. If an abnormal return results from
+raising an exception, then the postconditions are not checked.
+
+If a postcondition fails, then the exception
+@code{System.Assertions.Assert_Failure} is raised. If
+a message argument was supplied, then the given string
+will be used as the exception message. If no message
+argument was supplied, then the default message has
+the form "Postcondition failed at file:line". The
+exception is raised in the context of the subprogram
+body, so it is possible to catch postcondition failures
+within the subprogram body itself.
+
+Within a package spec, normal visibility rules
+in Ada would prevent forward references within a
+postcondition pragma to functions defined later in
+the same package. This would introduce undesirable
+ordering constraints. To avoid this problem, all
+postcondition pragmas are analyzed at the end of
+the package spec, allowing forward references.
+
+The following example shows that this even allows
+mutually recursive postconditions as in:
+
+@smallexample @c ada
+package Parity_Functions is
+ function Odd (X : Natural) return Boolean;
+ pragma Postcondition
+ (Odd'Result =
+ (x = 1
+ or else
+ (x /= 0 and then Even (X - 1))));
+
+ function Even (X : Natural) return Boolean;
+ pragma Postcondition
+ (Even'Result =
+ (x = 0
+ or else
+ (x /= 1 and then Odd (X - 1))));
+
+end Parity_Functions;
+@end smallexample
+
+@noindent
+There are no restrictions on the complexity or form of
+conditions used within @code{Postcondition} pragmas.
+The following example shows that it is even possible
+to verify performance behavior.
+
+@smallexample @c ada
+package Sort is
+
+ Performance : constant Float;
+ -- Performance constant set by implementation
+ -- to match target architecture behavior.
+
+ procedure Treesort (Arg : String);
+ -- Sorts characters of argument using N*logN sort
+ pragma Postcondition
+ (Float (Clock - Clock'Old) <=
+ Float (Arg'Length) *
+ log (Float (Arg'Length)) *
+ Performance);
+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
+@cindex Checks, preconditions
+@findex Preconditions
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Precondition (
+ [Check =>] Boolean_Expression
+ [,[Message =>] String_Expression]);
+@end smallexample
+
+@noindent
+The @code{Precondition} pragma is similar to @code{Postcondition}
+except that the corresponding checks take place immediately upon
+entry to the subprogram, and if a precondition fails, the exception
+is raised in the context of the caller, and the attribute 'Result
+cannot be used within the precondition expression.
+
+Otherwise, the placement and visibility rules are identical to those
+described for postconditions. The following is an example of use
+within a package spec:
+
+@smallexample @c ada
+package Math_Functions is
+ ...
+ function Sqrt (Arg : Float) return Float;
+ pragma Precondition (Arg >= 0.0)
+ ...
+end Math_Functions;
+@end smallexample
+
+@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
no calls to Task_Identification.Abort_Task.
@item No_Asynchronous_Control
-[RM D.7] There are no semantic dependences on the package
+There are no semantic dependences on the package
Asynchronous_Task_Control.
@item No_Calendar
Protected objects and access types that designate
such objects shall be declared only at library level.
+@item No_Local_Timing_Events
+[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
+declared at the library level.
+
@item No_Protected_Type_Allocators
There are no allocators for protected types or
types containing protected subcomponents.
@item No_Select_Statements
There are no select_statements.
+@item No_Specific_Termination_Handlers
+[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
+or to Ada.Task_Termination.Specific_Handler.
+
@item No_Task_Allocators
[RM D.7] There are no allocators for task types
or types containing task subcomponents.
@item No_Task_Termination
Tasks which terminate are erroneous.
+@item No_Unchecked_Conversion
+There are no semantic dependencies on the Ada.Unchecked_Conversion package.
+
+@item No_Unchecked_Deallocation
+There are no semantic dependencies on the Ada.Unchecked_Deallocation package.
+
@item Simple_Barriers
Entry barrier condition expressions shall be either static
boolean expressions or boolean objects which are declared in
This pragma is provided for compatibility with Ada 83. The syntax and
semantics are identical to pragma Atomic.
+@node Pragma Short_Circuit_And_Or
+@unnumberedsec Pragma Short_Circuit_And_Or
+@findex Short_Circuit_And_Or
+
+@noindent
+This configuration pragma causes any occurrence of the AND operator applied to
+operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
+is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
+may be useful in the context of certification protocols requiring the use of
+short-circuited logical operators. If this configuration pragma occurs locally
+within the file being compiled, it applies only to the file being compiled.
+There is no requirement that all units in a partition use this option.
+
+semantics are identical to pragma Atomic.
@node Pragma Source_File_Name
@unnumberedsec Pragma Source_File_Name
@findex Source_File_Name
@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 recompilations 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
aspects of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
-in the specification of package System.Task_Info in the runtime
+in the spec of package System.Task_Info in the runtime
library.
@node Pragma Task_Name
@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
of this pragma is also available by applying the -univ switch on the
compilations of units where universal addressing of the data is desired.
+@node Pragma Unmodified
+@unnumberedsec Pragma Unmodified
+@findex Unmodified
+@cindex Warnings, unmodified
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
+@end smallexample
+
+@noindent
+This pragma signals that the assignable entities (variables,
+@code{out} parameters, @code{in out} parameters) whose names are listed are
+deliberately not assigned in the current source unit. This
+suppresses warnings about the
+entities being referenced but not assigned, and in addition a warning will be
+generated if one of these entities is in fact assigned in the
+same unit as the pragma (or in the corresponding body, or one
+of its subunits).
+
+This is particularly useful for clearly signaling that a particular
+parameter is not modified, even though the spec suggests that it might
+be.
+
@node Pragma Unreferenced
@unnumberedsec Pragma Unreferenced
@findex Unreferenced
a program can then handle the @code{SIGINT} interrupt as it chooses.
For a full list of the interrupts handled in a specific implementation,
-see the source code for the specification of @code{Ada.Interrupts.Names} in
+see the source code for the spec of @code{Ada.Interrupts.Names} in
file @file{a-intnam.ads}. This is a target dependent file that contains the
list of interrupts recognized for a given target. The documentation in
this file also specifies what interrupts are affected by the use of
control over which warnings are active. The string is a list of letters
specifying which warnings are to be activated and which deactivated. The
code for these letters is the same as the string used in the command
-line switch controlling warnings. The following is a brief summary. For
+line switch controlling warnings. For a brief summary, use the gnatmake
+command with no arguments, which will generate usage information containing
+the list of warnings switches supported. For
full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
User's Guide}.
-@smallexample
-a turn on all optional warnings (except d,h,l)
-A turn off all optional warnings
-b turn on warnings for bad fixed value (not multiple of small)
-B turn off warnings for bad fixed value (not multiple of small)
-c turn on warnings for constant conditional
-C turn off warnings for constant conditional
-d turn on warnings for implicit dereference
-D turn off warnings for implicit dereference
-e treat all warnings as errors
-f turn on warnings for unreferenced formal
-F turn off warnings for unreferenced formal
-g turn on warnings for unrecognized pragma
-G turn off warnings for unrecognized pragma
-h turn on warnings for hiding variable
-H turn off warnings for hiding variable
-i turn on warnings for implementation unit
-I turn off warnings for implementation unit
-j turn on warnings for obsolescent (annex J) feature
-J turn off warnings for obsolescent (annex J) feature
-k turn on warnings on constant variable
-K turn off warnings on constant variable
-l turn on warnings for missing elaboration pragma
-L turn off warnings for missing elaboration pragma
-m turn on warnings for variable assigned but not read
-M turn off warnings for variable assigned but not read
-n normal warning mode (cancels -gnatws/-gnatwe)
-o turn on warnings for address clause overlay
-O turn off warnings for address clause overlay
-p turn on warnings for ineffective pragma Inline
-P turn off warnings for ineffective pragma Inline
-q turn on warnings for questionable missing parentheses
-Q turn off warnings for questionable missing parentheses
-r turn on warnings for redundant construct
-R turn off warnings for redundant construct
-s suppress all warnings
-t turn on warnings for tracking deleted code
-T turn off warnings for tracking deleted code
-u turn on warnings for unused entity
-U turn off warnings for unused entity
-v turn on warnings for unassigned variable
-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
-x turn on warnings for export/import
-X turn off warnings for export/import
-y turn on warnings for Ada 2005 incompatibility
-Y turn off warnings for Ada 2005 incompatibility
-z turn on size/align warnings for unchecked conversion
-Z turn off size/align warnings for unchecked conversion
-@end smallexample
-
@noindent
The specified warnings will be in effect until the end of the program
or another pragma Warnings is encountered. The effect of the pragma is
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).
-
-The pattern may start with an asterisk, which matches otherwise unmatched
-characters at the start of the message, and it may also end with an asterisk
-which matches otherwise unmatched characters at the end of the message. For
-example, the string "*alignment*" could be used to match any warnings about
-alignment problems. Within the string, the sequence "*" can be used to match
-any sequence of characters enclosed in quotation marks. No other regular
+warning messages (not including the initial "warning: " tag).
+
+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
expression notations are permitted. All characters other than asterisk in
these three specific cases are treated as literal characters in the match.
In this usage, the pattern string must match in the Off and On pragmas,
and at least one matching warning must be suppressed.
+Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be
+used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
+be useful in checking whether obsolete pragmas in existing programs are hiding
+real problems.
+
@node Pragma Weak_External
@unnumberedsec Pragma Weak_External
@findex Weak_External
* AST_Entry::
* Bit::
* Bit_Position::
+* Compiler_Version::
* Code_Address::
* Default_Bit_Order::
* Elaborated::
* Emax::
* Enabled::
* Enum_Rep::
+* Enum_Val::
* Epsilon::
* Fixed_Value::
* Has_Access_Values::
* Has_Discriminants::
* Img::
* Integer_Value::
+* Invalid_Value::
* Large::
* Machine_Size::
* Mantissa::
* Mechanism_Code::
* Null_Parameter::
* Object_Size::
+* Old::
* Passed_By_Reference::
* Pool_Address::
* Range_Length::
+* Result::
* Safe_Emax::
* Safe_Large::
* Small::
@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
@noindent
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
+the spec 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
integer calculation is done at run time, then the call to @code{Enum_Rep}
may raise @code{Constraint_Error}.
+@node Enum_Val
+@unnumberedsec Enum_Val
+@cindex Representation of enums
+@findex Enum_Val
+@noindent
+For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
+function with the following spec:
+
+@smallexample @c ada
+function @var{S}'Enum_Rep (Arg : @i{Universal_Integer)
+ return @var{S}'Base};
+@end smallexample
+
+@noindent
+The function returns the enumeration value whose representation matches the
+argument, or raises Constraint_Error if no enumeration literal of the type
+has the matching value.
+This will be equal to value of the @code{Val} 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).
+
@node Epsilon
@unnumberedsec Epsilon
@cindex Ada 83 attributes
This attribute is primarily intended for use in implementation of the
standard input-output functions for fixed-point values.
+@node Invalid_Value
+@unnumberedsec Invalid_Value
+@findex Invalid_Value
+@noindent
+For every scalar type S, S'Invalid_Value returns an undefined value of the
+type. If possible this value is an invalid representation for the type. The
+value returned is identical to the value used to initialize an otherwise
+uninitialized value of the type if pragma Initialize_Scalars is used,
+including the ability to modify the value with the binder -Sxx flag and
+relevant environment variables at run time.
+
@node Large
@unnumberedsec Large
@cindex Ada 83 attributes
integer field, and so the default size of record objects for this type
will be 64 (8 bytes).
-The @code{@var{type}'Object_Size} attribute
-has been added to GNAT to allow the
-default object size of a type to be easily determined. For example,
-@code{Natural'Object_Size} is 32, and
-@code{Rec'Object_Size} (for the record type in the above example) will be
-64. Note also that, unlike the situation with the
-@code{Size} attribute as defined in the Ada RM, the
-@code{Object_Size} attribute can be specified individually
-for different subtypes. For example:
+@node Old
+@unnumberedsec Old
+@cindex Capturing Old values
+@cindex Postconditions
+@noindent
+The attribute Prefix'Old can be used within a
+subprogram to refer to the value of the prefix on entry. So for
+example if you have an argument of a record type X called Arg1,
+you can refer to Arg1.Field'Old which yields the value of
+Arg1.Field on entry. The implementation simply involves generating
+an object declaration which captures the value on entry. Any
+prefix is allowed except one of a limited type (since limited
+types cannot be copied to capture their values) or a local variable
+(since it does not exist at subprogram entry time).
+
+The following example shows the use of 'Old to implement
+a test of a postcondition:
@smallexample @c ada
-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;
+with Old_Pkg;
+procedure Old is
+begin
+ Old_Pkg.Incr;
+end Old;
+
+package Old_Pkg is
+ procedure Incr;
+end Old_Pkg;
+
+package body Old_Pkg is
+ Count : Natural := 0;
+
+ procedure Incr is
+ begin
+ ... code manipulating the value of Count
+
+ pragma Assert (Count = Count'Old + 1);
+ end Incr;
+end Old_Pkg;
@end smallexample
@noindent
-In this example, @code{R'Object_Size} and @code{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 @code{R}
-or @code{R1} will
-by default be 32 bits (four bytes). But objects of type
-@code{R2} will be only
-8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
-
-Although @code{Object_Size} does properly reflect the default object size
-value, it is not necessarily the case that all objects will be of this size
-in a case where it is not specified explicitly. The compiler is free to
-increase the size and alignment of stand alone objects to improve efficiency
-of the generated code and sometimes does so in the case of large composite
-objects. If the size of a stand alone object is critical to the
-application, it should be specified explicitly.
+Note that it is allowed to apply 'Old to a constant entity, but this will
+result in a warning, since the old and new values will always be the same.
@node Passed_By_Reference
@unnumberedsec Passed_By_Reference
applied to the index subtype of a one dimensional array always gives the
same result as @code{Range} applied to the array itself.
+@node Result
+@unnumberedsec Result
+@findex Result
+@noindent
+@code{@var{function}'Result} can only be used with in a Postcondition pragma
+for a function. The prefix must be the name of the corresponding function. This
+is used to refer to the result of the function in the postcondition expression.
+For a further discussion of the use of this attribute and examples of its use,
+see the description of pragma Postcondition.
+
@node Safe_Emax
@unnumberedsec Safe_Emax
@cindex Ada 83 attributes
In addition to the implementation dependent pragmas and attributes, and
the implementation advice, there are a number of other Ada features
that are potentially implementation dependent. These are mentioned
-throughout the Ada Reference Manual, and are summarized in annex M@.
+throughout the Ada Reference Manual, and are summarized in Annex M@.
A requirement for conforming Ada compilers is that they provide
documentation describing how the implementation deals with each of these
-issues. In this chapter, you will find each point in annex M listed
+issues. In this chapter, you will find each point in Annex M listed
followed by a description in italic font of how GNAT
@c SGI info:
@ignore
This restriction ensures at compile time that there is no implicit or
explicit dependence on the package @code{Ada.Calendar}.
+@item No_Default_Initialization
+@findex No_Default_Initialization
+
+This restriction prohibits any instance of default initialization of variables.
+The binder implements a consistency rule which prevents any unit compiled
+without the restriction from with'ing a unit with the restriction (this allows
+the generation of initialization procedures to be skipped, since you can be
+sure that no call is ever generated to an initialization procedure in a unit
+with the restriction active). If used in conjunction with Initialize_Scalars or
+Normalize_Scalars, the effect is to prohibit all cases of variables declared
+without a specific initializer (including the case of OUT scalar parameters).
+
@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_Implicit_Dynamic_Code
@findex No_Implicit_Dynamic_Code
+@cindex trampoline
This restriction prevents the compiler from building ``trampolines''.
This is a structure that is built on the stack and contains dynamic
code to be executed at run time. On some targets, a trampoline is
Trampolines do not work on machines that prevent execution of stack
data. For example, on windows systems, enabling DEP (data execution
protection) will cause trampolines to raise an exception.
+Trampolines are also quite slow at run time.
+
+On many targets, trampolines have been largely eliminated. Look at the
+version of system.ads for your target --- if it has
+Always_Compatible_Rep equal to False, then trampolines are largely
+eliminated. In particular, a trampoline is built for the following
+features: @code{Address} of a nested subprogram;
+@code{Access} or @code{Unrestricted_Access} of a nested subprogram,
+but only if pragma Favor_Top_Level applies, or the access type has a
+foreign-language convention; primitive operations of nested tagged
+types.
@item No_Implicit_Loops
@findex No_Implicit_Loops
@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
@end cartouche
@noindent
The string passed to @code{Linker_Options} is presented uninterpreted as
-an argument to the link command, unless it contains Ascii.NUL characters.
+an argument to the link command, unless it contains ASCII.NUL characters.
NUL characters if they appear act as argument separators, so for example
@smallexample @c ada
-pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef");
+pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
@end smallexample
@noindent
@item @emph{Records}.
For the normal non-packed case, the alignment of a record is equal to
the maximum alignment of any of its components. For tagged records, this
-includes the implicit access type used for the tag. If a pragma @code{Pack} is
-used and all fields are packable (see separate section on pragma @code{Pack}),
-then the resulting alignment is 1.
+includes the implicit access type used for the tag. If a pragma @code{Pack}
+is used and all components are packable (see separate section on pragma
+@code{Pack}), then the resulting alignment is 1, unless the layout of the
+record makes it profitable to increase it.
A special case is when:
@itemize @bullet
An alignment clause may specify a larger alignment than the default value
up to some maximum value dependent on the target (obtainable by using the
attribute reference @code{Standard'Maximum_Alignment}). It may also specify
-a smaller alignment than the default value, for example
+a smaller alignment than the default value for enumeration, integer and
+fixed point types, as well as for record types, for example
@smallexample @c ada
type V is record
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).
of this subtype, and must be a multiple of the alignment value.
In addition, component size clauses are allowed which cause the array
-to be packed, by specifying a smaller value. The cases in which this
-is allowed are for component size values in the range 1 through 63. The value
-specified must not be smaller than the Size of the subtype. GNAT will
-accurately honor all packing requests in this range. For example, if
-we have:
+to be packed, by specifying a smaller value. A first case is for
+component size values in the range 1 through 63. The value specified
+must not be smaller than the Size of the subtype. GNAT will accurately
+honor all packing requests in this range. For example, if we have:
@smallexample @c ada
type r is array (1 .. 8) of Natural;
then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
Of course access to the components of such an array is considerably
less efficient than if the natural component size of 32 is used.
+A second case is when the subtype of the component is a record type
+padded because of its default alignment. For example, if we have:
+
+@smallexample @c ada
+type r is record
+ i : Integer;
+ j : Integer;
+ b : Boolean;
+end record;
+
+type a is array (1 .. 8) of r;
+for a'Component_Size use 72;
+@end smallexample
+
+@noindent
+then the resulting array has a length of 72 bytes, instead of 96 bytes
+if the alignment of the record (4) was obeyed.
Note that there is no point in giving both a component size clause
and a pragma Pack for the same array type. if such duplicate
Any type whose size is specified with a size clause
@item
Any packed array type with a static size
+@item
+Any record type padded because of its default alignment
@end itemize
@noindent
@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
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
+* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Command_Line.Response_File (a-clrefi.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
* Ada.Exceptions.Traceback (a-exctra.ads)::
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
+* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
+* Ada.Wide_Characters.Unicode (a-wichun.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
+* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
* GNAT.Altivec (g-altive.ads)::
* GNAT.Altivec.Conversions (g-altcon.ads)::
* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
-* GNAT.CRC32 (g-crc32.ads)::
* GNAT.Case_Util (g-casuti.ads)::
* GNAT.CGI (g-cgi.ads)::
* GNAT.CGI.Cookie (g-cgicoo.ads)::
* GNAT.Command_Line (g-comlin.ads)::
* GNAT.Compiler_Version (g-comver.ads)::
* GNAT.Ctrl_C (g-ctrl_c.ads)::
+* GNAT.CRC32 (g-crc32.ads)::
* GNAT.Current_Exception (g-curexc.ads)::
* GNAT.Debug_Pools (g-debpoo.ads)::
* GNAT.Debug_Utilities (g-debuti.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.Serial_Communications (g-sercom.ads)::
* GNAT.SHA1 (g-sha1.ads)::
+* GNAT.SHA224 (g-sha224.ads)::
+* GNAT.SHA256 (g-sha256.ads)::
+* GNAT.SHA384 (g-sha384.ads)::
+* GNAT.SHA512 (g-sha512.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
* 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)::
* GNAT.Task_Lock (g-tasloc.ads)::
* GNAT.Threads (g-thread.ads)::
+* GNAT.Time_Stamp (g-timsta.ads)::
* GNAT.Traceback (g-traceb.ads)::
* GNAT.Traceback.Symbolic (g-trasym.ads)::
* GNAT.UTF_32 (g-utf_32.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Os2lib (i-os2lib.ads)::
-* Interfaces.Os2lib.Errors (i-os2err.ads)::
-* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
-* Interfaces.Os2lib.Threads (i-os2thr.ads)::
* Interfaces.Packed_Decimal (i-pacdec.ads)::
* Interfaces.VxWorks (i-vxwork.ads)::
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
* System.Assertions (s-assert.ads)::
* System.Memory (s-memory.ads)::
* System.Partition_Interface (s-parint.ads)::
+* System.Pool_Global (s-pooglo.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)::
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
-@node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
+@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
@cindex Latin_1 constants for Wide_Wide_Character
@noindent
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
-@node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
+@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
@cindex Latin_9 constants for Wide_Wide_Character
@noindent
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
+@node Ada.Command_Line.Environment (a-colien.ads)
+@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
+@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
+@cindex Environment entries
+
+@noindent
+This child of @code{Ada.Command_Line}
+provides a mechanism for obtaining environment values on systems
+where this concept makes sense.
+
@node Ada.Command_Line.Remove (a-colire.ads)
@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
to further calls on the subprograms in @code{Ada.Command_Line} will not
see the removed argument.
-@node Ada.Command_Line.Environment (a-colien.ads)
-@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex Environment entries
+@node Ada.Command_Line.Response_File (a-clrefi.ads)
+@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
+@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
+@cindex Response file for command line
+@cindex Command line, response file
+@cindex Command line, handling long command lines
@noindent
-This child of @code{Ada.Command_Line}
-provides a mechanism for obtaining environment values on systems
-where this concept makes sense.
+This child of @code{Ada.Command_Line} provides a mechanism facilities for
+getting command line arguments from a text file, called a "response file".
+Using a response file allow passing a set of arguments to an executable longer
+than the maximum allowed by the system on the command line.
@node Ada.Direct_IO.C_Streams (a-diocst.ads)
@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
exception occurrence (@code{Null_Occurrence}) without raising
an exception.
+@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
+@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
+@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
+@cindex Null_Occurrence, testing for
+
+@noindent
+This child subprogram is used for handling otherwise unhandled
+exceptions (hence the name last chance), and perform clean ups before
+terminating the program. Note that this subprogram never returns.
+
@node Ada.Exceptions.Traceback (a-exctra.ads)
@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
+@section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
+@cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
+@cindex @code{Text_IO} resetting standard files
+
+@noindent
+This procedure is used to reset the status of the standard files used
+by Ada.Text_IO. This is useful in a situation (such as a restart in an
+embedded application) where the status of the files may change during
+execution (for example a standard input file may be redefined to be
+interactive).
+
+@node Ada.Wide_Characters.Unicode (a-wichun.ads)
+@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
+@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
+@cindex Unicode categorization, Wide_Character
+
+@noindent
+This package provides subprograms that allow categorization of
+Wide_Character values according to Unicode categories.
+
@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
+@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
+@cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
+@cindex @code{Wide_Text_IO} resetting standard files
+
+@noindent
+This procedure is used to reset the status of the standard files used
+by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
+embedded application) where the status of the files may change during
+execution (for example a standard input file may be redefined to be
+interactive).
+
+@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
+@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
+@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
+@cindex Unicode categorization, Wide_Wide_Character
+
+@noindent
+This package provides subprograms that allow categorization of
+Wide_Wide_Character values according to Unicode categories.
+
@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
+@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
+@cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
+@cindex @code{Wide_Wide_Text_IO} resetting standard files
+
+@noindent
+This procedure is used to reset the status of the standard files used
+by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
+restart in an embedded application) where the status of the files may
+change during execution (for example a standard input file may be
+redefined to be interactive).
+
@node GNAT.Altivec (g-altive.ads)
@section @code{GNAT.Altivec} (@file{g-altive.ads})
@cindex @code{GNAT.Altivec} (@file{g-altive.ads})
@noindent
Provides classic counting and binary semaphores using protected types.
+@node GNAT.Serial_Communications (g-sercom.ads)
+@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
+@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
+@cindex Serial_Communications
+
+@noindent
+Provides a simple interface to send and receive data over a serial
+port. This is only supported on GNU/Linux and Windows.
+
@node GNAT.SHA1 (g-sha1.ads)
@section @code{GNAT.SHA1} (@file{g-sha1.ads})
@cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
@cindex Secure Hash Algorithm SHA-1
@noindent
-Implements the SHA-1 Secure Hash Algorithm as described in RFC 3174.
+Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
+and RFC 3174.
+
+@node GNAT.SHA224 (g-sha224.ads)
+@section @code{GNAT.SHA224} (@file{g-sha224.ads})
+@cindex @code{GNAT.SHA224} (@file{g-sha224.ads})
+@cindex Secure Hash Algorithm SHA-224
+
+@noindent
+Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3.
+
+@node GNAT.SHA256 (g-sha256.ads)
+@section @code{GNAT.SHA256} (@file{g-sha256.ads})
+@cindex @code{GNAT.SHA256} (@file{g-sha256.ads})
+@cindex Secure Hash Algorithm SHA-256
+
+@noindent
+Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3.
+
+@node GNAT.SHA384 (g-sha384.ads)
+@section @code{GNAT.SHA384} (@file{g-sha384.ads})
+@cindex @code{GNAT.SHA384} (@file{g-sha384.ads})
+@cindex Secure Hash Algorithm SHA-384
+
+@noindent
+Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3.
+
+@node GNAT.SHA512 (g-sha512.ads)
+@section @code{GNAT.SHA512} (@file{g-sha512.ads})
+@cindex @code{GNAT.SHA512} (@file{g-sha512.ads})
+@cindex Secure Hash Algorithm SHA-512
+
+@noindent
+Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3.
@node GNAT.Signals (g-signal.ads)
@section @code{GNAT.Signals} (@file{g-signal.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})
single global task lock. Appropriate for use in situations where contention
between tasks is very rarely expected.
+@node GNAT.Time_Stamp (g-timsta.ads)
+@section @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
+@cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
+@cindex Time stamp
+@cindex Current time
+
+@noindent
+Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
+represents the current date and time in ISO 8601 format. This is a very simple
+routine with minimal code and there are no dependencies on any other unit.
+
@node GNAT.Threads (g-thread.ads)
@section @code{GNAT.Threads} (@file{g-thread.ads})
@cindex @code{GNAT.Threads} (@file{g-thread.ads})
is primarily intended to be used in connection with automated tools
for the generation of C++ interfaces.
-@node Interfaces.Os2lib (i-os2lib.ads)
-@section @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
-@cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
-@cindex Interfacing, to OS/2
-@cindex OS/2 interfacing
-
-@noindent
-This package provides interface definitions to the OS/2 library.
-It is a thin binding which is a direct translation of the
-various @file{<bse@.h>} files.
-
-@node Interfaces.Os2lib.Errors (i-os2err.ads)
-@section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
-@cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
-@cindex OS/2 Error codes
-@cindex Interfacing, to OS/2
-@cindex OS/2 interfacing
-
-@noindent
-This package provides definitions of the OS/2 error codes.
-
-@node Interfaces.Os2lib.Synchronization (i-os2syn.ads)
-@section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
-@cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
-@cindex Interfacing, to OS/2
-@cindex Synchronization, OS/2
-@cindex OS/2 synchronization primitives
-
-@noindent
-This is a child package that provides definitions for interfacing
-to the @code{OS/2} synchronization primitives.
-
-@node Interfaces.Os2lib.Threads (i-os2thr.ads)
-@section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
-@cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
-@cindex Interfacing, to OS/2
-@cindex Thread control, OS/2
-@cindex OS/2 thread interfacing
-
-@noindent
-This is a child package that provides definitions for interfacing
-to the @code{OS/2} thread primitives.
-
@node Interfaces.Packed_Decimal (i-pacdec.ads)
@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
is used primarily in a distribution context when using Annex E
with @code{GLADE}.
+@node System.Pool_Global (s-pooglo.ads)
+@section @code{System.Pool_Global} (@file{s-pooglo.ads})
+@cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
+@cindex Storage pool, global
+@cindex Global storage pool
+
+@noindent
+This package provides a storage pool that is equivalent to the default
+storage pool used for access types for which no pool is specifically
+declared. It uses malloc/free to allocate/free and does not attempt to
+do any automatic reclamation.
+
+@node System.Pool_Local (s-pooloc.ads)
+@section @code{System.Pool_Local} (@file{s-pooloc.ads})
+@cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
+@cindex Storage pool, local
+@cindex Local storage pool
+
+@noindent
+This package provides a storage pool that is intended for use with locally
+defined access types. It uses malloc/free for allocate/free, and maintains
+a list of allocated blocks, so that all storage allocated for the pool can
+be freed automatically when the pool is finalized.
+
@node System.Restrictions (s-restri.ads)
@section @code{System.Restrictions} (@file{s-restri.ads})
@cindex @code{System.Restrictions} (@file{s-restri.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})
@smallexample
package_declaration ::=
- package_specification | package_renaming
+ package_spec | package_renaming
-package_specification ::=
+package_spec ::=
@b{package} package_identifier @b{is}
@{simple_declarative_item@}
@b{end} package_identifier ;
package_identifier ::=
@code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
@code{Linker} | @code{Finder} | @code{Cross_Reference} |
- @code{gnatls} | @code{IDE} | @code{Pretty_Printer}
+ @code{gnatls} | @code{IDE} | @code{Pretty_Printer} | @code{Check}
@end smallexample
@subsection Package Naming
if defined.
@end table
+@subsection package Check
+
+@noindent
+The attributes of package @code{Check}
+specify the checking rule options to be used
+when invoking the checking tool @command{gnatcheck}.
+The following attributes apply to package @code{Check}:
+
+@table @code
+@item Default_switches
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatcheck} on a source
+written in that language. The first string in the range should always be
+@code{"-rules"} to specify that all the other options belong to the
+@code{-rules} section of the parameters of @command{gnatcheck} call.
+
+@end table
+
@subsection package Pretty_Printer
@noindent
OSDN Git Service
