18940 lines
655 KiB
Plaintext
18940 lines
655 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
|
|
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
|
|
@c o
|
|
@c GNAT DOCUMENTATION o
|
|
@c o
|
|
@c G N A T _ RM 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.3 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
|
|
|
|
@settitle GNAT Reference Manual
|
|
|
|
@setchapternewpage odd
|
|
@syncodeindex fn cp
|
|
|
|
@include gcc-common.texi
|
|
|
|
@dircategory GNU Ada tools
|
|
@direntry
|
|
* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title GNAT Reference Manual
|
|
@subtitle GNAT, The GNU Ada Compiler
|
|
@versionsubtitle
|
|
@author AdaCore
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
|
|
@end titlepage
|
|
|
|
@ifnottex
|
|
@node Top, About This Guide, (dir), (dir)
|
|
@top GNAT Reference Manual
|
|
|
|
@noindent
|
|
GNAT Reference Manual
|
|
|
|
@noindent
|
|
GNAT, The GNU Ada Compiler@*
|
|
GCC version @value{version-GCC}@*
|
|
|
|
@noindent
|
|
AdaCore
|
|
|
|
@menu
|
|
* About This Guide::
|
|
* Implementation Defined Pragmas::
|
|
* Implementation Defined Attributes::
|
|
* Implementation Defined Restrictions::
|
|
* Implementation Advice::
|
|
* Implementation Defined Characteristics::
|
|
* Intrinsic Subprograms::
|
|
* Representation Clauses and Pragmas::
|
|
* Standard Library Routines::
|
|
* The Implementation of Standard I/O::
|
|
* The GNAT Library::
|
|
* Interfacing to Other Languages::
|
|
* Specialized Needs Annexes::
|
|
* Implementation of Specific Ada Features::
|
|
* Implementation of Ada 2012 Features::
|
|
* Obsolescent Features::
|
|
* GNU Free Documentation License::
|
|
* Index::
|
|
|
|
--- The Detailed Node Listing ---
|
|
|
|
About This Guide
|
|
|
|
* What This Reference Manual Contains::
|
|
* Related Information::
|
|
|
|
Implementation Defined Pragmas
|
|
|
|
* Pragma Abort_Defer::
|
|
* Pragma Ada_83::
|
|
* Pragma Ada_95::
|
|
* Pragma Ada_05::
|
|
* Pragma Ada_2005::
|
|
* Pragma Ada_12::
|
|
* Pragma Ada_2012::
|
|
* Pragma Annotate::
|
|
* Pragma Assert::
|
|
* Pragma Assertion_Policy::
|
|
* 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 Convention_Identifier::
|
|
* Pragma CPP_Class::
|
|
* Pragma CPP_Constructor::
|
|
* Pragma CPP_Virtual::
|
|
* Pragma CPP_Vtable::
|
|
* Pragma Debug::
|
|
* Pragma Debug_Policy::
|
|
* Pragma Detect_Blocking::
|
|
* Pragma Elaboration_Checks::
|
|
* Pragma Eliminate::
|
|
* Pragma Export_Exception::
|
|
* Pragma Export_Function::
|
|
* Pragma Export_Object::
|
|
* Pragma Export_Procedure::
|
|
* Pragma Export_Value::
|
|
* Pragma Export_Valued_Procedure::
|
|
* Pragma Extend_System::
|
|
* Pragma Extensions_Allowed::
|
|
* Pragma External::
|
|
* Pragma External_Name_Casing::
|
|
* Pragma Fast_Math::
|
|
* Pragma Favor_Top_Level::
|
|
* Pragma Finalize_Storage_Only::
|
|
* Pragma Float_Representation::
|
|
* Pragma Ident::
|
|
* Pragma Implemented::
|
|
* Pragma Implicit_Packing::
|
|
* Pragma Import_Exception::
|
|
* Pragma Import_Function::
|
|
* Pragma Import_Object::
|
|
* Pragma Import_Procedure::
|
|
* Pragma Import_Valued_Procedure::
|
|
* Pragma Initialize_Scalars::
|
|
* Pragma Inline_Always::
|
|
* Pragma Inline_Generic::
|
|
* Pragma Interface::
|
|
* Pragma Interface_Name::
|
|
* Pragma Interrupt_Handler::
|
|
* Pragma Interrupt_State::
|
|
* Pragma Invariant::
|
|
* Pragma Keep_Names::
|
|
* Pragma License::
|
|
* Pragma Link_With::
|
|
* Pragma Linker_Alias::
|
|
* Pragma Linker_Constructor::
|
|
* Pragma Linker_Destructor::
|
|
* Pragma Linker_Section::
|
|
* Pragma Long_Float::
|
|
* Pragma Machine_Attribute::
|
|
* Pragma Main::
|
|
* Pragma Main_Storage::
|
|
* Pragma No_Body::
|
|
* Pragma No_Return::
|
|
* Pragma No_Strict_Aliasing ::
|
|
* Pragma Normalize_Scalars::
|
|
* Pragma Obsolescent::
|
|
* Pragma Optimize_Alignment::
|
|
* Pragma Ordered::
|
|
* Pragma Passive::
|
|
* Pragma Persistent_BSS::
|
|
* Pragma Polling::
|
|
* Pragma Postcondition::
|
|
* Pragma Precondition::
|
|
* Pragma Profile (Ravenscar)::
|
|
* Pragma Profile (Restricted)::
|
|
* Pragma Psect_Object::
|
|
* Pragma Pure_Function::
|
|
* Pragma Remote_Access_Type::
|
|
* Pragma Restriction_Warnings::
|
|
* Pragma Shared::
|
|
* Pragma Short_Circuit_And_Or::
|
|
* Pragma Short_Descriptors::
|
|
* Pragma Simple_Storage_Pool_Type::
|
|
* Pragma Source_File_Name::
|
|
* Pragma Source_File_Name_Project::
|
|
* Pragma Source_Reference::
|
|
* Pragma Static_Elaboration_Desired::
|
|
* Pragma Stream_Convert::
|
|
* Pragma Style_Checks::
|
|
* Pragma Subtitle::
|
|
* Pragma Suppress::
|
|
* Pragma Suppress_All::
|
|
* Pragma Suppress_Exception_Locations::
|
|
* Pragma Suppress_Initialization::
|
|
* Pragma Task_Info::
|
|
* Pragma Task_Name::
|
|
* Pragma Task_Storage::
|
|
* Pragma Test_Case::
|
|
* 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::
|
|
* Pragma Unsuppress::
|
|
* Pragma Use_VADS_Size::
|
|
* Pragma Validity_Checks::
|
|
* Pragma Volatile::
|
|
* Pragma Warnings::
|
|
* Pragma Weak_External::
|
|
* Pragma Wide_Character_Encoding::
|
|
|
|
Implementation Defined Attributes
|
|
|
|
* Abort_Signal::
|
|
* Address_Size::
|
|
* Asm_Input::
|
|
* Asm_Output::
|
|
* AST_Entry::
|
|
* Bit::
|
|
* Bit_Position::
|
|
* Compiler_Version::
|
|
* Code_Address::
|
|
* Default_Bit_Order::
|
|
* Descriptor_Size::
|
|
* Elaborated::
|
|
* Elab_Body::
|
|
* Elab_Spec::
|
|
* Elab_Subp_Body::
|
|
* Emax::
|
|
* Enabled::
|
|
* Enum_Rep::
|
|
* Enum_Val::
|
|
* Epsilon::
|
|
* Fixed_Value::
|
|
* Has_Access_Values::
|
|
* Has_Discriminants::
|
|
* Img::
|
|
* Integer_Value::
|
|
* Invalid_Value::
|
|
* Large::
|
|
* Machine_Size::
|
|
* Mantissa::
|
|
* Max_Interrupt_Priority::
|
|
* Max_Priority::
|
|
* Maximum_Alignment::
|
|
* Mechanism_Code::
|
|
* Null_Parameter::
|
|
* Object_Size::
|
|
* Old::
|
|
* Passed_By_Reference::
|
|
* Pool_Address::
|
|
* Range_Length::
|
|
* Result::
|
|
* Safe_Emax::
|
|
* Safe_Large::
|
|
* Simple_Storage_Pool::
|
|
* Small::
|
|
* Storage_Unit::
|
|
* Stub_Type::
|
|
* System_Allocator_Alignment::
|
|
* Target_Name::
|
|
* Tick::
|
|
* To_Address::
|
|
* Type_Class::
|
|
* UET_Address::
|
|
* Unconstrained_Array::
|
|
* Universal_Literal_String::
|
|
* Unrestricted_Access::
|
|
* VADS_Size::
|
|
* Value_Size::
|
|
* Wchar_T_Size::
|
|
* Word_Size::
|
|
|
|
Implementation Defined Restrictions
|
|
|
|
* Partition-Wide Restrictions::
|
|
* Program Unit Level Restrictions::
|
|
|
|
Partition-Wide Restrictions
|
|
|
|
* Immediate_Reclamation::
|
|
* Max_Asynchronous_Select_Nesting::
|
|
* Max_Entry_Queue_Length::
|
|
* Max_Protected_Entries::
|
|
* Max_Select_Alternatives::
|
|
* Max_Storage_At_Blocking::
|
|
* Max_Task_Entries::
|
|
* Max_Tasks::
|
|
* No_Abort_Statements::
|
|
* No_Access_Parameter_Allocators::
|
|
* No_Access_Subprograms::
|
|
* No_Allocators::
|
|
* No_Anonymous_Allocators::
|
|
* No_Calendar::
|
|
* No_Coextensions::
|
|
* No_Default_Initialization::
|
|
* No_Delay::
|
|
* No_Dependence::
|
|
* No_Direct_Boolean_Operators::
|
|
* No_Dispatch::
|
|
* No_Dispatching_Calls::
|
|
* No_Dynamic_Attachment::
|
|
* No_Dynamic_Priorities::
|
|
* No_Entry_Calls_In_Elaboration_Code::
|
|
* No_Enumeration_Maps::
|
|
* No_Exception_Handlers::
|
|
* No_Exception_Propagation::
|
|
* No_Exception_Registration::
|
|
* No_Exceptions::
|
|
* No_Finalization::
|
|
* No_Fixed_Point::
|
|
* No_Floating_Point::
|
|
* No_Implicit_Conditionals::
|
|
* No_Implicit_Dynamic_Code::
|
|
* No_Implicit_Heap_Allocations::
|
|
* No_Implicit_Loops::
|
|
* No_Initialize_Scalars::
|
|
* No_IO::
|
|
* No_Local_Allocators::
|
|
* No_Local_Protected_Objects::
|
|
* No_Local_Timing_Events::
|
|
* No_Nested_Finalization::
|
|
* No_Protected_Type_Allocators::
|
|
* No_Protected_Types::
|
|
* No_Recursion::
|
|
* No_Reentrancy::
|
|
* No_Relative_Delay::
|
|
* No_Requeue_Statements::
|
|
* No_Secondary_Stack::
|
|
* No_Select_Statements::
|
|
* No_Specific_Termination_Handlers::
|
|
* No_Specification_of_Aspect::
|
|
* No_Standard_Allocators_After_Elaboration::
|
|
* No_Standard_Storage_Pools::
|
|
* No_Stream_Optimizations::
|
|
* No_Streams::
|
|
* No_Task_Allocators::
|
|
* No_Task_Attributes_Package::
|
|
* No_Task_Hierarchy::
|
|
* No_Task_Termination::
|
|
* No_Tasking::
|
|
* No_Terminate_Alternatives::
|
|
* No_Unchecked_Access::
|
|
* Simple_Barriers::
|
|
* Static_Priorities::
|
|
* Static_Storage_Size::
|
|
|
|
Program Unit Level Restrictions
|
|
|
|
* No_Elaboration_Code::
|
|
* No_Entry_Queue::
|
|
* No_Implementation_Aspect_Specifications::
|
|
* No_Implementation_Attributes::
|
|
* No_Implementation_Identifiers::
|
|
* No_Implementation_Pragmas::
|
|
* No_Implementation_Restrictions::
|
|
* No_Implementation_Units::
|
|
* No_Implicit_Aliasing::
|
|
* No_Obsolescent_Features::
|
|
* No_Wide_Characters::
|
|
* SPARK::
|
|
|
|
The Implementation of Standard I/O
|
|
|
|
* Standard I/O Packages::
|
|
* FORM Strings::
|
|
* Direct_IO::
|
|
* Sequential_IO::
|
|
* Text_IO::
|
|
* Wide_Text_IO::
|
|
* Wide_Wide_Text_IO::
|
|
* Stream_IO::
|
|
* Text Translation::
|
|
* Shared Files::
|
|
* Filenames encoding::
|
|
* Open Modes::
|
|
* Operations on C Streams::
|
|
* Interfacing to C Streams::
|
|
|
|
The GNAT Library
|
|
|
|
* 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-chzla1.ads)::
|
|
* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
|
|
* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
|
|
* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
|
|
* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
|
|
* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
|
|
* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
|
|
* Ada.Containers.Formal_Vectors (a-cofove.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.Unbounded.Text_IO (a-suteio.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.Altivec.Vector_Types (g-alvety.ads)::
|
|
* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
|
|
* GNAT.Array_Split (g-arrspl.ads)::
|
|
* GNAT.AWK (g-awk.ads)::
|
|
* GNAT.Bounded_Buffers (g-boubuf.ads)::
|
|
* GNAT.Bounded_Mailboxes (g-boumai.ads)::
|
|
* GNAT.Bubble_Sort (g-bubsor.ads)::
|
|
* GNAT.Bubble_Sort_A (g-busora.ads)::
|
|
* GNAT.Bubble_Sort_G (g-busorg.ads)::
|
|
* GNAT.Byte_Order_Mark (g-byorma.ads)::
|
|
* GNAT.Byte_Swapping (g-bytswa.ads)::
|
|
* GNAT.Calendar (g-calend.ads)::
|
|
* GNAT.Calendar.Time_IO (g-catiio.ads)::
|
|
* GNAT.Case_Util (g-casuti.ads)::
|
|
* GNAT.CGI (g-cgi.ads)::
|
|
* GNAT.CGI.Cookie (g-cgicoo.ads)::
|
|
* GNAT.CGI.Debug (g-cgideb.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.Decode_String (g-decstr.ads)::
|
|
* GNAT.Decode_UTF8_String (g-deutst.ads)::
|
|
* GNAT.Directory_Operations (g-dirope.ads)::
|
|
* GNAT.Directory_Operations.Iteration (g-diopit.ads)::
|
|
* GNAT.Dynamic_HTables (g-dynhta.ads)::
|
|
* GNAT.Dynamic_Tables (g-dyntab.ads)::
|
|
* GNAT.Encode_String (g-encstr.ads)::
|
|
* GNAT.Encode_UTF8_String (g-enutst.ads)::
|
|
* GNAT.Exception_Actions (g-excact.ads)::
|
|
* GNAT.Exception_Traces (g-exctra.ads)::
|
|
* GNAT.Exceptions (g-except.ads)::
|
|
* GNAT.Expect (g-expect.ads)::
|
|
* GNAT.Expect.TTY (g-exptty.ads)::
|
|
* GNAT.Float_Control (g-flocon.ads)::
|
|
* GNAT.Heap_Sort (g-heasor.ads)::
|
|
* GNAT.Heap_Sort_A (g-hesora.ads)::
|
|
* GNAT.Heap_Sort_G (g-hesorg.ads)::
|
|
* GNAT.HTable (g-htable.ads)::
|
|
* GNAT.IO (g-io.ads)::
|
|
* GNAT.IO_Aux (g-io_aux.ads)::
|
|
* GNAT.Lock_Files (g-locfil.ads)::
|
|
* GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
|
|
* GNAT.MBBS_Float_Random (g-mbflra.ads)::
|
|
* GNAT.MD5 (g-md5.ads)::
|
|
* GNAT.Memory_Dump (g-memdum.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.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.Spelling_Checker (g-speche.ads)::
|
|
* GNAT.Spelling_Checker_Generic (g-spchge.ads)::
|
|
* GNAT.Spitbol.Patterns (g-spipat.ads)::
|
|
* GNAT.Spitbol (g-spitbo.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)::
|
|
* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
|
|
* GNAT.Wide_Spelling_Checker (g-wispch.ads)::
|
|
* GNAT.Wide_String_Split (g-wistsp.ads)::
|
|
* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
|
|
* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
|
|
* Interfaces.C.Extensions (i-cexten.ads)::
|
|
* Interfaces.C.Streams (i-cstrea.ads)::
|
|
* Interfaces.CPP (i-cpp.ads)::
|
|
* Interfaces.Packed_Decimal (i-pacdec.ads)::
|
|
* Interfaces.VxWorks (i-vxwork.ads)::
|
|
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
|
|
* System.Address_Image (s-addima.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)::
|
|
|
|
Text_IO
|
|
|
|
* Text_IO Stream Pointer Positioning::
|
|
* Text_IO Reading and Writing Non-Regular Files::
|
|
* Get_Immediate::
|
|
* Treating Text_IO Files as Streams::
|
|
* Text_IO Extensions::
|
|
* Text_IO Facilities for Unbounded Strings::
|
|
|
|
Wide_Text_IO
|
|
|
|
* Wide_Text_IO Stream Pointer Positioning::
|
|
* Wide_Text_IO Reading and Writing Non-Regular Files::
|
|
|
|
Wide_Wide_Text_IO
|
|
|
|
* Wide_Wide_Text_IO Stream Pointer Positioning::
|
|
* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
|
|
|
|
Interfacing to Other Languages
|
|
|
|
* Interfacing to C::
|
|
* Interfacing to C++::
|
|
* Interfacing to COBOL::
|
|
* Interfacing to Fortran::
|
|
* Interfacing to non-GNAT Ada code::
|
|
|
|
Specialized Needs Annexes
|
|
|
|
Implementation of Specific Ada Features
|
|
* Machine Code Insertions::
|
|
* GNAT Implementation of Tasking::
|
|
* GNAT Implementation of Shared Passive Packages::
|
|
* Code Generation for Array Aggregates::
|
|
* The Size of Discriminated Records with Default Discriminants::
|
|
* Strict Conformance to the Ada Reference Manual::
|
|
|
|
Implementation of Ada 2012 Features
|
|
|
|
Obsolescent Features
|
|
|
|
GNU Free Documentation License
|
|
|
|
Index
|
|
@end menu
|
|
|
|
@end ifnottex
|
|
|
|
@node About This Guide
|
|
@unnumbered About This Guide
|
|
|
|
@noindent
|
|
This manual contains useful information in writing programs using the
|
|
@value{EDITION} compiler. It includes information on implementation dependent
|
|
characteristics of @value{EDITION}, including all the information required by
|
|
Annex M of the Ada language standard.
|
|
|
|
@value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
|
|
Ada 83 compatibility mode.
|
|
By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
|
|
but you can override with a compiler switch
|
|
to explicitly specify the language version.
|
|
(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
|
|
@value{EDITION} User's Guide}, for details on these switches.)
|
|
Throughout this manual, references to ``Ada'' without a year suffix
|
|
apply to both the Ada 95 and Ada 2005 versions of the language.
|
|
|
|
Ada is designed to be highly portable.
|
|
In general, a program will have the same effect even when compiled by
|
|
different compilers on different platforms.
|
|
However, since Ada is designed to be used in a
|
|
wide variety of applications, it also contains a number of system
|
|
dependent features to be used in interfacing to the external world.
|
|
@cindex Implementation-dependent features
|
|
@cindex Portability
|
|
|
|
Note: Any program that makes use of implementation-dependent features
|
|
may be non-portable. You should follow good programming practice and
|
|
isolate and clearly document any sections of your program that make use
|
|
of these features in a non-portable manner.
|
|
|
|
@ifset PROEDITION
|
|
For ease of exposition, ``@value{EDITION}'' will be referred to simply as
|
|
``GNAT'' in the remainder of this document.
|
|
@end ifset
|
|
|
|
@menu
|
|
* What This Reference Manual Contains::
|
|
* Conventions::
|
|
* Related Information::
|
|
@end menu
|
|
|
|
@node What This Reference Manual Contains
|
|
@unnumberedsec What This Reference Manual Contains
|
|
|
|
@noindent
|
|
This reference manual contains the following chapters:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
|
|
pragmas, which can be used to extend and enhance the functionality of the
|
|
compiler.
|
|
|
|
@item
|
|
@ref{Implementation Defined Attributes}, lists GNAT
|
|
implementation-dependent attributes, which can be used to extend and
|
|
enhance the functionality of the compiler.
|
|
|
|
@item
|
|
@ref{Implementation Defined Restrictions}, lists GNAT
|
|
implementation-dependent restrictions, which can be used to extend and
|
|
enhance the functionality of the compiler.
|
|
|
|
@item
|
|
@ref{Implementation Advice}, provides information on generally
|
|
desirable behavior which are not requirements that all compilers must
|
|
follow since it cannot be provided on all systems, or which may be
|
|
undesirable on some systems.
|
|
|
|
@item
|
|
@ref{Implementation Defined Characteristics}, provides a guide to
|
|
minimizing implementation dependent features.
|
|
|
|
@item
|
|
@ref{Intrinsic Subprograms}, describes the intrinsic subprograms
|
|
implemented by GNAT, and how they can be imported into user
|
|
application programs.
|
|
|
|
@item
|
|
@ref{Representation Clauses and Pragmas}, describes in detail the
|
|
way that GNAT represents data, and in particular the exact set
|
|
of representation clauses and pragmas that is accepted.
|
|
|
|
@item
|
|
@ref{Standard Library Routines}, provides a listing of packages and a
|
|
brief description of the functionality that is provided by Ada's
|
|
extensive set of standard library routines as implemented by GNAT@.
|
|
|
|
@item
|
|
@ref{The Implementation of Standard I/O}, details how the GNAT
|
|
implementation of the input-output facilities.
|
|
|
|
@item
|
|
@ref{The GNAT Library}, is a catalog of packages that complement
|
|
the Ada predefined library.
|
|
|
|
@item
|
|
@ref{Interfacing to Other Languages}, describes how programs
|
|
written in Ada using GNAT can be interfaced to other programming
|
|
languages.
|
|
|
|
@ref{Specialized Needs Annexes}, describes the GNAT implementation of all
|
|
of the specialized needs annexes.
|
|
|
|
@item
|
|
@ref{Implementation of Specific Ada Features}, discusses issues related
|
|
to GNAT's implementation of machine code insertions, tasking, and several
|
|
other features.
|
|
|
|
@item
|
|
@ref{Implementation of Ada 2012 Features}, describes the status of the
|
|
GNAT implementation of the Ada 2012 language standard.
|
|
|
|
@item
|
|
@ref{Obsolescent Features} documents implementation dependent features,
|
|
including pragmas and attributes, which are considered obsolescent, since
|
|
there are other preferred ways of achieving the same results. These
|
|
obsolescent forms are retained for backwards compatibility.
|
|
|
|
@end itemize
|
|
|
|
@cindex Ada 95 Language Reference Manual
|
|
@cindex Ada 2005 Language Reference Manual
|
|
@noindent
|
|
This reference manual assumes a basic familiarity with the Ada 95 language, as
|
|
described in the International Standard ANSI/ISO/IEC-8652:1995,
|
|
January 1995.
|
|
It does not require knowledge of the new features introduced by Ada 2005,
|
|
(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
|
|
and Amendment 1).
|
|
Both reference manuals are included in the GNAT documentation
|
|
package.
|
|
|
|
@node Conventions
|
|
@unnumberedsec Conventions
|
|
@cindex Conventions, typographical
|
|
@cindex Typographical conventions
|
|
|
|
@noindent
|
|
Following are examples of the typographical and graphic conventions used
|
|
in this guide:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{Functions}, @code{utility program names}, @code{standard names},
|
|
and @code{classes}.
|
|
|
|
@item
|
|
@code{Option flags}
|
|
|
|
@item
|
|
@file{File names}, @samp{button names}, and @samp{field names}.
|
|
|
|
@item
|
|
@code{Variables}, @env{environment variables}, and @var{metasyntactic
|
|
variables}.
|
|
|
|
@item
|
|
@emph{Emphasis}.
|
|
|
|
@item
|
|
[optional information or parameters]
|
|
|
|
@item
|
|
Examples are described by text
|
|
@smallexample
|
|
and then shown this way.
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@noindent
|
|
Commands that are entered by the user are preceded in this manual by the
|
|
characters @samp{$ } (dollar sign followed by space). If your system uses this
|
|
sequence as a prompt, then the commands will appear exactly as you see them
|
|
in the manual. If your system uses some other prompt, then the command will
|
|
appear with the @samp{$} replaced by whatever prompt character you are using.
|
|
|
|
@node Related Information
|
|
@unnumberedsec Related Information
|
|
@noindent
|
|
See the following documents for further information on GNAT:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
|
|
@value{EDITION} User's Guide}, which provides information on how to use the
|
|
GNAT compiler system.
|
|
|
|
@item
|
|
@cite{Ada 95 Reference Manual}, which contains all reference
|
|
material for the Ada 95 programming language.
|
|
|
|
@item
|
|
@cite{Ada 95 Annotated Reference Manual}, which is an annotated version
|
|
of the Ada 95 standard. The annotations describe
|
|
detailed aspects of the design decision, and in particular contain useful
|
|
sections on Ada 83 compatibility.
|
|
|
|
@item
|
|
@cite{Ada 2005 Reference Manual}, which contains all reference
|
|
material for the Ada 2005 programming language.
|
|
|
|
@item
|
|
@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
|
|
of the Ada 2005 standard. The annotations describe
|
|
detailed aspects of the design decision, and in particular contain useful
|
|
sections on Ada 83 and Ada 95 compatibility.
|
|
|
|
@item
|
|
@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
|
|
which contains specific information on compatibility between GNAT and
|
|
DEC Ada 83 systems.
|
|
|
|
@item
|
|
@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
|
|
describes in detail the pragmas and attributes provided by the DEC Ada 83
|
|
compiler system.
|
|
|
|
@end itemize
|
|
|
|
@node Implementation Defined Pragmas
|
|
@chapter Implementation Defined Pragmas
|
|
|
|
@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.
|
|
|
|
In addition, Ada allows implementations to define additional pragmas
|
|
whose meaning is defined by the implementation. GNAT provides a number
|
|
of these implementation-defined pragmas, which can be used to extend
|
|
and enhance the functionality of the compiler. This section of the GNAT
|
|
Reference Manual describes these additional pragmas.
|
|
|
|
Note that any program using these pragmas might not be portable to other
|
|
compilers (although GNAT implements this set of pragmas on all
|
|
platforms). Therefore if portability to other compilers is an important
|
|
consideration, the use of these pragmas should be minimized.
|
|
|
|
@menu
|
|
* Pragma Abort_Defer::
|
|
* Pragma Ada_83::
|
|
* Pragma Ada_95::
|
|
* Pragma Ada_05::
|
|
* Pragma Ada_2005::
|
|
* Pragma Ada_12::
|
|
* Pragma Ada_2012::
|
|
* Pragma Annotate::
|
|
* Pragma Assert::
|
|
* Pragma Assertion_Policy::
|
|
* 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 Convention_Identifier::
|
|
* Pragma CPP_Class::
|
|
* Pragma CPP_Constructor::
|
|
* Pragma CPP_Virtual::
|
|
* Pragma CPP_Vtable::
|
|
* Pragma Debug::
|
|
* Pragma Debug_Policy::
|
|
* Pragma Detect_Blocking::
|
|
* Pragma Elaboration_Checks::
|
|
* Pragma Eliminate::
|
|
* Pragma Export_Exception::
|
|
* Pragma Export_Function::
|
|
* Pragma Export_Object::
|
|
* Pragma Export_Procedure::
|
|
* Pragma Export_Value::
|
|
* Pragma Export_Valued_Procedure::
|
|
* Pragma Extend_System::
|
|
* Pragma Extensions_Allowed::
|
|
* Pragma External::
|
|
* Pragma External_Name_Casing::
|
|
* Pragma Fast_Math::
|
|
* Pragma Favor_Top_Level::
|
|
* Pragma Finalize_Storage_Only::
|
|
* Pragma Float_Representation::
|
|
* Pragma Ident::
|
|
* Pragma Implemented::
|
|
* Pragma Implicit_Packing::
|
|
* Pragma Import_Exception::
|
|
* Pragma Import_Function::
|
|
* Pragma Import_Object::
|
|
* Pragma Import_Procedure::
|
|
* Pragma Import_Valued_Procedure::
|
|
* Pragma Initialize_Scalars::
|
|
* Pragma Inline_Always::
|
|
* Pragma Inline_Generic::
|
|
* Pragma Interface::
|
|
* Pragma Interface_Name::
|
|
* Pragma Interrupt_Handler::
|
|
* Pragma Interrupt_State::
|
|
* Pragma Invariant::
|
|
* Pragma Keep_Names::
|
|
* Pragma License::
|
|
* Pragma Link_With::
|
|
* Pragma Linker_Alias::
|
|
* Pragma Linker_Constructor::
|
|
* Pragma Linker_Destructor::
|
|
* Pragma Linker_Section::
|
|
* Pragma Long_Float::
|
|
* Pragma Machine_Attribute::
|
|
* Pragma Main::
|
|
* Pragma Main_Storage::
|
|
* Pragma No_Body::
|
|
* Pragma No_Return::
|
|
* Pragma No_Strict_Aliasing::
|
|
* Pragma Normalize_Scalars::
|
|
* Pragma Obsolescent::
|
|
* Pragma Optimize_Alignment::
|
|
* Pragma Ordered::
|
|
* Pragma Passive::
|
|
* Pragma Persistent_BSS::
|
|
* Pragma Polling::
|
|
* Pragma Postcondition::
|
|
* Pragma Precondition::
|
|
* Pragma Profile (Ravenscar)::
|
|
* Pragma Profile (Restricted)::
|
|
* Pragma Psect_Object::
|
|
* Pragma Pure_Function::
|
|
* Pragma Remote_Access_Type::
|
|
* Pragma Restriction_Warnings::
|
|
* Pragma Shared::
|
|
* Pragma Short_Circuit_And_Or::
|
|
* Pragma Short_Descriptors::
|
|
* Pragma Simple_Storage_Pool_Type::
|
|
* Pragma Source_File_Name::
|
|
* Pragma Source_File_Name_Project::
|
|
* Pragma Source_Reference::
|
|
* Pragma Static_Elaboration_Desired::
|
|
* Pragma Stream_Convert::
|
|
* Pragma Style_Checks::
|
|
* Pragma Subtitle::
|
|
* Pragma Suppress::
|
|
* Pragma Suppress_All::
|
|
* Pragma Suppress_Exception_Locations::
|
|
* Pragma Suppress_Initialization::
|
|
* Pragma Task_Info::
|
|
* Pragma Task_Name::
|
|
* Pragma Task_Storage::
|
|
* Pragma Test_Case::
|
|
* 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::
|
|
* Pragma Unsuppress::
|
|
* Pragma Use_VADS_Size::
|
|
* Pragma Validity_Checks::
|
|
* Pragma Volatile::
|
|
* Pragma Warnings::
|
|
* Pragma Weak_External::
|
|
* Pragma Wide_Character_Encoding::
|
|
@end menu
|
|
|
|
@node Pragma Abort_Defer
|
|
@unnumberedsec Pragma Abort_Defer
|
|
@findex Abort_Defer
|
|
@cindex Deferring aborts
|
|
@noindent
|
|
Syntax:
|
|
@smallexample
|
|
pragma Abort_Defer;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma must appear at the start of the statement sequence of a
|
|
handled sequence of statements (right after the @code{begin}). It has
|
|
the effect of deferring aborts for the sequence of statements (but not
|
|
for the declarations or handlers, if any, associated with this statement
|
|
sequence).
|
|
|
|
@node Pragma Ada_83
|
|
@unnumberedsec Pragma Ada_83
|
|
@findex Ada_83
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_83;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes Ada 83 mode for the unit to
|
|
which it applies, regardless of the mode set by the command line
|
|
switches. In Ada 83 mode, GNAT attempts to be as compatible with
|
|
the syntax and semantics of Ada 83, as defined in the original Ada
|
|
83 Reference Manual as possible. In particular, the keywords added by Ada 95
|
|
and Ada 2005 are not recognized, optional package bodies are allowed,
|
|
and generics may name types with unknown discriminants without using
|
|
the @code{(<>)} notation. In addition, some but not all of the additional
|
|
restrictions of Ada 83 are enforced.
|
|
|
|
Ada 83 mode is intended for two purposes. Firstly, it allows existing
|
|
Ada 83 code to be compiled and adapted to GNAT with less effort.
|
|
Secondly, it aids in keeping code backwards compatible with Ada 83.
|
|
However, there is no guarantee that code that is processed correctly
|
|
by GNAT in Ada 83 mode will in fact compile and execute with an Ada
|
|
83 compiler, since GNAT does not enforce all the additional checks
|
|
required by Ada 83.
|
|
|
|
@node Pragma Ada_95
|
|
@unnumberedsec Pragma Ada_95
|
|
@findex Ada_95
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_95;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes Ada 95 mode for the unit to which
|
|
it applies, regardless of the mode set by the command line switches.
|
|
This mode is set automatically for the @code{Ada} and @code{System}
|
|
packages and their children, so you need not specify it in these
|
|
contexts. This pragma is useful when writing a reusable component that
|
|
itself uses Ada 95 features, but which is intended to be usable from
|
|
either Ada 83 or Ada 95 programs.
|
|
|
|
@node Pragma Ada_05
|
|
@unnumberedsec Pragma Ada_05
|
|
@findex Ada_05
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_05;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes Ada 2005 mode for the unit to which
|
|
it applies, regardless of the mode set by the command line switches.
|
|
This pragma is useful when writing a reusable component that
|
|
itself uses Ada 2005 features, but which is intended to be usable from
|
|
either Ada 83 or Ada 95 programs.
|
|
|
|
@node Pragma Ada_2005
|
|
@unnumberedsec Pragma Ada_2005
|
|
@findex Ada_2005
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_2005;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This configuration pragma is a synonym for pragma Ada_05 and has the
|
|
same syntax and effect.
|
|
|
|
@node Pragma Ada_12
|
|
@unnumberedsec Pragma Ada_12
|
|
@findex Ada_12
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_12;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes Ada 2012 mode for the unit to which
|
|
it applies, regardless of the mode set by the command line switches.
|
|
This mode is set automatically for the @code{Ada} and @code{System}
|
|
packages and their children, so you need not specify it in these
|
|
contexts. This pragma is useful when writing a reusable component that
|
|
itself uses Ada 2012 features, but which is intended to be usable from
|
|
Ada 83, Ada 95, or Ada 2005 programs.
|
|
|
|
@node Pragma Ada_2012
|
|
@unnumberedsec Pragma Ada_2012
|
|
@findex Ada_2005
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Ada_2012;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This configuration pragma is a synonym for pragma Ada_12 and has the
|
|
same syntax and effect.
|
|
|
|
@node Pragma Annotate
|
|
@unnumberedsec Pragma Annotate
|
|
@findex Annotate
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
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 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
|
|
by any part of the GNAT compiler, except to generate corresponding note
|
|
lines in the generated ALI file. For the format of these note lines, see
|
|
the compiler source file lib-writ.ads. This pragma is intended for use by
|
|
external tools, including ASIS@. The use of pragma Annotate does not
|
|
affect the compilation process in any way. This pragma may be used as
|
|
a configuration pragma.
|
|
|
|
@node Pragma Assert
|
|
@unnumberedsec Pragma Assert
|
|
@findex Assert
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Assert (
|
|
boolean_EXPRESSION
|
|
[, string_EXPRESSION]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The effect of this pragma depends on whether the corresponding command
|
|
line switch is set to activate assertions. The pragma expands into code
|
|
equivalent to the following:
|
|
|
|
@smallexample @c ada
|
|
if assertions-enabled then
|
|
if not boolean_EXPRESSION then
|
|
System.Assertions.Raise_Assert_Failure
|
|
(string_EXPRESSION);
|
|
end if;
|
|
end if;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The string argument, if given, is the message that will be associated
|
|
with the exception occurrence if the exception is raised. If no second
|
|
argument is given, the default message is @samp{@var{file}:@var{nnn}},
|
|
where @var{file} is the name of the source file containing the assert,
|
|
and @var{nnn} is the line number of the assert. A pragma is not a
|
|
statement, so if a statement sequence contains nothing but a pragma
|
|
assert, then a null statement is required in addition, as in:
|
|
|
|
@smallexample @c ada
|
|
@dots{}
|
|
if J > 3 then
|
|
pragma Assert (K > 3, "Bad value for K");
|
|
null;
|
|
end if;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note that, as with the @code{if} statement to which it is equivalent, the
|
|
type of the expression is either @code{Standard.Boolean}, or any type derived
|
|
from this standard type.
|
|
|
|
If assertions are disabled (switch @option{-gnata} not used), then there
|
|
is no run-time effect (and in particular, any side effects from the
|
|
expression will not occur at run time). (The expression is still
|
|
analyzed at compile time, and may cause types to be frozen if they are
|
|
mentioned here for the first time).
|
|
|
|
If assertions are enabled, then the given expression is tested, and if
|
|
it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
|
|
which results in the raising of @code{Assert_Failure} with the given message.
|
|
|
|
You should generally avoid side effects in the expression arguments of
|
|
this pragma, because these side effects will turn on and off with the
|
|
setting of the assertions mode, resulting in assertions that have an
|
|
effect on the program. However, the expressions are analyzed for
|
|
semantic correctness whether or not assertions are enabled, so turning
|
|
assertions on and off cannot affect the legality of a program.
|
|
|
|
Note that the implementation defined policy @code{DISABLE}, given in a
|
|
pragma Assertion_Policy, can be used to suppress this semantic analysis.
|
|
|
|
Note: this is a standard language-defined pragma in versions
|
|
of Ada from 2005 on. In GNAT, it is implemented in all versions
|
|
of Ada, and the DISABLE policy is an implementation-defined
|
|
addition.
|
|
|
|
|
|
@node Pragma Assertion_Policy
|
|
@unnumberedsec Pragma Assertion_Policy
|
|
@findex Debug_Policy
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Assertion_Policy (CHECK | DISABLE | IGNORE);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the argument is @code{CHECK}, then pragma @code{Assert} is enabled.
|
|
If the argument is @code{IGNORE}, then pragma @code{Assert} is ignored.
|
|
This pragma overrides the effect of the @option{-gnata} switch on the
|
|
command line.
|
|
|
|
The implementation defined policy @code{DISABLE} is like
|
|
@code{IGNORE} except that it completely disables semantic
|
|
checking of the argument to @code{pragma Assert}. This may
|
|
be useful when the pragma argument references subprograms
|
|
in a with'ed package which is replaced by a dummy package
|
|
for the final build.
|
|
|
|
Note: this is a standard language-defined pragma in versions
|
|
of Ada from 2005 on. In GNAT, it is implemented in all versions
|
|
of Ada, and the DISABLE policy is an implementation-defined
|
|
addition.
|
|
|
|
@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
|
|
@findex Ast_Entry
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma AST_Entry (entry_IDENTIFIER);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is implemented only in the OpenVMS implementation of GNAT@. The
|
|
argument is the simple name of a single entry; at most one @code{AST_Entry}
|
|
pragma is allowed for any given entry. This pragma must be used in
|
|
conjunction with the @code{AST_Entry} attribute, and is only allowed after
|
|
the entry declaration and in the same task type specification or single task
|
|
as the entry to which it applies. This pragma specifies that the given entry
|
|
may be used to handle an OpenVMS asynchronous system trap (@code{AST})
|
|
resulting from an OpenVMS system service call. The pragma does not affect
|
|
normal use of the entry. For further details on this pragma, see the
|
|
DEC Ada Language Reference Manual, section 9.12a.
|
|
|
|
@node Pragma C_Pass_By_Copy
|
|
@unnumberedsec Pragma C_Pass_By_Copy
|
|
@cindex Passing by copy
|
|
@findex C_Pass_By_Copy
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma C_Pass_By_Copy
|
|
([Max_Size =>] static_integer_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Normally the default mechanism for passing C convention records to C
|
|
convention subprograms is to pass them by reference, as suggested by RM
|
|
B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
|
|
this default, by requiring that record formal parameters be passed by
|
|
copy if all of the following conditions are met:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The size of the record type does not exceed the value specified for
|
|
@code{Max_Size}.
|
|
@item
|
|
The record type has @code{Convention C}.
|
|
@item
|
|
The formal parameter has this record type, and the subprogram has a
|
|
foreign (non-Ada) convention.
|
|
@end itemize
|
|
|
|
@noindent
|
|
If these conditions are met the argument is passed by copy, i.e.@: in a
|
|
manner consistent with what C expects if the corresponding formal in the
|
|
C prototype is a struct (rather than a pointer to a struct).
|
|
|
|
You can also pass records by copy by specifying the convention
|
|
@code{C_Pass_By_Copy} for the record type, or by using the extended
|
|
@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
|
|
@cindex Check names, defining
|
|
@findex Check_Name
|
|
@noindent
|
|
Syntax:
|
|
@smallexample @c ada
|
|
pragma Check_Name (check_name_IDENTIFIER);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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 or more configuration pragmas
|
|
are present in a partition mentioning the same name, only one new
|
|
check name is introduced.
|
|
|
|
An implementation defined check name introduced with this pragma may
|
|
be used in only three contexts: @code{pragma Suppress},
|
|
@code{pragma Unsuppress},
|
|
and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
|
|
any of these three cases, the check name must be visible. A check
|
|
name is visible if it is in the configuration pragmas applying to
|
|
the current unit, or if it appears at the start of any unit that
|
|
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 | DISABLE | 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.
|
|
|
|
The implementation defined policy @code{DISABLE} is like
|
|
@code{OFF} except that it completely disables semantic
|
|
checking of the argument to the corresponding class of
|
|
pragmas. This may be useful when the pragma arguments reference
|
|
subprograms in a with'ed package which is replaced by a dummy package
|
|
for the final build.
|
|
|
|
@node Pragma Comment
|
|
@unnumberedsec Pragma Comment
|
|
@findex Comment
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Comment (static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is almost identical in effect to pragma @code{Ident}. It allows the
|
|
placement of a comment into the object file and hence into the
|
|
executable file if the operating system permits such usage. The
|
|
difference is that @code{Comment}, unlike @code{Ident}, has
|
|
no limitations on placement of the pragma (it can be placed
|
|
anywhere in the main source unit), and if more than one pragma
|
|
is used, all comments are retained.
|
|
|
|
@node Pragma Common_Object
|
|
@unnumberedsec Pragma Common_Object
|
|
@findex Common_Object
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Common_Object (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Size =>] EXTERNAL_SYMBOL] );
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma enables the shared use of variables stored in overlaid
|
|
linker areas corresponding to the use of @code{COMMON}
|
|
in Fortran. The single
|
|
object @var{LOCAL_NAME} is assigned to the area designated by
|
|
the @var{External} argument.
|
|
You may define a record to correspond to a series
|
|
of fields. The @var{Size} argument
|
|
is syntax checked in GNAT, but otherwise ignored.
|
|
|
|
@code{Common_Object} is not supported on all platforms. If no
|
|
support is available, then the code generator will issue a message
|
|
indicating that the necessary attribute for implementation of this
|
|
pragma is not available.
|
|
|
|
@node Pragma Compile_Time_Error
|
|
@unnumberedsec Pragma Compile_Time_Error
|
|
@findex Compile_Time_Error
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Compile_Time_Error
|
|
(boolean_EXPRESSION, static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma can be used to generate additional compile time
|
|
error messages. It
|
|
is particularly useful in generics, where errors can be issued for
|
|
specific problematic instantiations. The first parameter is a boolean
|
|
expression. The pragma is effective only if the value of this expression
|
|
is known at compile time, and has the value True. The set of expressions
|
|
whose values are known at compile time includes all static boolean
|
|
expressions, and also other values which the compiler can determine
|
|
at compile time (e.g., the size of a record type set by an explicit
|
|
size representation clause, or the value of a variable which was
|
|
initialized to a constant and is known not to have been modified).
|
|
If these conditions are met, an error message is generated using
|
|
the value given as the second argument. This string value may contain
|
|
embedded ASCII.LF characters to break the message into multiple lines.
|
|
|
|
@node Pragma Compile_Time_Warning
|
|
@unnumberedsec Pragma Compile_Time_Warning
|
|
@findex Compile_Time_Warning
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Compile_Time_Warning
|
|
(boolean_EXPRESSION, static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Same as pragma Compile_Time_Error, except a warning is issued instead
|
|
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
|
|
@findex Complete_Representation
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Complete_Representation;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma must appear immediately within a record representation
|
|
clause. Typical placements are before the first component clause
|
|
or after the last component clause. The effect is to give an error
|
|
message if any component is missing a component clause. This pragma
|
|
may be used to ensure that a record representation clause is
|
|
complete, and that this invariant is maintained if fields are
|
|
added to the record in the future.
|
|
|
|
@node Pragma Complex_Representation
|
|
@unnumberedsec Pragma Complex_Representation
|
|
@findex Complex_Representation
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Complex_Representation
|
|
([Entity =>] LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @var{Entity} argument must be the name of a record type which has
|
|
two fields of the same floating-point type. The effect of this pragma is
|
|
to force gcc to use the special internal complex representation form for
|
|
this record, which may be more efficient. Note that this may result in
|
|
the code for this type not conforming to standard ABI (application
|
|
binary interface) requirements for the handling of record types. For
|
|
example, in some environments, there is a requirement for passing
|
|
records by pointer, and the use of this pragma may result in passing
|
|
this type in floating-point registers.
|
|
|
|
@node Pragma Component_Alignment
|
|
@unnumberedsec Pragma Component_Alignment
|
|
@cindex Alignments of components
|
|
@findex Component_Alignment
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Component_Alignment (
|
|
[Form =>] ALIGNMENT_CHOICE
|
|
[, [Name =>] type_LOCAL_NAME]);
|
|
|
|
ALIGNMENT_CHOICE ::=
|
|
Component_Size
|
|
| Component_Size_4
|
|
| Storage_Unit
|
|
| Default
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Specifies the alignment of components in array or record types.
|
|
The meaning of the @var{Form} argument is as follows:
|
|
|
|
@table @code
|
|
@findex Component_Size
|
|
@item Component_Size
|
|
Aligns scalar components and subcomponents of the array or record type
|
|
on boundaries appropriate to their inherent size (naturally
|
|
aligned). For example, 1-byte components are aligned on byte boundaries,
|
|
2-byte integer components are aligned on 2-byte boundaries, 4-byte
|
|
integer components are aligned on 4-byte boundaries and so on. These
|
|
alignment rules correspond to the normal rules for C compilers on all
|
|
machines except the VAX@.
|
|
|
|
@findex Component_Size_4
|
|
@item Component_Size_4
|
|
Naturally aligns components with a size of four or fewer
|
|
bytes. Components that are larger than 4 bytes are placed on the next
|
|
4-byte boundary.
|
|
|
|
@findex Storage_Unit
|
|
@item Storage_Unit
|
|
Specifies that array or record components are byte aligned, i.e.@:
|
|
aligned on boundaries determined by the value of the constant
|
|
@code{System.Storage_Unit}.
|
|
|
|
@cindex OpenVMS
|
|
@item Default
|
|
Specifies that array or record components are aligned on default
|
|
boundaries, appropriate to the underlying hardware or operating system or
|
|
both. For OpenVMS VAX systems, the @code{Default} choice is the same as
|
|
the @code{Storage_Unit} choice (byte alignment). For all other systems,
|
|
the @code{Default} choice is the same as @code{Component_Size} (natural
|
|
alignment).
|
|
@end table
|
|
|
|
@noindent
|
|
If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must
|
|
refer to a local record or array type, and the specified alignment
|
|
choice applies to the specified type. The use of
|
|
@code{Component_Alignment} together with a pragma @code{Pack} causes the
|
|
@code{Component_Alignment} pragma to be ignored. The use of
|
|
@code{Component_Alignment} together with a record representation clause
|
|
is only effective for fields not specified by the representation clause.
|
|
|
|
If the @code{Name} parameter is absent, the pragma can be used as either
|
|
a configuration pragma, in which case it applies to one or more units in
|
|
accordance with the normal rules for configuration pragmas, or it can be
|
|
used within a declarative part, in which case it applies to types that
|
|
are declared within this declarative part, or within any nested scope
|
|
within this declarative part. In either case it specifies the alignment
|
|
to be applied to any record or array type which has otherwise standard
|
|
representation.
|
|
|
|
If the alignment for a record or array type is not specified (using
|
|
pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
|
|
clause), the GNAT uses the default alignment as described previously.
|
|
|
|
@node Pragma Convention_Identifier
|
|
@unnumberedsec Pragma Convention_Identifier
|
|
@findex Convention_Identifier
|
|
@cindex Conventions, synonyms
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Convention_Identifier (
|
|
[Name =>] IDENTIFIER,
|
|
[Convention =>] convention_IDENTIFIER);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides a mechanism for supplying synonyms for existing
|
|
convention identifiers. The @code{Name} identifier can subsequently
|
|
be used as a synonym for the given convention in other pragmas (including
|
|
for example pragma @code{Import} or another @code{Convention_Identifier}
|
|
pragma). As an example of the use of this, suppose you had legacy code
|
|
which used Fortran77 as the identifier for Fortran. Then the pragma:
|
|
|
|
@smallexample @c ada
|
|
pragma Convention_Identifier (Fortran77, Fortran);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
would allow the use of the convention identifier @code{Fortran77} in
|
|
subsequent code, avoiding the need to modify the sources. As another
|
|
example, you could use this to parameterize convention requirements
|
|
according to systems. Suppose you needed to use @code{Stdcall} on
|
|
windows systems, and @code{C} on some other system, then you could
|
|
define a convention identifier @code{Library} and use a single
|
|
@code{Convention_Identifier} pragma to specify which convention
|
|
would be used system-wide.
|
|
|
|
@node Pragma CPP_Class
|
|
@unnumberedsec Pragma CPP_Class
|
|
@findex CPP_Class
|
|
@cindex Interfacing with C++
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma CPP_Class ([Entity =>] LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The argument denotes an entity in the current declarative region that is
|
|
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 an error is issued in that case.
|
|
|
|
Pragma @code{CPP_Class} is intended primarily for automatic generation
|
|
using an automatic binding generator tool.
|
|
See @ref{Interfacing to C++} for related information.
|
|
|
|
Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
|
|
for backward compatibility but its functionality is available
|
|
using pragma @code{Import} with @code{Convention} = @code{CPP}.
|
|
|
|
@node Pragma CPP_Constructor
|
|
@unnumberedsec Pragma CPP_Constructor
|
|
@cindex Interfacing with C++
|
|
@findex CPP_Constructor
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma CPP_Constructor ([Entity =>] LOCAL_NAME
|
|
[, [External_Name =>] static_string_EXPRESSION ]
|
|
[, [Link_Name =>] static_string_EXPRESSION ]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma identifies an imported function (imported in the usual way
|
|
with pragma @code{Import}) as corresponding to a C++ constructor. If
|
|
@code{External_Name} and @code{Link_Name} are not specified then the
|
|
@code{Entity} argument is a name that must have been previously mentioned
|
|
in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
|
|
must be of one of the following forms:
|
|
|
|
@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}}
|
|
@end itemize
|
|
|
|
@item
|
|
@code{function @var{Fname} (@dots{}) return @var{T}'Class}
|
|
@end itemize
|
|
|
|
@noindent
|
|
where @var{T} is a limited record type imported from C++ with pragma
|
|
@code{Import} and @code{Convention} = @code{CPP}.
|
|
|
|
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 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++
|
|
@findex CPP_Virtual
|
|
@noindent
|
|
This pragma is now obsolete has has no effect because GNAT generates
|
|
the same object layout than the G++ compiler.
|
|
|
|
See @ref{Interfacing to C++} for related information.
|
|
|
|
@node Pragma CPP_Vtable
|
|
@unnumberedsec Pragma CPP_Vtable
|
|
@cindex Interfacing with C++
|
|
@findex CPP_Vtable
|
|
@noindent
|
|
This pragma is now obsolete has has no effect because GNAT generates
|
|
the same object layout than the G++ compiler.
|
|
|
|
See @ref{Interfacing to C++} for related information.
|
|
|
|
@node Pragma Debug
|
|
@unnumberedsec Pragma Debug
|
|
@findex Debug
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
|
|
|
|
PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
|
|
PROCEDURE_NAME
|
|
| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The procedure call argument has the syntactic form of an expression, meeting
|
|
the syntactic requirements for pragmas.
|
|
|
|
If debug pragmas are not enabled or if the condition is present and evaluates
|
|
to False, this pragma has no effect. If debug pragmas are enabled, the
|
|
semantics of the pragma is exactly equivalent to the procedure call statement
|
|
corresponding to the argument with a terminating semicolon. Pragmas are
|
|
permitted in sequences of declarations, so you can use pragma @code{Debug} to
|
|
intersperse calls to debug procedures in the middle of declarations. Debug
|
|
pragmas can be enabled either by use of the command line switch @option{-gnata}
|
|
or by use of the configuration pragma @code{Debug_Policy}.
|
|
|
|
@node Pragma Debug_Policy
|
|
@unnumberedsec Pragma Debug_Policy
|
|
@findex Debug_Policy
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Debug_Policy (CHECK | DISABLE | IGNORE);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
|
|
If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
|
|
This pragma overrides the effect of the @option{-gnata} switch on the
|
|
command line.
|
|
|
|
The implementation defined policy @code{DISABLE} is like
|
|
@code{IGNORE} except that it completely disables semantic
|
|
checking of the argument to @code{pragma Debug}. This may
|
|
be useful when the pragma argument references subprograms
|
|
in a with'ed package which is replaced by a dummy package
|
|
for the final build.
|
|
|
|
@node Pragma Detect_Blocking
|
|
@unnumberedsec Pragma Detect_Blocking
|
|
@findex Detect_Blocking
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Detect_Blocking;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a configuration pragma that forces the detection of potentially
|
|
blocking operations within a protected operation, and to raise Program_Error
|
|
if that happens.
|
|
|
|
@node Pragma Elaboration_Checks
|
|
@unnumberedsec Pragma Elaboration_Checks
|
|
@cindex Elaboration control
|
|
@findex Elaboration_Checks
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Elaboration_Checks (Dynamic | Static);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a configuration pragma that provides control over the
|
|
elaboration model used by the compilation affected by the
|
|
pragma. If the parameter is @code{Dynamic},
|
|
then the dynamic elaboration
|
|
model described in the Ada Reference Manual is used, as though
|
|
the @option{-gnatE} switch had been specified on the command
|
|
line. If the parameter is @code{Static}, then the default GNAT static
|
|
model is used. This configuration pragma overrides the setting
|
|
of the command line. For full details on the elaboration models
|
|
used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
|
|
gnat_ugn, @value{EDITION} User's Guide}.
|
|
|
|
@node Pragma Eliminate
|
|
@unnumberedsec Pragma Eliminate
|
|
@cindex Elimination of unused subprograms
|
|
@findex Eliminate
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR,
|
|
[Source_Location =>] STRING_LITERAL);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The string literal given for the source location is a string which
|
|
specifies the line number of the occurrence of the entity, using
|
|
the syntax for SOURCE_TRACE given below:
|
|
|
|
@smallexample @c ada
|
|
SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET]
|
|
|
|
LBRACKET ::= [
|
|
RBRACKET ::= ]
|
|
|
|
SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
|
|
|
|
LINE_NUMBER ::= DIGIT @{DIGIT@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Spaces around the colon in a @code{Source_Reference} are optional.
|
|
|
|
The @code{DEFINING_DESIGNATOR} matches the defining designator used in an
|
|
explicit subprogram declaration, where the @code{entity} name in this
|
|
designator appears on the source line specified by the source location.
|
|
|
|
The source trace that is given as the @code{Source_Location} shall obey the
|
|
following rules. The @code{FILE_NAME} is the short name (with no directory
|
|
information) of an Ada source file, given using exactly the required syntax
|
|
for the underlying file system (e.g. case is important if the underlying
|
|
operating system is case sensitive). @code{LINE_NUMBER} gives the line
|
|
number of the occurrence of the @code{entity}
|
|
as a decimal literal without an exponent or point. If an @code{entity} is not
|
|
declared in a generic instantiation (this includes generic subprogram
|
|
instances), the source trace includes only one source reference. If an entity
|
|
is declared inside a generic instantiation, its source trace (when parsing
|
|
from left to right) starts with the source location of the declaration of the
|
|
entity in the generic unit and ends with the source location of the
|
|
instantiation (it is given in square brackets). This approach is recursively
|
|
used in case of nested instantiations: the rightmost (nested most deeply in
|
|
square brackets) element of the source trace is the location of the outermost
|
|
instantiation, the next to left element is the location of the next (first
|
|
nested) instantiation in the code of the corresponding generic unit, and so
|
|
on, and the leftmost element (that is out of any square brackets) is the
|
|
location of the declaration of the entity to eliminate in a generic unit.
|
|
|
|
Note that the @code{Source_Location} argument specifies which of a set of
|
|
similarly named entities is being eliminated, dealing both with overloading,
|
|
and also appearence of the same entity name in different scopes.
|
|
|
|
This pragma indicates that the given entity is not used in the program to be
|
|
compiled and built. The effect of the pragma is to allow the compiler to
|
|
eliminate the code or data associated with the named entity. Any reference to
|
|
an eliminated entity causes a compile-time or link-time error.
|
|
|
|
The intention of pragma @code{Eliminate} is to allow a program to be compiled
|
|
in a system-independent manner, with unused entities eliminated, without
|
|
needing to modify the source text. Normally the required set of
|
|
@code{Eliminate} pragmas is constructed automatically using the gnatelim tool.
|
|
|
|
Any source file change that removes, splits, or
|
|
adds lines may make the set of Eliminate pragmas invalid because their
|
|
@code{Source_Location} argument values may get out of date.
|
|
|
|
Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
|
|
operation. In this case all the subprograms to which the given operation can
|
|
dispatch are considered to be unused (are never called as a result of a direct
|
|
or a dispatching call).
|
|
|
|
@node Pragma Export_Exception
|
|
@unnumberedsec Pragma Export_Exception
|
|
@cindex OpenVMS
|
|
@findex Export_Exception
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Exception (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Form =>] Ada | VMS]
|
|
[, [Code =>] static_integer_EXPRESSION]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is implemented only in the OpenVMS implementation of GNAT@. It
|
|
causes the specified exception to be propagated outside of the Ada program,
|
|
so that it can be handled by programs written in other OpenVMS languages.
|
|
This pragma establishes an external name for an Ada exception and makes the
|
|
name available to the OpenVMS Linker as a global symbol. For further details
|
|
on this pragma, see the
|
|
DEC Ada Language Reference Manual, section 13.9a3.2.
|
|
|
|
@node Pragma Export_Function
|
|
@unnumberedsec Pragma Export_Function
|
|
@cindex Argument passing mechanisms
|
|
@findex Export_Function
|
|
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Function (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Result_Type =>] result_SUBTYPE_MARK]
|
|
[, [Mechanism =>] MECHANISM]
|
|
[, [Result_Mechanism =>] MECHANISM_NAME]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
| ""
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Use this pragma to make a function externally callable and optionally
|
|
provide information on mechanisms to be used for passing parameter and
|
|
result values. We recommend, for the purposes of improving portability,
|
|
this pragma always be used in conjunction with a separate pragma
|
|
@code{Export}, which must precede the pragma @code{Export_Function}.
|
|
GNAT does not require a separate pragma @code{Export}, but if none is
|
|
present, @code{Convention Ada} is assumed, which is usually
|
|
not what is wanted, so it is usually appropriate to use this
|
|
pragma in conjunction with a @code{Export} or @code{Convention}
|
|
pragma that specifies the desired foreign convention.
|
|
Pragma @code{Export_Function}
|
|
(and @code{Export}, if present) must appear in the same declarative
|
|
region as the function to which they apply.
|
|
|
|
@var{internal_name} must uniquely designate the function to which the
|
|
pragma applies. If more than one function name exists of this name in
|
|
the declarative part you must use the @code{Parameter_Types} and
|
|
@code{Result_Type} parameters is mandatory to achieve the required
|
|
unique designation. @var{subtype_mark}s in these parameters must
|
|
exactly match the subtypes in the corresponding function specification,
|
|
using positional notation to match parameters with subtype marks.
|
|
The form with an @code{'Access} attribute can be used to match an
|
|
anonymous access parameter.
|
|
|
|
@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
|
|
string or a static string expressions that evaluates to the null
|
|
string. In this case, no external name is generated. This form
|
|
still allows the specification of parameter mechanisms.
|
|
|
|
@node Pragma Export_Object
|
|
@unnumberedsec Pragma Export_Object
|
|
@findex Export_Object
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Object
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Size =>] EXTERNAL_SYMBOL]
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma designates an object as exported, and apart from the
|
|
extended rules for external symbols, is identical in effect to the use of
|
|
the normal @code{Export} pragma applied to an object. You may use a
|
|
separate Export pragma (and you probably should from the point of view
|
|
of portability), but it is not required. @var{Size} is syntax checked,
|
|
but otherwise ignored by GNAT@.
|
|
|
|
@node Pragma Export_Procedure
|
|
@unnumberedsec Pragma Export_Procedure
|
|
@findex Export_Procedure
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Procedure (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Mechanism =>] MECHANISM]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
| ""
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical to @code{Export_Function} except that it
|
|
applies to a procedure rather than a function and the parameters
|
|
@code{Result_Type} and @code{Result_Mechanism} are not permitted.
|
|
GNAT does not require a separate pragma @code{Export}, but if none is
|
|
present, @code{Convention Ada} is assumed, which is usually
|
|
not what is wanted, so it is usually appropriate to use this
|
|
pragma in conjunction with a @code{Export} or @code{Convention}
|
|
pragma that specifies the desired foreign convention.
|
|
|
|
@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
|
|
string or a static string expressions that evaluates to the null
|
|
string. In this case, no external name is generated. This form
|
|
still allows the specification of parameter mechanisms.
|
|
|
|
@node Pragma Export_Value
|
|
@unnumberedsec Pragma Export_Value
|
|
@findex Export_Value
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Value (
|
|
[Value =>] static_integer_EXPRESSION,
|
|
[Link_Name =>] static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma serves to export a static integer value for external use.
|
|
The first argument specifies the value to be exported. The Link_Name
|
|
argument specifies the symbolic name to be associated with the integer
|
|
value. This pragma is useful for defining a named static value in Ada
|
|
that can be referenced in assembly language units to be linked with
|
|
the application. This pragma is currently supported only for the
|
|
AAMP target and is ignored for other targets.
|
|
|
|
@node Pragma Export_Valued_Procedure
|
|
@unnumberedsec Pragma Export_Valued_Procedure
|
|
@findex Export_Valued_Procedure
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Export_Valued_Procedure (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Mechanism =>] MECHANISM]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
| ""
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical to @code{Export_Procedure} except that the
|
|
first parameter of @var{LOCAL_NAME}, which must be present, must be of
|
|
mode @code{OUT}, and externally the subprogram is treated as a function
|
|
with this parameter as the result of the function. GNAT provides for
|
|
this capability to allow the use of @code{OUT} and @code{IN OUT}
|
|
parameters in interfacing to external functions (which are not permitted
|
|
in Ada functions).
|
|
GNAT does not require a separate pragma @code{Export}, but if none is
|
|
present, @code{Convention Ada} is assumed, which is almost certainly
|
|
not what is wanted since the whole point of this pragma is to interface
|
|
with foreign language functions, so it is usually appropriate to use this
|
|
pragma in conjunction with a @code{Export} or @code{Convention}
|
|
pragma that specifies the desired foreign convention.
|
|
|
|
@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
|
|
string or a static string expressions that evaluates to the null
|
|
string. In this case, no external name is generated. This form
|
|
still allows the specification of parameter mechanisms.
|
|
|
|
@node Pragma Extend_System
|
|
@unnumberedsec Pragma Extend_System
|
|
@cindex @code{system}, extending
|
|
@cindex Dec Ada 83
|
|
@findex Extend_System
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Extend_System ([Name =>] IDENTIFIER);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used to provide backwards compatibility with other
|
|
implementations that extend the facilities of package @code{System}. In
|
|
GNAT, @code{System} contains only the definitions that are present in
|
|
the Ada RM@. However, other implementations, notably the DEC Ada 83
|
|
implementation, provide many extensions to package @code{System}.
|
|
|
|
For each such implementation accommodated by this pragma, GNAT provides a
|
|
package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
|
|
implementation, which provides the required additional definitions. You
|
|
can use this package in two ways. You can @code{with} it in the normal
|
|
way and access entities either by selection or using a @code{use}
|
|
clause. In this case no special processing is required.
|
|
|
|
However, if existing code contains references such as
|
|
@code{System.@var{xxx}} where @var{xxx} is an entity in the extended
|
|
definitions provided in package @code{System}, you may use this pragma
|
|
to extend visibility in @code{System} in a non-standard way that
|
|
provides greater compatibility with the existing code. Pragma
|
|
@code{Extend_System} is a configuration pragma whose single argument is
|
|
the name of the package containing the extended definition
|
|
(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
|
|
control of this pragma will be processed using special visibility
|
|
processing that looks in package @code{System.Aux_@var{xxx}} where
|
|
@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
|
|
package @code{System}, but not found in package @code{System}.
|
|
|
|
You can use this pragma either to access a predefined @code{System}
|
|
extension supplied with the compiler, for example @code{Aux_DEC} or
|
|
you can construct your own extension unit following the above
|
|
definition. Note that such a package is a child of @code{System}
|
|
and thus is considered part of the implementation. To compile
|
|
it you will have to use the appropriate switch for compiling
|
|
system units.
|
|
@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, @value{EDITION} User's Guide},
|
|
for details.
|
|
|
|
@node Pragma Extensions_Allowed
|
|
@unnumberedsec Pragma Extensions_Allowed
|
|
@cindex Ada Extensions
|
|
@cindex GNAT Extensions
|
|
@findex Extensions_Allowed
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Extensions_Allowed (On | Off);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This configuration pragma enables or disables the implementation
|
|
extension mode (the use of Off as a parameter cancels the effect
|
|
of the @option{-gnatX} command switch).
|
|
|
|
In extension mode, the latest version of the Ada language is
|
|
implemented (currently Ada 2012), and in addition a small number
|
|
of GNAT specific extensions are recognized as follows:
|
|
|
|
@table @asis
|
|
@item Constrained attribute for generic objects
|
|
The @code{Constrained} attribute is permitted for objects of
|
|
generic types. The result indicates if the corresponding actual
|
|
is constrained.
|
|
|
|
@end table
|
|
|
|
@node Pragma External
|
|
@unnumberedsec Pragma External
|
|
@findex External
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma External (
|
|
[ Convention =>] convention_IDENTIFIER,
|
|
[ Entity =>] LOCAL_NAME
|
|
[, [External_Name =>] static_string_EXPRESSION ]
|
|
[, [Link_Name =>] static_string_EXPRESSION ]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical in syntax and semantics to pragma
|
|
@code{Export} as defined in the Ada Reference Manual. It is
|
|
provided for compatibility with some Ada 83 compilers that
|
|
used this pragma for exactly the same purposes as pragma
|
|
@code{Export} before the latter was standardized.
|
|
|
|
@node Pragma External_Name_Casing
|
|
@unnumberedsec Pragma External_Name_Casing
|
|
@cindex Dec Ada 83 casing compatibility
|
|
@cindex External Names, casing
|
|
@cindex Casing of External names
|
|
@findex External_Name_Casing
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma External_Name_Casing (
|
|
Uppercase | Lowercase
|
|
[, Uppercase | Lowercase | As_Is]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides control over the casing of external names associated
|
|
with Import and Export pragmas. There are two cases to consider:
|
|
|
|
@table @asis
|
|
@item Implicit external names
|
|
Implicit external names are derived from identifiers. The most common case
|
|
arises when a standard Ada Import or Export pragma is used with only two
|
|
arguments, as in:
|
|
|
|
@smallexample @c ada
|
|
pragma Import (C, C_Routine);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Since Ada is a case-insensitive language, the spelling of the identifier in
|
|
the Ada source program does not provide any information on the desired
|
|
casing of the external name, and so a convention is needed. In GNAT the
|
|
default treatment is that such names are converted to all lower case
|
|
letters. This corresponds to the normal C style in many environments.
|
|
The first argument of pragma @code{External_Name_Casing} can be used to
|
|
control this treatment. If @code{Uppercase} is specified, then the name
|
|
will be forced to all uppercase letters. If @code{Lowercase} is specified,
|
|
then the normal default of all lower case letters will be used.
|
|
|
|
This same implicit treatment is also used in the case of extended DEC Ada 83
|
|
compatible Import and Export pragmas where an external name is explicitly
|
|
specified using an identifier rather than a string.
|
|
|
|
@item Explicit external names
|
|
Explicit external names are given as string literals. The most common case
|
|
arises when a standard Ada Import or Export pragma is used with three
|
|
arguments, as in:
|
|
|
|
@smallexample @c ada
|
|
pragma Import (C, C_Routine, "C_routine");
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In this case, the string literal normally provides the exact casing required
|
|
for the external name. The second argument of pragma
|
|
@code{External_Name_Casing} may be used to modify this behavior.
|
|
If @code{Uppercase} is specified, then the name
|
|
will be forced to all uppercase letters. If @code{Lowercase} is specified,
|
|
then the name will be forced to all lowercase letters. A specification of
|
|
@code{As_Is} provides the normal default behavior in which the casing is
|
|
taken from the string provided.
|
|
@end table
|
|
|
|
@noindent
|
|
This pragma may appear anywhere that a pragma is valid. In particular, it
|
|
can be used as a configuration pragma in the @file{gnat.adc} file, in which
|
|
case it applies to all subsequent compilations, or it can be used as a program
|
|
unit pragma, in which case it only applies to the current unit, or it can
|
|
be used more locally to control individual Import/Export pragmas.
|
|
|
|
It is primarily intended for use with OpenVMS systems, where many
|
|
compilers convert all symbols to upper case by default. For interfacing to
|
|
such compilers (e.g.@: the DEC C compiler), it may be convenient to use
|
|
the pragma:
|
|
|
|
@smallexample @c ada
|
|
pragma External_Name_Casing (Uppercase, Uppercase);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
to enforce the upper casing of all external symbols.
|
|
|
|
@node Pragma Fast_Math
|
|
@unnumberedsec Pragma Fast_Math
|
|
@findex Fast_Math
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Fast_Math;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a configuration pragma which activates a mode in which speed is
|
|
considered more important for floating-point operations than absolutely
|
|
accurate adherence to the requirements of the standard. Currently the
|
|
following operations are affected:
|
|
|
|
@table @asis
|
|
@item Complex Multiplication
|
|
The normal simple formula for complex multiplication can result in intermediate
|
|
overflows for numbers near the end of the range. The Ada standard requires that
|
|
this situation be detected and corrected by scaling, but in Fast_Math mode such
|
|
cases will simply result in overflow. Note that to take advantage of this you
|
|
must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
|
|
under control of the pragma, rather than use the preinstantiated versions.
|
|
@end table
|
|
|
|
@node Pragma Favor_Top_Level
|
|
@unnumberedsec Pragma Favor_Top_Level
|
|
@findex Favor_Top_Level
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Favor_Top_Level (type_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The named type must be an access-to-subprogram type. This pragma is an
|
|
efficiency hint to the compiler, regarding the use of 'Access or
|
|
'Unrestricted_Access on nested (non-library-level) subprograms. The
|
|
pragma means that nested subprograms are not used with this type, or
|
|
are rare, so that the generated code should be efficient in the
|
|
top-level case. When this pragma is used, dynamically generated
|
|
trampolines may be used on some targets for nested subprograms.
|
|
See also the No_Implicit_Dynamic_Code restriction.
|
|
|
|
@node Pragma Finalize_Storage_Only
|
|
@unnumberedsec Pragma Finalize_Storage_Only
|
|
@findex Finalize_Storage_Only
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma allows the compiler not to emit a Finalize call for objects
|
|
defined at the library level. This is mostly useful for types where
|
|
finalization is only used to deal with storage reclamation since in most
|
|
environments it is not necessary to reclaim memory just before terminating
|
|
execution, hence the name.
|
|
|
|
@node Pragma Float_Representation
|
|
@unnumberedsec Pragma Float_Representation
|
|
@cindex OpenVMS
|
|
@findex Float_Representation
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
|
|
|
|
FLOAT_REP ::= VAX_Float | IEEE_Float
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In the one argument form, this pragma is a configuration pragma which
|
|
allows control over the internal representation chosen for the predefined
|
|
floating point types declared in the packages @code{Standard} and
|
|
@code{System}. On all systems other than OpenVMS, the argument must
|
|
be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
|
|
argument may be @code{VAX_Float} to specify the use of the VAX float
|
|
format for the floating-point types in Standard. This requires that
|
|
the standard runtime libraries be recompiled.
|
|
|
|
The two argument form specifies the representation to be used for
|
|
the specified floating-point type. On all systems other than OpenVMS,
|
|
the argument must
|
|
be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
|
|
argument may be @code{VAX_Float} to specify the use of the VAX float
|
|
format, as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
For digits values up to 6, F float format will be used.
|
|
@item
|
|
For digits values from 7 to 9, D float format will be used.
|
|
@item
|
|
For digits values from 10 to 15, G float format will be used.
|
|
@item
|
|
Digits values above 15 are not allowed.
|
|
@end itemize
|
|
|
|
@node Pragma Ident
|
|
@unnumberedsec Pragma Ident
|
|
@findex Ident
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Ident (static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides a string identification in the generated object file,
|
|
if the system supports the concept of this kind of identification string.
|
|
This pragma is allowed only in the outermost declarative part or
|
|
declarative items of a compilation unit. If more than one @code{Ident}
|
|
pragma is given, only the last one processed is effective.
|
|
@cindex OpenVMS
|
|
On OpenVMS systems, the effect of the pragma is identical to the effect of
|
|
the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
|
|
maximum allowed length is 31 characters, so if it is important to
|
|
maintain compatibility with this compiler, you should obey this length
|
|
limit.
|
|
|
|
@node Pragma Implemented
|
|
@unnumberedsec Pragma Implemented
|
|
@findex Implemented
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
|
|
|
|
implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is an Ada 2012 representation pragma which applies to protected, task
|
|
and synchronized interface primitives. The use of pragma Implemented provides
|
|
a way to impose a static requirement on the overriding operation by adhering
|
|
to one of the three implementation kids: entry, protected procedure or any of
|
|
the above.
|
|
|
|
@smallexample @c ada
|
|
type Synch_Iface is synchronized interface;
|
|
procedure Prim_Op (Obj : in out Iface) is abstract;
|
|
pragma Implemented (Prim_Op, By_Protected_Procedure);
|
|
|
|
protected type Prot_1 is new Synch_Iface with
|
|
procedure Prim_Op; -- Legal
|
|
end Prot_1;
|
|
|
|
protected type Prot_2 is new Synch_Iface with
|
|
entry Prim_Op; -- Illegal
|
|
end Prot_2;
|
|
|
|
task type Task_Typ is new Synch_Iface with
|
|
entry Prim_Op; -- Illegal
|
|
end Task_Typ;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
When applied to the procedure_or_entry_NAME of a requeue statement, pragma
|
|
Implemented determines the runtime behavior of the requeue. Implementation kind
|
|
By_Entry guarantees that the action of requeueing will proceed from an entry to
|
|
another entry. Implementation kind By_Protected_Procedure transforms the
|
|
requeue into a dispatching call, thus eliminating the chance of blocking. Kind
|
|
By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
|
|
the target's overriding subprogram kind.
|
|
|
|
@node Pragma Implicit_Packing
|
|
@unnumberedsec Pragma Implicit_Packing
|
|
@findex Implicit_Packing
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Implicit_Packing;
|
|
@end smallexample
|
|
|
|
@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. 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;
|
|
for R'Size use 8;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
|
|
does not change the layout of a composite object. So the Size clause in the
|
|
above example is normally rejected, since the default layout of the array uses
|
|
8-bit components, and thus the array requires a minimum of 64 bits.
|
|
|
|
If this declaration is compiled in a region of code covered by an occurrence
|
|
of the configuration pragma Implicit_Packing, then the Size clause in this
|
|
and similar examples will cause implicit packing and thus be accepted. For
|
|
this implicit packing to occur, the type in question must be an array of small
|
|
components whose size is known at compile time, and the Size clause must
|
|
specify the exact size that corresponds to the length of the array multiplied
|
|
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 Implicit_Packing allows this record
|
|
declaration to compile without an explicit pragma Pack.
|
|
@node Pragma Import_Exception
|
|
@unnumberedsec Pragma Import_Exception
|
|
@cindex OpenVMS
|
|
@findex Import_Exception
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Import_Exception (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Form =>] Ada | VMS]
|
|
[, [Code =>] static_integer_EXPRESSION]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is implemented only in the OpenVMS implementation of GNAT@.
|
|
It allows OpenVMS conditions (for example, from OpenVMS system services or
|
|
other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
|
|
The pragma specifies that the exception associated with an exception
|
|
declaration in an Ada program be defined externally (in non-Ada code).
|
|
For further details on this pragma, see the
|
|
DEC Ada Language Reference Manual, section 13.9a.3.1.
|
|
|
|
@node Pragma Import_Function
|
|
@unnumberedsec Pragma Import_Function
|
|
@findex Import_Function
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Import_Function (
|
|
[Internal =>] LOCAL_NAME,
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Result_Type =>] SUBTYPE_MARK]
|
|
[, [Mechanism =>] MECHANISM]
|
|
[, [Result_Mechanism =>] MECHANISM_NAME]
|
|
[, [First_Optional_Parameter =>] IDENTIFIER]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used in conjunction with a pragma @code{Import} to
|
|
specify additional information for an imported function. The pragma
|
|
@code{Import} (or equivalent pragma @code{Interface}) must precede the
|
|
@code{Import_Function} pragma and both must appear in the same
|
|
declarative part as the function specification.
|
|
|
|
The @var{Internal} argument must uniquely designate
|
|
the function to which the
|
|
pragma applies. If more than one function name exists of this name in
|
|
the declarative part you must use the @code{Parameter_Types} and
|
|
@var{Result_Type} parameters to achieve the required unique
|
|
designation. Subtype marks in these parameters must exactly match the
|
|
subtypes in the corresponding function specification, using positional
|
|
notation to match parameters with subtype marks.
|
|
The form with an @code{'Access} attribute can be used to match an
|
|
anonymous access parameter.
|
|
|
|
You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
|
|
parameters to specify passing mechanisms for the
|
|
parameters and result. If you specify a single mechanism name, it
|
|
applies to all parameters. Otherwise you may specify a mechanism on a
|
|
parameter by parameter basis using either positional or named
|
|
notation. If the mechanism is not specified, the default mechanism
|
|
is used.
|
|
|
|
@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
|
|
are optional, meaning that they are not passed at the generated code
|
|
level (this is distinct from the notion of optional parameters in Ada
|
|
where the parameters are passed anyway with the designated optional
|
|
parameters). All optional parameters must be of mode @code{IN} and have
|
|
default parameter values that are either known at compile time
|
|
expressions, or uses of the @code{'Null_Parameter} attribute.
|
|
|
|
@node Pragma Import_Object
|
|
@unnumberedsec Pragma Import_Object
|
|
@findex Import_Object
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Import_Object
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Size =>] EXTERNAL_SYMBOL]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma designates an object as imported, and apart from the
|
|
extended rules for external symbols, is identical in effect to the use of
|
|
the normal @code{Import} pragma applied to an object. Unlike the
|
|
subprogram case, you need not use a separate @code{Import} pragma,
|
|
although you may do so (and probably should do so from a portability
|
|
point of view). @var{size} is syntax checked, but otherwise ignored by
|
|
GNAT@.
|
|
|
|
@node Pragma Import_Procedure
|
|
@unnumberedsec Pragma Import_Procedure
|
|
@findex Import_Procedure
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Import_Procedure (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Mechanism =>] MECHANISM]
|
|
[, [First_Optional_Parameter =>] IDENTIFIER]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical to @code{Import_Function} except that it
|
|
applies to a procedure rather than a function and the parameters
|
|
@code{Result_Type} and @code{Result_Mechanism} are not permitted.
|
|
|
|
@node Pragma Import_Valued_Procedure
|
|
@unnumberedsec Pragma Import_Valued_Procedure
|
|
@findex Import_Valued_Procedure
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Import_Valued_Procedure (
|
|
[Internal =>] LOCAL_NAME
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Parameter_Types =>] PARAMETER_TYPES]
|
|
[, [Mechanism =>] MECHANISM]
|
|
[, [First_Optional_Parameter =>] IDENTIFIER]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
|
|
PARAMETER_TYPES ::=
|
|
null
|
|
| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
|
|
|
|
TYPE_DESIGNATOR ::=
|
|
subtype_NAME
|
|
| subtype_Name ' Access
|
|
|
|
MECHANISM ::=
|
|
MECHANISM_NAME
|
|
| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
|
|
|
|
MECHANISM_ASSOCIATION ::=
|
|
[formal_parameter_NAME =>] MECHANISM_NAME
|
|
|
|
MECHANISM_NAME ::=
|
|
Value
|
|
| Reference
|
|
| Descriptor [([Class =>] CLASS_NAME)]
|
|
| Short_Descriptor [([Class =>] CLASS_NAME)]
|
|
|
|
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical to @code{Import_Procedure} except that the
|
|
first parameter of @var{LOCAL_NAME}, which must be present, must be of
|
|
mode @code{OUT}, and externally the subprogram is treated as a function
|
|
with this parameter as the result of the function. The purpose of this
|
|
capability is to allow the use of @code{OUT} and @code{IN OUT}
|
|
parameters in interfacing to external functions (which are not permitted
|
|
in Ada functions). You may optionally use the @code{Mechanism}
|
|
parameters to specify passing mechanisms for the parameters.
|
|
If you specify a single mechanism name, it applies to all parameters.
|
|
Otherwise you may specify a mechanism on a parameter by parameter
|
|
basis using either positional or named notation. If the mechanism is not
|
|
specified, the default mechanism is used.
|
|
|
|
Note that it is important to use this pragma in conjunction with a separate
|
|
pragma Import that specifies the desired convention, since otherwise the
|
|
default convention is Ada, which is almost certainly not what is required.
|
|
|
|
@node Pragma Initialize_Scalars
|
|
@unnumberedsec Pragma Initialize_Scalars
|
|
@findex Initialize_Scalars
|
|
@cindex debugging with Initialize_Scalars
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Initialize_Scalars;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is similar to @code{Normalize_Scalars} conceptually but has
|
|
two important differences. First, there is no requirement for the pragma
|
|
to be used uniformly in all units of a partition, in particular, it is fine
|
|
to use this just for some or all of the application units of a partition,
|
|
without needing to recompile the run-time library.
|
|
|
|
In the case where some units are compiled with the pragma, and some without,
|
|
then a declaration of a variable where the type is defined in package
|
|
Standard or is locally declared will always be subject to initialization,
|
|
as will any declaration of a scalar variable. For composite variables,
|
|
whether the variable is initialized may also depend on whether the package
|
|
in which the type of the variable is declared is compiled with the pragma.
|
|
|
|
The other important difference is that you can control the value used
|
|
for initializing scalar objects. At bind time, you can select several
|
|
options for initialization. You can
|
|
initialize with invalid values (similar to Normalize_Scalars, though for
|
|
Initialize_Scalars it is not always possible to determine the invalid
|
|
values in complex cases like signed component fields with non-standard
|
|
sizes). You can also initialize with high or
|
|
low values, or with a specified bit pattern. See the users guide for binder
|
|
options for specifying these cases.
|
|
|
|
This means that you can compile a program, and then without having to
|
|
recompile the program, you can run it with different values being used
|
|
for initializing otherwise uninitialized values, to test if your program
|
|
behavior depends on the choice. Of course the behavior should not change,
|
|
and if it does, then most likely you have an erroneous reference to an
|
|
uninitialized value.
|
|
|
|
It is even possible to change the value at execution time eliminating even
|
|
the need to rebind with a different switch using an environment variable.
|
|
See the GNAT users guide for details.
|
|
|
|
Note that pragma @code{Initialize_Scalars} is particularly useful in
|
|
conjunction with the enhanced validity checking that is now provided
|
|
in GNAT, which checks for invalid values under more conditions.
|
|
Using this feature (see description of the @option{-gnatV} flag in the
|
|
users guide) in conjunction with pragma @code{Initialize_Scalars}
|
|
provides a powerful new tool to assist in the detection of problems
|
|
caused by uninitialized variables.
|
|
|
|
Note: the use of @code{Initialize_Scalars} has a fairly extensive
|
|
effect on the generated code. This may cause your code to be
|
|
substantially larger. It may also cause an increase in the amount
|
|
of stack required, so it is probably a good idea to turn on stack
|
|
checking (see description of stack checking in the GNAT users guide)
|
|
when using this pragma.
|
|
|
|
@node Pragma Inline_Always
|
|
@unnumberedsec Pragma Inline_Always
|
|
@findex Inline_Always
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Inline_Always (NAME [, NAME]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Similar to pragma @code{Inline} except that inlining is not subject to
|
|
the use of option @option{-gnatn} and the inlining happens regardless of
|
|
whether this option is used.
|
|
|
|
@node Pragma Inline_Generic
|
|
@unnumberedsec Pragma Inline_Generic
|
|
@findex Inline_Generic
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Inline_Generic (generic_package_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is implemented for compatibility with DEC Ada 83 and is recognized,
|
|
but otherwise ignored, by GNAT@. All generic instantiations are inlined
|
|
by default when using GNAT@.
|
|
|
|
@node Pragma Interface
|
|
@unnumberedsec Pragma Interface
|
|
@findex Interface
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Interface (
|
|
[Convention =>] convention_identifier,
|
|
[Entity =>] local_NAME
|
|
[, [External_Name =>] static_string_expression]
|
|
[, [Link_Name =>] static_string_expression]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical in syntax and semantics to
|
|
the standard Ada pragma @code{Import}. It is provided for compatibility
|
|
with Ada 83. The definition is upwards compatible both with pragma
|
|
@code{Interface} as defined in the Ada 83 Reference Manual, and also
|
|
with some extended implementations of this pragma in certain Ada 83
|
|
implementations. The only difference between pragma @code{Interface}
|
|
and pragma @code{Import} is that there is special circuitry to allow
|
|
both pragmas to appear for the same subprogram entity (normally it
|
|
is illegal to have multiple @code{Import} pragmas. This is useful in
|
|
maintaining Ada 83/Ada 95 compatibility and is compatible with other
|
|
Ada 83 compilers.
|
|
|
|
@node Pragma Interface_Name
|
|
@unnumberedsec Pragma Interface_Name
|
|
@findex Interface_Name
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Interface_Name (
|
|
[Entity =>] LOCAL_NAME
|
|
[, [External_Name =>] static_string_EXPRESSION]
|
|
[, [Link_Name =>] static_string_EXPRESSION]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides an alternative way of specifying the interface name
|
|
for an interfaced subprogram, and is provided for compatibility with Ada
|
|
83 compilers that use the pragma for this purpose. You must provide at
|
|
least one of @var{External_Name} or @var{Link_Name}.
|
|
|
|
@node Pragma Interrupt_Handler
|
|
@unnumberedsec Pragma Interrupt_Handler
|
|
@findex Interrupt_Handler
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Interrupt_Handler (procedure_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This program unit pragma is supported for parameterless protected procedures
|
|
as described in Annex C of the Ada Reference Manual. On the AAMP target
|
|
the pragma can also be specified for nonprotected parameterless procedures
|
|
that are declared at the library level (which includes procedures
|
|
declared at the top level of a library package). In the case of AAMP,
|
|
when this pragma is applied to a nonprotected procedure, the instruction
|
|
@code{IERET} is generated for returns from the procedure, enabling
|
|
maskable interrupts, in place of the normal return instruction.
|
|
|
|
@node Pragma Interrupt_State
|
|
@unnumberedsec Pragma Interrupt_State
|
|
@findex Interrupt_State
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Interrupt_State
|
|
([Name =>] value,
|
|
[State =>] SYSTEM | RUNTIME | USER);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Normally certain interrupts are reserved to the implementation. Any attempt
|
|
to attach an interrupt causes Program_Error to be raised, as described in
|
|
RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
|
|
many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
|
|
reserved to the implementation, so that @kbd{Ctrl-C} can be used to
|
|
interrupt execution. Additionally, signals such as @code{SIGSEGV},
|
|
@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
|
|
Ada exceptions, or used to implement run-time functions such as the
|
|
@code{abort} statement and stack overflow checking.
|
|
|
|
Pragma @code{Interrupt_State} provides a general mechanism for overriding
|
|
such uses of interrupts. It subsumes the functionality of pragma
|
|
@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
|
|
available on Windows or VMS. On all other platforms than VxWorks,
|
|
it applies to signals; on VxWorks, it applies to vectored hardware interrupts
|
|
and may be used to mark interrupts required by the board support package
|
|
as reserved.
|
|
|
|
Interrupts can be in one of three states:
|
|
@itemize @bullet
|
|
@item System
|
|
|
|
The interrupt is reserved (no Ada handler can be installed), and the
|
|
Ada run-time may not install a handler. As a result you are guaranteed
|
|
standard system default action if this interrupt is raised.
|
|
|
|
@item Runtime
|
|
|
|
The interrupt is reserved (no Ada handler can be installed). The run time
|
|
is allowed to install a handler for internal control purposes, but is
|
|
not required to do so.
|
|
|
|
@item User
|
|
|
|
The interrupt is unreserved. The user may install a handler to provide
|
|
some other action.
|
|
@end itemize
|
|
|
|
@noindent
|
|
These states are the allowed values of the @code{State} parameter of the
|
|
pragma. The @code{Name} parameter is a value of the type
|
|
@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
|
|
@code{Ada.Interrupts.Names}.
|
|
|
|
This is a configuration pragma, and the binder will check that there
|
|
are no inconsistencies between different units in a partition in how a
|
|
given interrupt is specified. It may appear anywhere a pragma is legal.
|
|
|
|
The effect is to move the interrupt to the specified state.
|
|
|
|
By declaring interrupts to be SYSTEM, you guarantee the standard system
|
|
action, such as a core dump.
|
|
|
|
By declaring interrupts to be USER, you guarantee that you can install
|
|
a handler.
|
|
|
|
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 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,
|
|
and in the case of the signal used to implement the @code{abort} statement.
|
|
|
|
@node Pragma Invariant
|
|
@unnumberedsec Pragma Invariant
|
|
@findex Invariant
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Invariant
|
|
([Entity =>] private_type_LOCAL_NAME,
|
|
[Check =>] EXPRESSION
|
|
[,[Message =>] String_Expression]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides exactly the same capabilities as the Invariant aspect
|
|
defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The Invariant
|
|
aspect is fully implemented in Ada 2012 mode, but since it requires the use
|
|
of the aspect syntax, which is not available exception in 2012 mode, it is
|
|
not possible to use the Invariant aspect in earlier versions of Ada. However
|
|
the Invariant pragma may be used in any version of Ada.
|
|
|
|
The pragma must appear within the visible part of the package specification,
|
|
after the type to which its Entity argument appears. As with the Invariant
|
|
aspect, the Check expression is not analyzed until the end of the visible
|
|
part of the package, so it may contain forward references. The Message
|
|
argument, if present, provides the exception message used if the invariant
|
|
is violated. If no Message parameter is provided, a default message that
|
|
identifies the line on which the pragma appears is used.
|
|
|
|
It is permissible to have multiple Invariants for the same type entity, in
|
|
which case they are and'ed together. It is permissible to use this pragma
|
|
in Ada 2012 mode, but you cannot have both an invariant aspect and an
|
|
invariant pragma for the same entity.
|
|
|
|
For further details on the use of this pragma, see the Ada 2012 documentation
|
|
of the Invariant aspect.
|
|
|
|
@node Pragma Keep_Names
|
|
@unnumberedsec Pragma Keep_Names
|
|
@findex Keep_Names
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @var{LOCAL_NAME} argument
|
|
must refer to an enumeration first subtype
|
|
in the current declarative part. The effect is to retain the enumeration
|
|
literal names for use by @code{Image} and @code{Value} even if a global
|
|
@code{Discard_Names} pragma applies. This is useful when you want to
|
|
generally suppress enumeration literal names and for example you therefore
|
|
use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
|
|
want to retain the names for specific enumeration types.
|
|
|
|
@node Pragma License
|
|
@unnumberedsec Pragma License
|
|
@findex License
|
|
@cindex License checking
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is provided to allow automated checking for appropriate license
|
|
conditions with respect to the standard and modified GPL@. A pragma
|
|
@code{License}, which is a configuration pragma that typically appears at
|
|
the start of a source file or in a separate @file{gnat.adc} file, specifies
|
|
the licensing conditions of a unit as follows:
|
|
|
|
@itemize @bullet
|
|
@item Unrestricted
|
|
This is used for a unit that can be freely used with no license restrictions.
|
|
Examples of such units are public domain units, and units from the Ada
|
|
Reference Manual.
|
|
|
|
@item GPL
|
|
This is used for a unit that is licensed under the unmodified GPL, and which
|
|
therefore cannot be @code{with}'ed by a restricted unit.
|
|
|
|
@item Modified_GPL
|
|
This is used for a unit licensed under the GNAT modified GPL that includes
|
|
a special exception paragraph that specifically permits the inclusion of
|
|
the unit in programs without requiring the entire program to be released
|
|
under the GPL@.
|
|
|
|
@item Restricted
|
|
This is used for a unit that is restricted in that it is not permitted to
|
|
depend on units that are licensed under the GPL@. Typical examples are
|
|
proprietary code that is to be released under more restrictive license
|
|
conditions. Note that restricted units are permitted to @code{with} units
|
|
which are licensed under the modified GPL (this is the whole point of the
|
|
modified GPL).
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
Normally a unit with no @code{License} pragma is considered to have an
|
|
unknown license, and no checking is done. However, standard GNAT headers
|
|
are recognized, and license information is derived from them as follows.
|
|
|
|
@itemize @bullet
|
|
|
|
A GNAT license header starts with a line containing 78 hyphens. The following
|
|
comment text is searched for the appearance of any of the following strings.
|
|
|
|
If the string ``GNU General Public License'' is found, then the unit is assumed
|
|
to have GPL license, unless the string ``As a special exception'' follows, in
|
|
which case the license is assumed to be modified GPL@.
|
|
|
|
If one of the strings
|
|
``This specification is adapted from the Ada Semantic Interface'' or
|
|
``This specification is derived from the Ada Reference Manual'' is found
|
|
then the unit is assumed to be unrestricted.
|
|
@end itemize
|
|
|
|
@noindent
|
|
These default actions means that a program with a restricted license pragma
|
|
will automatically get warnings if a GPL unit is inappropriately
|
|
@code{with}'ed. For example, the program:
|
|
|
|
@smallexample @c ada
|
|
with Sem_Ch3;
|
|
with GNAT.Sockets;
|
|
procedure Secret_Stuff is
|
|
@dots{}
|
|
end Secret_Stuff
|
|
@end smallexample
|
|
|
|
@noindent
|
|
if compiled with pragma @code{License} (@code{Restricted}) in a
|
|
@file{gnat.adc} file will generate the warning:
|
|
|
|
@smallexample
|
|
1. with Sem_Ch3;
|
|
|
|
|
>>> license of withed unit "Sem_Ch3" is incompatible
|
|
|
|
2. with GNAT.Sockets;
|
|
3. procedure Secret_Stuff is
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
|
|
compiler and is licensed under the
|
|
GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
|
|
run time, and is therefore licensed under the modified GPL@.
|
|
|
|
@node Pragma Link_With
|
|
@unnumberedsec Pragma Link_With
|
|
@findex Link_With
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is provided for compatibility with certain Ada 83 compilers.
|
|
It has exactly the same effect as pragma @code{Linker_Options} except
|
|
that spaces occurring within one of the string expressions are treated
|
|
as separators. For example, in the following case:
|
|
|
|
@smallexample @c ada
|
|
pragma Link_With ("-labc -ldef");
|
|
@end smallexample
|
|
|
|
@noindent
|
|
results in passing the strings @code{-labc} and @code{-ldef} as two
|
|
separate arguments to the linker. In addition pragma Link_With allows
|
|
multiple arguments, with the same effect as successive pragmas.
|
|
|
|
@node Pragma Linker_Alias
|
|
@unnumberedsec Pragma Linker_Alias
|
|
@findex Linker_Alias
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Linker_Alias (
|
|
[Entity =>] LOCAL_NAME,
|
|
[Target =>] static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{LOCAL_NAME} must refer to an object that is declared at the library
|
|
level. This pragma establishes the given entity as a linker alias for the
|
|
given target. It is equivalent to @code{__attribute__((alias))} in GNU C
|
|
and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol
|
|
@var{static_string_EXPRESSION} in the object file, that is to say no space
|
|
is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
|
|
to the same address as @var{static_string_EXPRESSION} by the linker.
|
|
|
|
The actual linker name for the target must be used (e.g.@: the fully
|
|
encoded name with qualification in Ada, or the mangled name in C++),
|
|
or it must be declared using the C convention with @code{pragma Import}
|
|
or @code{pragma Export}.
|
|
|
|
Not all target machines support this pragma. On some of them it is accepted
|
|
only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}.
|
|
|
|
@smallexample @c ada
|
|
-- Example of the use of pragma Linker_Alias
|
|
|
|
package p is
|
|
i : Integer := 1;
|
|
pragma Export (C, i);
|
|
|
|
new_name_for_i : Integer;
|
|
pragma Linker_Alias (new_name_for_i, "i");
|
|
end p;
|
|
@end smallexample
|
|
|
|
@node Pragma Linker_Constructor
|
|
@unnumberedsec Pragma Linker_Constructor
|
|
@findex Linker_Constructor
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Linker_Constructor (procedure_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
|
|
is declared at the library level. A procedure to which this pragma is
|
|
applied will be treated as an initialization routine by the linker.
|
|
It is equivalent to @code{__attribute__((constructor))} in GNU C and
|
|
causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
|
|
of the executable is called (or immediately after the shared library is
|
|
loaded if the procedure is linked in a shared library), in particular
|
|
before the Ada run-time environment is set up.
|
|
|
|
Because of these specific contexts, the set of operations such a procedure
|
|
can perform is very limited and the type of objects it can manipulate is
|
|
essentially restricted to the elementary types. In particular, it must only
|
|
contain code to which pragma Restrictions (No_Elaboration_Code) applies.
|
|
|
|
This pragma is used by GNAT to implement auto-initialization of shared Stand
|
|
Alone Libraries, which provides a related capability without the restrictions
|
|
listed above. Where possible, the use of Stand Alone Libraries is preferable
|
|
to the use of this pragma.
|
|
|
|
@node Pragma Linker_Destructor
|
|
@unnumberedsec Pragma Linker_Destructor
|
|
@findex Linker_Destructor
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Linker_Destructor (procedure_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
|
|
is declared at the library level. A procedure to which this pragma is
|
|
applied will be treated as a finalization routine by the linker.
|
|
It is equivalent to @code{__attribute__((destructor))} in GNU C and
|
|
causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
|
|
of the executable has exited (or immediately before the shared library
|
|
is unloaded if the procedure is linked in a shared library), in particular
|
|
after the Ada run-time environment is shut down.
|
|
|
|
See @code{pragma Linker_Constructor} for the set of restrictions that apply
|
|
because of these specific contexts.
|
|
|
|
@node Pragma Linker_Section
|
|
@unnumberedsec Pragma Linker_Section
|
|
@findex Linker_Section
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Linker_Section (
|
|
[Entity =>] LOCAL_NAME,
|
|
[Section =>] static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{LOCAL_NAME} must refer to an object that is declared at the library
|
|
level. This pragma specifies the name of the linker section for the given
|
|
entity. It is equivalent to @code{__attribute__((section))} in GNU C and
|
|
causes @var{LOCAL_NAME} to be placed in the @var{static_string_EXPRESSION}
|
|
section of the executable (assuming the linker doesn't rename the section).
|
|
|
|
The compiler normally places library-level objects in standard sections
|
|
depending on their type: procedures and functions generally go in the
|
|
@code{.text} section, initialized variables in the @code{.data} section
|
|
and uninitialized variables in the @code{.bss} section.
|
|
|
|
Other, special sections may exist on given target machines to map special
|
|
hardware, for example I/O ports or flash memory. This pragma is a means to
|
|
defer the final layout of the executable to the linker, thus fully working
|
|
at the symbolic level with the compiler.
|
|
|
|
Some file formats do not support arbitrary sections so not all target
|
|
machines support this pragma. The use of this pragma may cause a program
|
|
execution to be erroneous if it is used to place an entity into an
|
|
inappropriate section (e.g.@: a modified variable into the @code{.text}
|
|
section). See also @code{pragma Persistent_BSS}.
|
|
|
|
@smallexample @c ada
|
|
-- Example of the use of pragma Linker_Section
|
|
|
|
package IO_Card is
|
|
Port_A : Integer;
|
|
pragma Volatile (Port_A);
|
|
pragma Linker_Section (Port_A, ".bss.port_a");
|
|
|
|
Port_B : Integer;
|
|
pragma Volatile (Port_B);
|
|
pragma Linker_Section (Port_B, ".bss.port_b");
|
|
end IO_Card;
|
|
@end smallexample
|
|
|
|
@node Pragma Long_Float
|
|
@unnumberedsec Pragma Long_Float
|
|
@cindex OpenVMS
|
|
@findex Long_Float
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Long_Float (FLOAT_FORMAT);
|
|
|
|
FLOAT_FORMAT ::= D_Float | G_Float
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is implemented only in the OpenVMS implementation of GNAT@.
|
|
It allows control over the internal representation chosen for the predefined
|
|
type @code{Long_Float} and for floating point type representations with
|
|
@code{digits} specified in the range 7 through 15.
|
|
For further details on this pragma, see the
|
|
@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
|
|
this pragma, the standard runtime libraries must be recompiled.
|
|
|
|
@node Pragma Machine_Attribute
|
|
@unnumberedsec Pragma Machine_Attribute
|
|
@findex Machine_Attribute
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Machine_Attribute (
|
|
[Entity =>] LOCAL_NAME,
|
|
[Attribute_Name =>] static_string_EXPRESSION
|
|
[, [Info =>] static_EXPRESSION] );
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Machine-dependent attributes can be specified for types and/or
|
|
declarations. This pragma is semantically equivalent to
|
|
@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
|
|
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
|
|
@cindex OpenVMS
|
|
@findex Main
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
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
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is provided for compatibility with OpenVMS VAX Systems. It has
|
|
no effect in GNAT, other than being syntax checked.
|
|
|
|
@node Pragma Main_Storage
|
|
@unnumberedsec Pragma Main_Storage
|
|
@cindex OpenVMS
|
|
@findex Main_Storage
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Main_Storage
|
|
(MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
|
|
|
|
MAIN_STORAGE_OPTION ::=
|
|
[WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
|
|
| [TOP_GUARD =>] static_SIMPLE_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is provided for compatibility with OpenVMS VAX Systems. It has
|
|
no effect in GNAT, other than being syntax checked. Note that the pragma
|
|
also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
|
|
|
|
@node Pragma No_Body
|
|
@unnumberedsec Pragma No_Body
|
|
@findex No_Body
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma No_Body;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
There are a number of cases in which a package spec does not require a body,
|
|
and in fact a body is not permitted. GNAT will not permit the spec to be
|
|
compiled if there is a body around. The pragma No_Body allows you to provide
|
|
a body file, even in a case where no body is allowed. The body file must
|
|
contain only comments and a single No_Body pragma. This is recognized by
|
|
the compiler as indicating that no body is logically present.
|
|
|
|
This is particularly useful during maintenance when a package is modified in
|
|
such a way that a body needed before is no longer needed. The provision of a
|
|
dummy body with a No_Body pragma ensures that there is no interference from
|
|
earlier versions of the package body.
|
|
|
|
@node Pragma No_Return
|
|
@unnumberedsec Pragma No_Return
|
|
@findex No_Return
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure
|
|
declarations in the current declarative part. A procedure to which this
|
|
pragma is applied may not contain any explicit @code{return} statements.
|
|
In addition, if the procedure contains any implicit returns from falling
|
|
off the end of a statement sequence, then execution of that implicit
|
|
return will cause Program_Error to be raised.
|
|
|
|
One use of this pragma is to identify procedures whose only purpose is to raise
|
|
an exception. Another use of this pragma is to suppress incorrect warnings
|
|
about missing returns in functions, where the last statement of a function
|
|
statement sequence is a call to such a procedure.
|
|
|
|
Note that in Ada 2005 mode, this pragma is part of the language, and is
|
|
identical in effect to the pragma as implemented in Ada 95 mode.
|
|
|
|
@node Pragma No_Strict_Aliasing
|
|
@unnumberedsec Pragma No_Strict_Aliasing
|
|
@findex No_Strict_Aliasing
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{type_LOCAL_NAME} must refer to an access type
|
|
declaration in the current declarative part. The effect is to inhibit
|
|
strict aliasing optimization for the given type. The form with no
|
|
arguments is a configuration pragma which applies to all access types
|
|
declared in units to which the pragma applies. For a detailed
|
|
description of the strict aliasing optimization, and the situations
|
|
in which it must be suppressed, see @ref{Optimization and Strict
|
|
Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
|
|
|
|
This pragma currently has no effects on access to unconstrained array types.
|
|
|
|
@node Pragma Normalize_Scalars
|
|
@unnumberedsec Pragma Normalize_Scalars
|
|
@findex Normalize_Scalars
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Normalize_Scalars;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a language defined pragma which is fully implemented in GNAT@. The
|
|
effect is to cause all scalar objects that are not otherwise initialized
|
|
to be initialized. The initial values are implementation dependent and
|
|
are as follows:
|
|
|
|
@table @code
|
|
@item Standard.Character
|
|
@noindent
|
|
Objects whose root type is Standard.Character are initialized to
|
|
Character'Last unless the subtype range excludes NUL (in which case
|
|
NUL is used). This choice will always generate an invalid value if
|
|
one exists.
|
|
|
|
@item Standard.Wide_Character
|
|
@noindent
|
|
Objects whose root type is Standard.Wide_Character are initialized to
|
|
Wide_Character'Last unless the subtype range excludes NUL (in which case
|
|
NUL is used). This choice will always generate an invalid value if
|
|
one exists.
|
|
|
|
@item Standard.Wide_Wide_Character
|
|
@noindent
|
|
Objects whose root type is Standard.Wide_Wide_Character are initialized to
|
|
the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
|
|
which case NUL is used). This choice will always generate an invalid value if
|
|
one exists.
|
|
|
|
@item Integer types
|
|
@noindent
|
|
Objects of an integer type are treated differently depending on whether
|
|
negative values are present in the subtype. If no negative values are
|
|
present, then all one bits is used as the initial value except in the
|
|
special case where zero is excluded from the subtype, in which case
|
|
all zero bits are used. This choice will always generate an invalid
|
|
value if one exists.
|
|
|
|
For subtypes with negative values present, the largest negative number
|
|
is used, except in the unusual case where this largest negative number
|
|
is in the subtype, and the largest positive number is not, in which case
|
|
the largest positive value is used. This choice will always generate
|
|
an invalid value if one exists.
|
|
|
|
@item Floating-Point Types
|
|
Objects of all floating-point types are initialized to all 1-bits. For
|
|
standard IEEE format, this corresponds to a NaN (not a number) which is
|
|
indeed an invalid value.
|
|
|
|
@item Fixed-Point Types
|
|
Objects of all fixed-point types are treated as described above for integers,
|
|
with the rules applying to the underlying integer value used to represent
|
|
the fixed-point value.
|
|
|
|
@item Modular types
|
|
Objects of a modular type are initialized to all one bits, except in
|
|
the special case where zero is excluded from the subtype, in which
|
|
case all zero bits are used. This choice will always generate an
|
|
invalid value if one exists.
|
|
|
|
@item Enumeration types
|
|
Objects of an enumeration type are initialized to all one-bits, i.e.@: to
|
|
the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
|
|
whose Pos value is zero, in which case a code of zero is used. This choice
|
|
will always generate an invalid value if one exists.
|
|
|
|
@end table
|
|
|
|
@node Pragma Obsolescent
|
|
@unnumberedsec Pragma Obsolescent
|
|
@findex Obsolescent
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
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. 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
|
|
used when an API must be modified by eventually removing or modifying
|
|
existing subprograms or other entities. The pragma can be used at an
|
|
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 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 entity 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
|
|
pragma indicates that the entire package is considered
|
|
obsolescent. In this case a client @code{with}'ing such a package
|
|
violates the restriction, and the @code{with} statement is
|
|
flagged with warnings if the warning option is set.
|
|
|
|
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
|
|
in the predefined library where subprograms or packages
|
|
have become defined as obsolescent in Ada 2005
|
|
(e.g.@: in Ada.Characters.Handling), but may be used anywhere.
|
|
|
|
The following examples show typical uses of this pragma:
|
|
|
|
@smallexample @c ada
|
|
package p is
|
|
pragma Obsolescent (p, Message => "use pp instead of p");
|
|
end p;
|
|
|
|
package q is
|
|
procedure q2;
|
|
pragma Obsolescent ("use q2new instead");
|
|
|
|
type R is new integer;
|
|
pragma Obsolescent
|
|
(Entity => R,
|
|
Message => "use RR in Ada 2005",
|
|
Version => Ada_05);
|
|
|
|
type M is record
|
|
F1 : Integer;
|
|
F2 : Integer;
|
|
pragma Obsolescent;
|
|
F3 : Integer;
|
|
end record;
|
|
|
|
type E is (a, bc, 'd', quack);
|
|
pragma Obsolescent (Entity => bc)
|
|
pragma Obsolescent (Entity => 'd')
|
|
|
|
function "+"
|
|
(a, b : character) return character;
|
|
pragma Obsolescent (Entity => "+");
|
|
end;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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 Ordered
|
|
@unnumberedsec Pragma Ordered
|
|
@findex Ordered
|
|
@findex pragma @code{Ordered}
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Most enumeration types are from a conceptual point of view unordered.
|
|
For example, consider:
|
|
|
|
@smallexample @c ada
|
|
type Color is (Red, Blue, Green, Yellow);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
By Ada semantics @code{Blue > Red} and @code{Green > Blue},
|
|
but really these relations make no sense; the enumeration type merely
|
|
specifies a set of possible colors, and the order is unimportant.
|
|
|
|
For unordered enumeration types, it is generally a good idea if
|
|
clients avoid comparisons (other than equality or inequality) and
|
|
explicit ranges. (A @emph{client} is a unit where the type is referenced,
|
|
other than the unit where the type is declared, its body, and its subunits.)
|
|
For example, if code buried in some client says:
|
|
|
|
@smallexample @c ada
|
|
if Current_Color < Yellow then ...
|
|
if Current_Color in Blue .. Green then ...
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then the client code is relying on the order, which is undesirable.
|
|
It makes the code hard to read and creates maintenance difficulties if
|
|
entries have to be added to the enumeration type. Instead,
|
|
the code in the client should list the possibilities, or an
|
|
appropriate subtype should be declared in the unit that declares
|
|
the original enumeration type. E.g., the following subtype could
|
|
be declared along with the type @code{Color}:
|
|
|
|
@smallexample @c ada
|
|
subtype RBG is Color range Red .. Green;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and then the client could write:
|
|
|
|
@smallexample @c ada
|
|
if Current_Color in RBG then ...
|
|
if Current_Color = Blue or Current_Color = Green then ...
|
|
@end smallexample
|
|
|
|
@noindent
|
|
However, some enumeration types are legitimately ordered from a conceptual
|
|
point of view. For example, if you declare:
|
|
|
|
@smallexample @c ada
|
|
type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then the ordering imposed by the language is reasonable, and
|
|
clients can depend on it, writing for example:
|
|
|
|
@smallexample @c ada
|
|
if D in Mon .. Fri then ...
|
|
if D < Wed then ...
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The pragma @option{Ordered} is provided to mark enumeration types that
|
|
are conceptually ordered, alerting the reader that clients may depend
|
|
on the ordering. GNAT provides a pragma to mark enumerations as ordered
|
|
rather than one to mark them as unordered, since in our experience,
|
|
the great majority of enumeration types are conceptually unordered.
|
|
|
|
The types @code{Boolean}, @code{Character}, @code{Wide_Character},
|
|
and @code{Wide_Wide_Character}
|
|
are considered to be ordered types, so each is declared with a
|
|
pragma @code{Ordered} in package @code{Standard}.
|
|
|
|
Normally pragma @code{Ordered} serves only as documentation and a guide for
|
|
coding standards, but GNAT provides a warning switch @option{-gnatw.u} that
|
|
requests warnings for inappropriate uses (comparisons and explicit
|
|
subranges) for unordered types. If this switch is used, then any
|
|
enumeration type not marked with pragma @code{Ordered} will be considered
|
|
as unordered, and will generate warnings for inappropriate uses.
|
|
|
|
For additional information please refer to the description of the
|
|
@option{-gnatw.u} switch in the @value{EDITION} User's Guide.
|
|
|
|
@node Pragma Passive
|
|
@unnumberedsec Pragma Passive
|
|
@findex Passive
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Passive [(Semaphore | No)];
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Syntax checked, but otherwise ignored by GNAT@. This is recognized for
|
|
compatibility with DEC Ada 83 implementations, where it is used within a
|
|
task definition to request that a task be made passive. If the argument
|
|
@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
|
|
treats the pragma as an assertion that the containing task is passive
|
|
and that optimization of context switch with this task is permitted and
|
|
desired. If the argument @code{No} is present, the task must not be
|
|
optimized. GNAT does not attempt to optimize any tasks in this manner
|
|
(since protected objects are available in place of passive tasks).
|
|
|
|
@node Pragma Persistent_BSS
|
|
@unnumberedsec Pragma Persistent_BSS
|
|
@findex Persistent_BSS
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Persistent_BSS [(LOCAL_NAME)]
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma allows selected objects to be placed in the @code{.persistent_bss}
|
|
section. On some targets the linker and loader provide for special
|
|
treatment of this section, allowing a program to be reloaded without
|
|
affecting the contents of this data (hence the name persistent).
|
|
|
|
There are two forms of usage. If an argument is given, it must be the
|
|
local name of a library level object, with no explicit initialization
|
|
and whose type is potentially persistent. If no argument is given, then
|
|
the pragma is a configuration pragma, and applies to all library level
|
|
objects with no explicit initialization of potentially persistent types.
|
|
|
|
A potentially persistent type is a scalar type, or a non-tagged,
|
|
non-discriminated record, all of whose components have no explicit
|
|
initialization and are themselves of a potentially persistent type,
|
|
or an array, all of whose constraints are static, and whose component
|
|
type is potentially persistent.
|
|
|
|
If this pragma is used on a target where this feature is not supported,
|
|
then the pragma will be ignored. See also @code{pragma Linker_Section}.
|
|
|
|
@node Pragma Polling
|
|
@unnumberedsec Pragma Polling
|
|
@findex Polling
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Polling (ON | OFF);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma controls the generation of polling code. This is normally off.
|
|
If @code{pragma Polling (ON)} is used then periodic calls are generated to
|
|
the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
|
|
runtime library, and can be found in file @file{a-excpol.adb}.
|
|
|
|
Pragma @code{Polling} can appear as a configuration pragma (for example it
|
|
can be placed in the @file{gnat.adc} file) to enable polling globally, or it
|
|
can be used in the statement or declaration sequence to control polling
|
|
more locally.
|
|
|
|
A call to the polling routine is generated at the start of every loop and
|
|
at the start of every subprogram call. This guarantees that the @code{Poll}
|
|
routine is called frequently, and places an upper bound (determined by
|
|
the complexity of the code) on the period between two @code{Poll} calls.
|
|
|
|
The primary purpose of the polling interface is to enable asynchronous
|
|
aborts on targets that cannot otherwise support it (for example Windows
|
|
NT), but it may be used for any other purpose requiring periodic polling.
|
|
The standard version is null, and can be replaced by a user program. This
|
|
will require re-compilation of the @code{Ada.Exceptions} package that can
|
|
be found in files @file{a-except.ads} and @file{a-except.adb}.
|
|
|
|
A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
|
|
distribution) is used to enable the asynchronous abort capability on
|
|
targets that do not normally support the capability. The version of
|
|
@code{Poll} in this file makes a call to the appropriate runtime routine
|
|
to test for an abort condition.
|
|
|
|
Note that polling can also be enabled by use of the @option{-gnatP} switch.
|
|
@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 immediately 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 immediately 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
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Profile (Ravenscar);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes the following set of configuration
|
|
pragmas:
|
|
|
|
@table @code
|
|
@item Task_Dispatching_Policy (FIFO_Within_Priorities)
|
|
[RM D.2.2] Tasks are dispatched following a preemptive
|
|
priority-ordered scheduling policy.
|
|
|
|
@item Locking_Policy (Ceiling_Locking)
|
|
[RM D.3] While tasks and interrupts execute a protected action, they inherit
|
|
the ceiling priority of the corresponding protected object.
|
|
@c
|
|
@c @item Detect_Blocking
|
|
@c This pragma forces the detection of potentially blocking operations within a
|
|
@c protected operation, and to raise Program_Error if that happens.
|
|
@end table
|
|
@noindent
|
|
|
|
plus the following set of restrictions:
|
|
|
|
@table @code
|
|
@item Max_Entry_Queue_Length => 1
|
|
No task can be queued on a protected entry.
|
|
@item Max_Protected_Entries => 1
|
|
@item Max_Task_Entries => 0
|
|
No rendezvous statements are allowed.
|
|
@item No_Abort_Statements
|
|
@item No_Dynamic_Attachment
|
|
@item No_Dynamic_Priorities
|
|
@item No_Implicit_Heap_Allocations
|
|
@item No_Local_Protected_Objects
|
|
@item No_Local_Timing_Events
|
|
@item No_Protected_Type_Allocators
|
|
@item No_Relative_Delay
|
|
@item No_Requeue_Statements
|
|
@item No_Select_Statements
|
|
@item No_Specific_Termination_Handlers
|
|
@item No_Task_Allocators
|
|
@item No_Task_Hierarchy
|
|
@item No_Task_Termination
|
|
@item Simple_Barriers
|
|
@end table
|
|
@noindent
|
|
|
|
The Ravenscar profile also includes the following restrictions that specify
|
|
that there are no semantic dependences on the corresponding predefined
|
|
packages:
|
|
|
|
@table @code
|
|
@item No_Dependence => Ada.Asynchronous_Task_Control
|
|
@item No_Dependence => Ada.Calendar
|
|
@item No_Dependence => Ada.Execution_Time.Group_Budget
|
|
@item No_Dependence => Ada.Execution_Time.Timers
|
|
@item No_Dependence => Ada.Task_Attributes
|
|
@item No_Dependence => System.Multiprocessors.Dispatching_Domains
|
|
@end table
|
|
|
|
@noindent
|
|
|
|
This set of configuration pragmas and restrictions correspond to the
|
|
definition of the ``Ravenscar Profile'' for limited tasking, devised and
|
|
published by the @cite{International Real-Time Ada Workshop}, 1997,
|
|
and whose most recent description is available at
|
|
@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
|
|
|
|
The original definition of the profile was revised at subsequent IRTAW
|
|
meetings. It has been included in the ISO
|
|
@cite{Guide for the Use of the Ada Programming Language in High
|
|
Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
|
|
the next revision of the standard. The formal definition given by
|
|
the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
|
|
AI-305) available at
|
|
@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
|
|
@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
|
|
|
|
The above set is a superset of the restrictions provided by pragma
|
|
@code{Profile (Restricted)}, it includes six additional restrictions
|
|
(@code{Simple_Barriers}, @code{No_Select_Statements},
|
|
@code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
|
|
@code{No_Relative_Delay} and @code{No_Task_Termination}). This means
|
|
that pragma @code{Profile (Ravenscar)}, like the pragma
|
|
@code{Profile (Restricted)},
|
|
automatically causes the use of a simplified,
|
|
more efficient version of the tasking run-time system.
|
|
|
|
@node Pragma Profile (Restricted)
|
|
@unnumberedsec Pragma Profile (Restricted)
|
|
@findex Restricted Run Time
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Profile (Restricted);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A configuration pragma that establishes the following set of restrictions:
|
|
|
|
@itemize @bullet
|
|
@item No_Abort_Statements
|
|
@item No_Entry_Queue
|
|
@item No_Task_Hierarchy
|
|
@item No_Task_Allocators
|
|
@item No_Dynamic_Priorities
|
|
@item No_Terminate_Alternatives
|
|
@item No_Dynamic_Attachment
|
|
@item No_Protected_Type_Allocators
|
|
@item No_Local_Protected_Objects
|
|
@item No_Requeue_Statements
|
|
@item No_Task_Attributes_Package
|
|
@item Max_Asynchronous_Select_Nesting = 0
|
|
@item Max_Task_Entries = 0
|
|
@item Max_Protected_Entries = 1
|
|
@item Max_Select_Alternatives = 0
|
|
@end itemize
|
|
|
|
@noindent
|
|
This set of restrictions causes the automatic selection of a simplified
|
|
version of the run time that provides improved performance for the
|
|
limited set of tasking functionality permitted by this set of restrictions.
|
|
|
|
@node Pragma Psect_Object
|
|
@unnumberedsec Pragma Psect_Object
|
|
@findex Psect_Object
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Psect_Object (
|
|
[Internal =>] LOCAL_NAME,
|
|
[, [External =>] EXTERNAL_SYMBOL]
|
|
[, [Size =>] EXTERNAL_SYMBOL]);
|
|
|
|
EXTERNAL_SYMBOL ::=
|
|
IDENTIFIER
|
|
| static_string_EXPRESSION
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is identical in effect to pragma @code{Common_Object}.
|
|
|
|
@node Pragma Pure_Function
|
|
@unnumberedsec Pragma Pure_Function
|
|
@findex Pure_Function
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma appears in the same declarative part as a function
|
|
declaration (or a set of function declarations if more than one
|
|
overloaded declaration exists, in which case the pragma applies
|
|
to all entities). It specifies that the function @code{Entity} is
|
|
to be considered pure for the purposes of code generation. This means
|
|
that the compiler can assume that there are no side effects, and
|
|
in particular that two calls with identical arguments produce the
|
|
same result. It also means that the function can be used in an
|
|
address clause.
|
|
|
|
Note that, quite deliberately, there are no static checks to try
|
|
to ensure that this promise is met, so @code{Pure_Function} can be used
|
|
with functions that are conceptually pure, even if they do modify
|
|
global variables. For example, a square root function that is
|
|
instrumented to count the number of times it is called is still
|
|
conceptually pure, and can still be optimized, even though it
|
|
modifies a global variable (the count). Memo functions are another
|
|
example (where a table of previous calls is kept and consulted to
|
|
avoid re-computation).
|
|
|
|
Note also that the normal rules excluding optimization of subprograms
|
|
in pure units (when parameter types are descended from System.Address,
|
|
or when the full view of a parameter type is limited), do not apply
|
|
for the Pure_Function case. If you explicitly specify Pure_Function,
|
|
the compiler may optimize away calls with identical arguments, and
|
|
if that results in unexpected behavior, the proper action is not to
|
|
use the pragma for subprograms that are not (conceptually) pure.
|
|
|
|
@findex Pure
|
|
Note: Most functions in a @code{Pure} package are automatically pure, and
|
|
there is no need to use pragma @code{Pure_Function} for such functions. One
|
|
exception is any function that has at least one formal of type
|
|
@code{System.Address} or a type derived from it. Such functions are not
|
|
considered pure by default, since the compiler assumes that the
|
|
@code{Address} parameter may be functioning as a pointer and that the
|
|
referenced data may change even if the address value does not.
|
|
Similarly, imported functions are not considered to be pure by default,
|
|
since there is no way of checking that they are in fact pure. The use
|
|
of pragma @code{Pure_Function} for such a function will override these default
|
|
assumption, and cause the compiler to treat a designated subprogram as pure
|
|
in these cases.
|
|
|
|
Note: If pragma @code{Pure_Function} is applied to a renamed function, it
|
|
applies to the underlying renamed function. This can be used to
|
|
disambiguate cases of overloading where some but not all functions
|
|
in a set of overloaded functions are to be designated as pure.
|
|
|
|
If pragma @code{Pure_Function} is applied to a library level function, the
|
|
function is also considered pure from an optimization point of view, but the
|
|
unit is not a Pure unit in the categorization sense. So for example, a function
|
|
thus marked is free to @code{with} non-pure units.
|
|
|
|
@node Pragma Remote_Access_Type
|
|
@unnumberedsec Pragma Remote_Access_Type
|
|
@findex Remote_Access_Type
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma appears in the formal part of a generic declaration.
|
|
It specifies an exception to the RM rule from E.2.2(17/2), which forbids
|
|
the use of a remote access to class-wide type as actual for a formal
|
|
access type.
|
|
|
|
When this pragma applies to a formal access type @code{Entity}, that
|
|
type is treated as a remote access to class-wide type in the generic.
|
|
It must be a formal general access type, and its designated type must
|
|
be the class-wide type of a formal tagged limited private type from the
|
|
same generic declaration.
|
|
|
|
In the generic unit, the formal type is subject to all restrictions
|
|
pertaining to remote access to class-wide types. At instantiation, the
|
|
actual type must be a remote access to class-wide type.
|
|
|
|
@node Pragma Restriction_Warnings
|
|
@unnumberedsec Pragma Restriction_Warnings
|
|
@findex Restriction_Warnings
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Restriction_Warnings
|
|
(restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma allows a series of restriction identifiers to be
|
|
specified (the list of allowed identifiers is the same as for
|
|
pragma @code{Restrictions}). For each of these identifiers
|
|
the compiler checks for violations of the restriction, but
|
|
generates a warning message rather than an error message
|
|
if the restriction is violated.
|
|
|
|
@node Pragma Shared
|
|
@unnumberedsec Pragma Shared
|
|
@findex Shared
|
|
|
|
@noindent
|
|
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.
|
|
|
|
@node Pragma Short_Descriptors
|
|
@unnumberedsec Pragma Short_Descriptors
|
|
@findex Short_Descriptors
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Short_Descriptors
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In VMS versions of the compiler, this configuration pragma causes all
|
|
occurrences of the mechanism types Descriptor[_xxx] to be treated as
|
|
Short_Descriptor[_xxx]. This is helpful in porting legacy applications from a
|
|
32-bit environment to a 64-bit environment. This pragma is ignored for non-VMS
|
|
versions.
|
|
|
|
@node Pragma Simple_Storage_Pool_Type
|
|
@unnumberedsec Pragma Simple_Storage_Pool_Type
|
|
@findex Simple_Storage_Pool_Type
|
|
@cindex Storage pool, simple
|
|
@cindex Simple storage pool
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A type can be established as a ``simple storage pool type'' by applying
|
|
the representation pragma @code{Simple_Storage_Pool_Type} to the type.
|
|
A type named in the pragma must be a library-level immutably limited record
|
|
type or limited tagged type declared immediately within a package declaration.
|
|
The type can also be a limited private type whose full type is allowed as
|
|
a simple storage pool type.
|
|
|
|
For a simple storage pool type @var{SSP}, nonabstract primitive subprograms
|
|
@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
|
|
are subtype conformant with the following subprogram declarations:
|
|
|
|
@smallexample @c ada
|
|
procedure Allocate
|
|
(Pool : in out SSP;
|
|
Storage_Address : out System.Address;
|
|
Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
|
|
Alignment : System.Storage_Elements.Storage_Count);
|
|
|
|
procedure Deallocate
|
|
(Pool : in out SSP;
|
|
Storage_Address : System.Address;
|
|
Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
|
|
Alignment : System.Storage_Elements.Storage_Count);
|
|
|
|
function Storage_Size (Pool : SSP)
|
|
return System.Storage_Elements.Storage_Count;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
|
|
@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
|
|
applying an unchecked deallocation has no effect other than to set its actual
|
|
parameter to null. If @code{Storage_Size} is not declared, then the
|
|
@code{Storage_Size} attribute applied to an access type associated with
|
|
a pool object of type SSP returns zero. Additional operations can be declared
|
|
for a simple storage pool type (such as for supporting a mark/release
|
|
storage-management discipline).
|
|
|
|
An object of a simple storage pool type can be associated with an access
|
|
type by specifying the attribute @code{Simple_Storage_Pool}. For example:
|
|
|
|
@smallexample @c ada
|
|
|
|
My_Pool : My_Simple_Storage_Pool_Type;
|
|
|
|
type Acc is access My_Data_Type;
|
|
|
|
for Acc'Simple_Storage_Pool use My_Pool;
|
|
|
|
@end smallexample
|
|
|
|
@noindent
|
|
See attribute @code{Simple_Storage_Pool} for further details.
|
|
|
|
@node Pragma Source_File_Name
|
|
@unnumberedsec Pragma Source_File_Name
|
|
@findex Source_File_Name
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Source_File_Name (
|
|
[Unit_Name =>] unit_NAME,
|
|
Spec_File_Name => STRING_LITERAL,
|
|
[Index => INTEGER_LITERAL]);
|
|
|
|
pragma Source_File_Name (
|
|
[Unit_Name =>] unit_NAME,
|
|
Body_File_Name => STRING_LITERAL,
|
|
[Index => INTEGER_LITERAL]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Use this to override the normal naming convention. It is a configuration
|
|
pragma, and so has the usual applicability of configuration pragmas
|
|
(i.e.@: it applies to either an entire partition, or to all units in a
|
|
compilation, or to a single unit, depending on how it is used.
|
|
@var{unit_name} is mapped to @var{file_name_literal}. The identifier for
|
|
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]);
|
|
|
|
pragma Source_File_Name
|
|
( [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]);
|
|
|
|
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The first argument is a pattern that contains a single asterisk indicating
|
|
the point at which the unit name is to be inserted in the pattern string
|
|
to form the file name. The second argument is optional. If present it
|
|
specifies the casing of the unit name in the resulting file name string.
|
|
The default is lower case. Finally the third argument allows for systematic
|
|
replacement of any dots in the unit name by the specified string literal.
|
|
|
|
Note that Source_File_Name pragmas should not be used if you are using
|
|
project files. The reason for this rule is that the project manager is not
|
|
aware of these pragmas, and so other tools that use the projet file would not
|
|
be aware of the intended naming conventions. If you are using project files,
|
|
file naming is controlled by Source_File_Name_Project pragmas, which are
|
|
usually supplied automatically by the project manager. A pragma
|
|
Source_File_Name cannot appear after a @ref{Pragma Source_File_Name_Project}.
|
|
|
|
For more details on the use of the @code{Source_File_Name} pragma,
|
|
@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
|
|
and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
|
|
User's Guide}.
|
|
|
|
@node Pragma Source_File_Name_Project
|
|
@unnumberedsec Pragma Source_File_Name_Project
|
|
@findex Source_File_Name_Project
|
|
@noindent
|
|
|
|
This pragma has the same syntax and semantics as pragma Source_File_Name.
|
|
It is only allowed as a stand alone configuration pragma.
|
|
It cannot appear after a @ref{Pragma Source_File_Name}, and
|
|
most importantly, once pragma Source_File_Name_Project appears,
|
|
no further Source_File_Name pragmas are allowed.
|
|
|
|
The intention is that Source_File_Name_Project pragmas are always
|
|
generated by the Project Manager in a manner consistent with the naming
|
|
specified in a project file, and when naming is controlled in this manner,
|
|
it is not permissible to attempt to modify this naming scheme using
|
|
Source_File_Name or Source_File_Name_Project pragmas (which would not be
|
|
known to the project manager).
|
|
|
|
@node Pragma Source_Reference
|
|
@unnumberedsec Pragma Source_Reference
|
|
@findex Source_Reference
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma must appear as the first line of a source file.
|
|
@var{integer_literal} is the logical line number of the line following
|
|
the pragma line (for use in error messages and debugging
|
|
information). @var{string_literal} is a static string constant that
|
|
specifies the file name to be used in error messages and debugging
|
|
information. This is most notably used for the output of @code{gnatchop}
|
|
with the @option{-r} switch, to make sure that the original unchopped
|
|
source file is the one referred to.
|
|
|
|
The second argument must be a string literal, it cannot be a static
|
|
string expression other than a string literal. This is because its value
|
|
is needed for error messages issued by all phases of the compiler.
|
|
|
|
@node Pragma Static_Elaboration_Desired
|
|
@unnumberedsec Pragma Static_Elaboration_Desired
|
|
@findex Static_Elaboration_Desired
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Static_Elaboration_Desired;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used to indicate that the compiler should attempt to initialize
|
|
statically the objects declared in the library unit to which the pragma applies,
|
|
when these objects are initialized (explicitly or implicitly) by an aggregate.
|
|
In the absence of this pragma, aggregates in object declarations are expanded
|
|
into assignments and loops, even when the aggregate components are static
|
|
constants. When the aggregate is present the compiler builds a static expression
|
|
that requires no run-time code, so that the initialized object can be placed in
|
|
read-only data space. If the components are not static, or the aggregate has
|
|
more that 100 components, the compiler emits a warning that the pragma cannot
|
|
be obeyed. (See also the restriction No_Implicit_Loops, which supports static
|
|
construction of larger aggregates with static components that include an others
|
|
choice.)
|
|
|
|
@node Pragma Stream_Convert
|
|
@unnumberedsec Pragma Stream_Convert
|
|
@findex Stream_Convert
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Stream_Convert (
|
|
[Entity =>] type_LOCAL_NAME,
|
|
[Read =>] function_NAME,
|
|
[Write =>] function_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma provides an efficient way of providing stream functions for
|
|
types defined in packages. Not only is it simpler to use than declaring
|
|
the necessary functions with attribute representation clauses, but more
|
|
significantly, it allows the declaration to made in such a way that the
|
|
stream packages are not loaded unless they are needed. The use of
|
|
the Stream_Convert pragma adds no overhead at all, unless the stream
|
|
attributes are actually used on the designated type.
|
|
|
|
The first argument specifies the type for which stream functions are
|
|
provided. The second parameter provides a function used to read values
|
|
of this type. It must name a function whose argument type may be any
|
|
subtype, and whose returned type must be the type given as the first
|
|
argument to the pragma.
|
|
|
|
The meaning of the @var{Read}
|
|
parameter is that if a stream attribute directly
|
|
or indirectly specifies reading of the type given as the first parameter,
|
|
then a value of the type given as the argument to the Read function is
|
|
read from the stream, and then the Read function is used to convert this
|
|
to the required target type.
|
|
|
|
Similarly the @var{Write} parameter specifies how to treat write attributes
|
|
that directly or indirectly apply to the type given as the first parameter.
|
|
It must have an input parameter of the type specified by the first parameter,
|
|
and the return type must be the same as the input type of the Read function.
|
|
The effect is to first call the Write function to convert to the given stream
|
|
type, and then write the result type to the stream.
|
|
|
|
The Read and Write functions must not be overloaded subprograms. If necessary
|
|
renamings can be supplied to meet this requirement.
|
|
The usage of this attribute is best illustrated by a simple example, taken
|
|
from the GNAT implementation of package Ada.Strings.Unbounded:
|
|
|
|
@smallexample @c ada
|
|
function To_Unbounded (S : String)
|
|
return Unbounded_String
|
|
renames To_Unbounded_String;
|
|
|
|
pragma Stream_Convert
|
|
(Unbounded_String, To_Unbounded, To_String);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The specifications of the referenced functions, as given in the Ada
|
|
Reference Manual are:
|
|
|
|
@smallexample @c ada
|
|
function To_Unbounded_String (Source : String)
|
|
return Unbounded_String;
|
|
|
|
function To_String (Source : Unbounded_String)
|
|
return String;
|
|
@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 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
|
|
@findex Style_Checks
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Style_Checks (string_LITERAL | ALL_CHECKS |
|
|
On | Off [, LOCAL_NAME]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used in conjunction with compiler switches to control the
|
|
built in style checking provided by GNAT@. The compiler switches, if set,
|
|
provide an initial setting for the switches, and this pragma may be used
|
|
to modify these settings, or the settings may be provided entirely by
|
|
the use of the pragma. This pragma can be used anywhere that a pragma
|
|
is legal, including use as a configuration pragma (including use in
|
|
the @file{gnat.adc} file).
|
|
|
|
The form with a string literal specifies which style options are to be
|
|
activated. These are additive, so they apply in addition to any previously
|
|
set style check options. The codes for the options are the same as those
|
|
used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
|
|
For example the following two methods can be used to enable
|
|
layout checking:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@smallexample @c ada
|
|
pragma Style_Checks ("l");
|
|
@end smallexample
|
|
|
|
@item
|
|
@smallexample
|
|
gcc -c -gnatyl @dots{}
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@noindent
|
|
The form ALL_CHECKS activates all standard checks (its use is equivalent
|
|
to the use of the @code{gnaty} switch with no options. @xref{Top,
|
|
@value{EDITION} User's Guide, About This Guide, gnat_ugn,
|
|
@value{EDITION} User's Guide}, for details.)
|
|
|
|
Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used).
|
|
In this case, ALL_CHECKS implies the standard set of GNAT mode style check
|
|
options (i.e. equivalent to -gnatyg).
|
|
|
|
The forms with @code{Off} and @code{On}
|
|
can be used to temporarily disable style checks
|
|
as shown in the following example:
|
|
|
|
@smallexample @c ada
|
|
@iftex
|
|
@leftskip=0cm
|
|
@end iftex
|
|
pragma Style_Checks ("k"); -- requires keywords in lower case
|
|
pragma Style_Checks (Off); -- turn off style checks
|
|
NULL; -- this will not generate an error message
|
|
pragma Style_Checks (On); -- turn style checks back on
|
|
NULL; -- this will generate an error message
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Finally the two argument form is allowed only if the first argument is
|
|
@code{On} or @code{Off}. The effect is to turn of semantic style checks
|
|
for the specified entity, as shown in the following example:
|
|
|
|
@smallexample @c ada
|
|
@iftex
|
|
@leftskip=0cm
|
|
@end iftex
|
|
pragma Style_Checks ("r"); -- require consistency of identifier casing
|
|
Arg : Integer;
|
|
Rf1 : Integer := ARG; -- incorrect, wrong case
|
|
pragma Style_Checks (Off, Arg);
|
|
Rf2 : Integer := ARG; -- OK, no error
|
|
@end smallexample
|
|
|
|
@node Pragma Subtitle
|
|
@unnumberedsec Pragma Subtitle
|
|
@findex Subtitle
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Subtitle ([Subtitle =>] STRING_LITERAL);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is recognized for compatibility with other Ada compilers
|
|
but is ignored by GNAT@.
|
|
|
|
@node Pragma Suppress
|
|
@unnumberedsec Pragma Suppress
|
|
@findex Suppress
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Suppress (Identifier [, [On =>] Name]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a standard pragma, and supports all the check names required in
|
|
the RM. It is included here because GNAT recognizes one additional check
|
|
name: @code{Alignment_Check} which can be used to suppress alignment checks
|
|
on addresses used in address clauses. Such checks can also be suppressed
|
|
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
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Suppress_All;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma can appear anywhere within a unit.
|
|
The effect is to apply @code{Suppress (All_Checks)} to the unit
|
|
in which it appears. This pragma is implemented for compatibility with DEC
|
|
Ada 83 usage where it appears at the end of a unit, and for compatibility
|
|
with Rational Ada, where it appears as a program unit pragma.
|
|
The use of the standard Ada pragma @code{Suppress (All_Checks)}
|
|
as a normal configuration pragma is the preferred usage in GNAT@.
|
|
|
|
@node Pragma Suppress_Exception_Locations
|
|
@unnumberedsec Pragma Suppress_Exception_Locations
|
|
@findex Suppress_Exception_Locations
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Suppress_Exception_Locations;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In normal mode, a raise statement for an exception by default generates
|
|
an exception message giving the file name and line number for the location
|
|
of the raise. This is useful for debugging and logging purposes, but this
|
|
entails extra space for the strings for the messages. The configuration
|
|
pragma @code{Suppress_Exception_Locations} can be used to suppress the
|
|
generation of these strings, with the result that space is saved, but the
|
|
exception message for such raises is null. This configuration pragma may
|
|
appear in a global configuration pragma file, or in a specific unit as
|
|
usual. It is not required that this pragma be used consistently within
|
|
a partition, so it is fine to have some units within a partition compiled
|
|
with this pragma and others compiled in normal mode without it.
|
|
|
|
@node Pragma Suppress_Initialization
|
|
@unnumberedsec Pragma Suppress_Initialization
|
|
@findex Suppress_Initialization
|
|
@cindex Suppressing initialization
|
|
@cindex Initialization, suppression of
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Suppress_Initialization ([Entity =>] subtype_Name);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here subtype_Name is the name introduced by a type declaration
|
|
or subtype declaration.
|
|
This pragma suppresses any implicit or explicit initialization
|
|
for all variables of the given type or subtype,
|
|
including initialization resulting from the use of pragmas
|
|
Normalize_Scalars or Initialize_Scalars.
|
|
|
|
This is considered a representation item, so it cannot be given after
|
|
the type is frozen. It applies to all subsequent object declarations,
|
|
and also any allocator that creates objects of the type.
|
|
|
|
If the pragma is given for the first subtype, then it is considered
|
|
to apply to the base type and all its subtypes. If the pragma is given
|
|
for other than a first subtype, then it applies only to the given subtype.
|
|
The pragma may not be given after the type is frozen.
|
|
|
|
@node Pragma Task_Info
|
|
@unnumberedsec Pragma Task_Info
|
|
@findex Task_Info
|
|
@noindent
|
|
Syntax
|
|
|
|
@smallexample @c ada
|
|
pragma Task_Info (EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma appears within a task definition (like pragma
|
|
@code{Priority}) and applies to the task in which it appears. The
|
|
argument must be of type @code{System.Task_Info.Task_Info_Type}.
|
|
The @code{Task_Info} pragma provides system dependent control over
|
|
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 spec of package System.Task_Info in the runtime
|
|
library.
|
|
|
|
@node Pragma Task_Name
|
|
@unnumberedsec Pragma Task_Name
|
|
@findex Task_Name
|
|
@noindent
|
|
Syntax
|
|
|
|
@smallexample @c ada
|
|
pragma Task_Name (string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma appears within a task definition (like pragma
|
|
@code{Priority}) and applies to the task in which it appears. The
|
|
argument must be of type String, and provides a name to be used for
|
|
the task instance when the task is created. Note that this expression
|
|
is not required to be static, and in particular, it can contain
|
|
references to task discriminants. This facility can be used to
|
|
provide different names for different tasks as they are created,
|
|
as illustrated in the example below.
|
|
|
|
The task name is recorded internally in the run-time structures
|
|
and is accessible to tools like the debugger. In addition the
|
|
routine @code{Ada.Task_Identification.Image} will return this
|
|
string, with a unique task address appended.
|
|
|
|
@smallexample @c ada
|
|
-- Example of the use of pragma Task_Name
|
|
|
|
with Ada.Task_Identification;
|
|
use Ada.Task_Identification;
|
|
with Text_IO; use Text_IO;
|
|
procedure t3 is
|
|
|
|
type Astring is access String;
|
|
|
|
task type Task_Typ (Name : access String) is
|
|
pragma Task_Name (Name.all);
|
|
end Task_Typ;
|
|
|
|
task body Task_Typ is
|
|
Nam : constant String := Image (Current_Task);
|
|
begin
|
|
Put_Line ("-->" & Nam (1 .. 14) & "<--");
|
|
end Task_Typ;
|
|
|
|
type Ptr_Task is access Task_Typ;
|
|
Task_Var : Ptr_Task;
|
|
|
|
begin
|
|
Task_Var :=
|
|
new Task_Typ (new String'("This is task 1"));
|
|
Task_Var :=
|
|
new Task_Typ (new String'("This is task 2"));
|
|
end;
|
|
@end smallexample
|
|
|
|
@node Pragma Task_Storage
|
|
@unnumberedsec Pragma Task_Storage
|
|
@findex Task_Storage
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Task_Storage (
|
|
[Task_Type =>] LOCAL_NAME,
|
|
[Top_Guard =>] static_integer_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma specifies the length of the guard area for tasks. The guard
|
|
area is an additional storage area allocated to a task. A value of zero
|
|
means that either no guard area is created or a minimal guard area is
|
|
created, depending on the target. This pragma can appear anywhere a
|
|
@code{Storage_Size} attribute definition clause is allowed for a task
|
|
type.
|
|
|
|
@node Pragma Test_Case
|
|
@unnumberedsec Pragma Test_Case
|
|
@cindex Test cases
|
|
@findex Test_Case
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Test_Case (
|
|
[Name =>] static_string_Expression
|
|
,[Mode =>] (Nominal | Robustness)
|
|
[, Requires => Boolean_Expression]
|
|
[, Ensures => Boolean_Expression]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @code{Test_Case} pragma allows defining fine-grain specifications
|
|
for use by testing and verification tools. The compiler checks its
|
|
validity but the presence of pragma @code{Test_Case} does not lead to
|
|
any modification of the code generated by the compiler.
|
|
|
|
@code{Test_Case} pragmas may only appear immediately following the
|
|
(separate) declaration of a subprogram in a package declaration, inside
|
|
a package spec unit. Only other pragmas may intervene (that is appear
|
|
between the subprogram declaration and a test case).
|
|
|
|
The compiler checks that boolean expressions given in @code{Requires} and
|
|
@code{Ensures} are valid, where the rules for @code{Requires} are the
|
|
same as the rule for an expression in @code{Precondition} and the rules
|
|
for @code{Ensures} are the same as the rule for an expression in
|
|
@code{Postcondition}. In particular, attributes @code{'Old} and
|
|
@code{'Result} can only be used within the @code{Ensures}
|
|
expression. 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 Test_Case (Name => "Test 1",
|
|
Mode => Nominal,
|
|
Requires => Arg < 100,
|
|
Ensures => Sqrt'Result < 10);
|
|
...
|
|
end Math_Functions;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The meaning of a test case is that, if the associated subprogram is
|
|
executed in a context where @code{Requires} holds, then @code{Ensures}
|
|
should hold when the subprogram returns. Mode @code{Nominal} indicates
|
|
that the input context should satisfy the precondition of the
|
|
subprogram, and the output context should then satisfy its
|
|
postcondition. More @code{Robustness} indicates that the pre- and
|
|
postcondition of the subprogram should be ignored for this test case.
|
|
|
|
@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
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Time_Slice (static_duration_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
For implementations of GNAT on operating systems where it is possible
|
|
to supply a time slice value, this pragma may be used for this purpose.
|
|
It is ignored if it is used in a system that does not allow this control,
|
|
or if it appears in other than the main program unit.
|
|
@cindex OpenVMS
|
|
Note that the effect of this pragma is identical to the effect of the
|
|
DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
|
|
|
|
@node Pragma Title
|
|
@unnumberedsec Pragma Title
|
|
@findex Title
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Title (TITLING_OPTION [, TITLING OPTION]);
|
|
|
|
TITLING_OPTION ::=
|
|
[Title =>] STRING_LITERAL,
|
|
| [Subtitle =>] STRING_LITERAL
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Syntax checked but otherwise ignored by GNAT@. This is a listing control
|
|
pragma used in DEC Ada 83 implementations to provide a title and/or
|
|
subtitle for the program listing. The program listing generated by GNAT
|
|
does not have titles or subtitles.
|
|
|
|
Unlike other pragmas, the full flexibility of named notation is allowed
|
|
for this pragma, i.e.@: the parameters may be given in any order if named
|
|
notation is used, and named and positional notation can be mixed
|
|
following the normal rules for procedure calls in Ada.
|
|
|
|
@node Pragma Unchecked_Union
|
|
@unnumberedsec Pragma Unchecked_Union
|
|
@cindex Unions in C
|
|
@findex Unchecked_Union
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unchecked_Union (first_subtype_LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used to specify a representation of a record type that is
|
|
equivalent to a C union. It was introduced as a GNAT implementation defined
|
|
pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
|
|
pragma, making it language defined, and GNAT fully implements this extended
|
|
version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
|
|
details, consult the Ada 2005 Reference Manual, section B.3.3.
|
|
|
|
@node Pragma Unimplemented_Unit
|
|
@unnumberedsec Pragma Unimplemented_Unit
|
|
@findex Unimplemented_Unit
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unimplemented_Unit;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If this pragma occurs in a unit that is processed by the compiler, GNAT
|
|
aborts with the message @samp{@var{xxx} not implemented}, where
|
|
@var{xxx} is the name of the current compilation unit. This pragma is
|
|
intended to allow the compiler to handle unimplemented library units in
|
|
a clean manner.
|
|
|
|
The abort only happens if code is being generated. Thus you can use
|
|
specs of unimplemented packages in syntax or semantic checking mode.
|
|
|
|
@node Pragma Universal_Aliasing
|
|
@unnumberedsec Pragma Universal_Aliasing
|
|
@findex Universal_Aliasing
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{type_LOCAL_NAME} must refer to a type declaration in the current
|
|
declarative part. The effect is to inhibit strict type-based aliasing
|
|
optimization for the given type. In other words, the effect is as though
|
|
access types designating this type were subject to pragma No_Strict_Aliasing.
|
|
For a detailed description of the strict aliasing optimization, and the
|
|
situations in which it must be suppressed, @xref{Optimization and Strict
|
|
Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
|
|
|
|
@node Pragma Universal_Data
|
|
@unnumberedsec Pragma Universal_Data
|
|
@findex Universal_Data
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Universal_Data [(library_unit_Name)];
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is supported only for the AAMP target and is ignored for
|
|
other targets. The pragma specifies that all library-level objects
|
|
(Counter 0 data) associated with the library unit are to be accessed
|
|
and updated using universal addressing (24-bit addresses for AAMP5)
|
|
rather than the default of 16-bit Data Environment (DENV) addressing.
|
|
Use of this pragma will generally result in less efficient code for
|
|
references to global data associated with the library unit, but
|
|
allows such data to be located anywhere in memory. This pragma is
|
|
a library unit pragma, but can also be used as a configuration pragma
|
|
(including use in the @file{gnat.adc} file). The functionality
|
|
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
|
|
@cindex Warnings, unreferenced
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
|
|
pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma signals that the entities whose names are listed are
|
|
deliberately not referenced in the current source unit. This
|
|
suppresses warnings about the
|
|
entities being unreferenced, and in addition a warning will be
|
|
generated if one of these entities is in fact subsequently referenced 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 referenced in some particular subprogram implementation
|
|
and that this is deliberate. It can also be useful in the case of
|
|
objects declared only for their initialization or finalization side
|
|
effects.
|
|
|
|
If @code{LOCAL_NAME} identifies more than one matching homonym in the
|
|
current scope, then the entity most recently declared is the one to which
|
|
the pragma applies. Note that in the case of accept formals, the pragma
|
|
Unreferenced may appear immediately after the keyword @code{do} which
|
|
allows the indication of whether or not accept formals are referenced
|
|
or not to be given individually for each accept statement.
|
|
|
|
The left hand side of an assignment does not count as a reference for the
|
|
purpose of this pragma. Thus it is fine to assign to an entity for which
|
|
pragma Unreferenced is given.
|
|
|
|
Note that if a warning is desired for all calls to a given subprogram,
|
|
regardless of whether they occur in the same unit as the subprogram
|
|
declaration, then this pragma should not be used (calls from another
|
|
unit would not be flagged); pragma Obsolescent can be used instead
|
|
for this purpose, see @xref{Pragma Obsolescent}.
|
|
|
|
The second form of pragma @code{Unreferenced} is used within a context
|
|
clause. In this case the arguments must be unit names of units previously
|
|
mentioned in @code{with} clauses (similar to the usage of pragma
|
|
@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
|
|
units and unreferenced entities within these units.
|
|
|
|
@node Pragma Unreferenced_Objects
|
|
@unnumberedsec Pragma Unreferenced_Objects
|
|
@findex Unreferenced_Objects
|
|
@cindex Warnings, unreferenced
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma signals that for the types or subtypes whose names are
|
|
listed, objects which are declared with one of these types or subtypes may
|
|
not be referenced, and if no references appear, no warnings are given.
|
|
|
|
This is particularly useful for objects which are declared solely for their
|
|
initialization and finalization effect. Such variables are sometimes referred
|
|
to as RAII variables (Resource Acquisition Is Initialization). Using this
|
|
pragma on the relevant type (most typically a limited controlled type), the
|
|
compiler will automatically suppress unwanted warnings about these variables
|
|
not being referenced.
|
|
|
|
@node Pragma Unreserve_All_Interrupts
|
|
@unnumberedsec Pragma Unreserve_All_Interrupts
|
|
@findex Unreserve_All_Interrupts
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unreserve_All_Interrupts;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Normally certain interrupts are reserved to the implementation. Any attempt
|
|
to attach an interrupt causes Program_Error to be raised, as described in
|
|
RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
|
|
many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
|
|
reserved to the implementation, so that @kbd{Ctrl-C} can be used to
|
|
interrupt execution.
|
|
|
|
If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
|
|
a program, then all such interrupts are unreserved. This allows the
|
|
program to handle these interrupts, but disables their standard
|
|
functions. For example, if this pragma is used, then pressing
|
|
@kbd{Ctrl-C} will not automatically interrupt execution. However,
|
|
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 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
|
|
the @code{Unreserve_All_Interrupts} pragma.
|
|
|
|
For a more general facility for controlling what interrupts can be
|
|
handled, see pragma @code{Interrupt_State}, which subsumes the functionality
|
|
of the @code{Unreserve_All_Interrupts} pragma.
|
|
|
|
@node Pragma Unsuppress
|
|
@unnumberedsec Pragma Unsuppress
|
|
@findex Unsuppress
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma undoes the effect of a previous pragma @code{Suppress}. If
|
|
there is no corresponding pragma @code{Suppress} in effect, it has no
|
|
effect. The range of the effect is the same as for pragma
|
|
@code{Suppress}. The meaning of the arguments is identical to that used
|
|
in pragma @code{Suppress}.
|
|
|
|
One important application is to ensure that checks are on in cases where
|
|
code depends on the checks for its correct functioning, so that the code
|
|
will compile correctly even if the compiler switches are set to suppress
|
|
checks.
|
|
|
|
@node Pragma Use_VADS_Size
|
|
@unnumberedsec Pragma Use_VADS_Size
|
|
@cindex @code{Size}, VADS compatibility
|
|
@findex Use_VADS_Size
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Use_VADS_Size;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is a configuration pragma. In a unit to which it applies, any use
|
|
of the 'Size attribute is automatically interpreted as a use of the
|
|
'VADS_Size attribute. Note that this may result in incorrect semantic
|
|
processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
|
|
the handling of existing code which depends on the interpretation of Size
|
|
as implemented in the VADS compiler. See description of the VADS_Size
|
|
attribute for further details.
|
|
|
|
@node Pragma Validity_Checks
|
|
@unnumberedsec Pragma Validity_Checks
|
|
@findex Validity_Checks
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is used in conjunction with compiler switches to control the
|
|
built-in validity checking provided by GNAT@. The compiler switches, if set
|
|
provide an initial setting for the switches, and this pragma may be used
|
|
to modify these settings, or the settings may be provided entirely by
|
|
the use of the pragma. This pragma can be used anywhere that a pragma
|
|
is legal, including use as a configuration pragma (including use in
|
|
the @file{gnat.adc} file).
|
|
|
|
The form with a string literal specifies which validity options are to be
|
|
activated. The validity checks are first set to include only the default
|
|
reference manual settings, and then a string of letters in the string
|
|
specifies the exact set of options required. The form of this string
|
|
is exactly as described for the @option{-gnatVx} compiler switch (see the
|
|
GNAT users guide for details). For example the following two methods
|
|
can be used to enable validity checking for mode @code{in} and
|
|
@code{in out} subprogram parameters:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@smallexample @c ada
|
|
pragma Validity_Checks ("im");
|
|
@end smallexample
|
|
|
|
@item
|
|
@smallexample
|
|
gcc -c -gnatVim @dots{}
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@noindent
|
|
The form ALL_CHECKS activates all standard checks (its use is equivalent
|
|
to the use of the @code{gnatva} switch.
|
|
|
|
The forms with @code{Off} and @code{On}
|
|
can be used to temporarily disable validity checks
|
|
as shown in the following example:
|
|
|
|
@smallexample @c ada
|
|
@iftex
|
|
@leftskip=0cm
|
|
@end iftex
|
|
pragma Validity_Checks ("c"); -- validity checks for copies
|
|
pragma Validity_Checks (Off); -- turn off validity checks
|
|
A := B; -- B will not be validity checked
|
|
pragma Validity_Checks (On); -- turn validity checks back on
|
|
A := C; -- C will be validity checked
|
|
@end smallexample
|
|
|
|
@node Pragma Volatile
|
|
@unnumberedsec Pragma Volatile
|
|
@findex Volatile
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Volatile (LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma is defined by the Ada Reference Manual, and the GNAT
|
|
implementation is fully conformant with this definition. The reason it
|
|
is mentioned in this section is that a pragma of the same name was supplied
|
|
in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
|
|
implementation of pragma Volatile is upwards compatible with the
|
|
implementation in DEC Ada 83.
|
|
|
|
@node Pragma Warnings
|
|
@unnumberedsec Pragma Warnings
|
|
@findex Warnings
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Warnings (On | Off);
|
|
pragma Warnings (On | Off, LOCAL_NAME);
|
|
pragma Warnings (static_string_EXPRESSION);
|
|
pragma Warnings (On | Off, static_string_EXPRESSION);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Normally warnings are enabled, with the output being controlled by
|
|
the command line switch. Warnings (@code{Off}) turns off generation of
|
|
warnings until a Warnings (@code{On}) is encountered or the end of the
|
|
current unit. If generation of warnings is turned off using this
|
|
pragma, then no warning messages are output, regardless of the
|
|
setting of the command line switches.
|
|
|
|
The form with a single argument may be used as a configuration pragma.
|
|
|
|
If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
|
|
the specified entity. This suppression is effective from the point where
|
|
it occurs till the end of the extended scope of the variable (similar to
|
|
the scope of @code{Suppress}).
|
|
|
|
The form with a single static_string_EXPRESSION argument provides more precise
|
|
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. 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}.
|
|
|
|
@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
|
|
cumulative. Initially the set of warnings is the standard default set
|
|
as possibly modified by compiler switches. Then each pragma Warning
|
|
modifies this set of warnings as specified. This form of the pragma may
|
|
also be used as a configuration pragma.
|
|
|
|
The fourth form, with an @code{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 "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.
|
|
|
|
There are two ways to use the pragma in this form. The OFF form can be used as a
|
|
configuration pragma. The effect is to suppress all warnings (if any)
|
|
that match the pattern string throughout the compilation.
|
|
|
|
The second usage is to suppress a warning locally, and in this case, two
|
|
pragmas must appear in sequence:
|
|
|
|
@smallexample @c ada
|
|
pragma Warnings (Off, Pattern);
|
|
@dots{} code where given warning is to be suppressed
|
|
pragma Warnings (On, Pattern);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In this usage, the pattern string must match in the Off and On pragmas,
|
|
and at least one matching warning must be suppressed.
|
|
|
|
Note: to write a string that will match any warning, use the string
|
|
@code{"***"}. It will not work to use a single asterisk or two asterisks
|
|
since this looks like an operator name. This form with three asterisks
|
|
is similar in effect to specifying @code{pragma Warnings (Off)} except that a
|
|
matching @code{pragma Warnings (On, "***")} will be required. This can be
|
|
helpful in avoiding forgetting to turn warnings back on.
|
|
|
|
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.
|
|
|
|
Note: pragma Warnings does not affect the processing of style messages. See
|
|
separate entry for pragma Style_Checks for control of style messages.
|
|
|
|
@node Pragma Weak_External
|
|
@unnumberedsec Pragma Weak_External
|
|
@findex Weak_External
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Weak_External ([Entity =>] LOCAL_NAME);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@var{LOCAL_NAME} must refer to an object that is declared at the library
|
|
level. This pragma specifies that the given entity should be marked as a
|
|
weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
|
|
in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead
|
|
of a regular symbol, that is to say a symbol that does not have to be
|
|
resolved by the linker if used in conjunction with a pragma Import.
|
|
|
|
When a weak symbol is not resolved by the linker, its address is set to
|
|
zero. This is useful in writing interfaces to external modules that may
|
|
or may not be linked in the final executable, for example depending on
|
|
configuration settings.
|
|
|
|
If a program references at run time an entity to which this pragma has been
|
|
applied, and the corresponding symbol was not resolved at link time, then
|
|
the execution of the program is erroneous. It is not erroneous to take the
|
|
Address of such an entity, for example to guard potential references,
|
|
as shown in the example below.
|
|
|
|
Some file formats do not support weak symbols so not all target machines
|
|
support this pragma.
|
|
|
|
@smallexample @c ada
|
|
-- Example of the use of pragma Weak_External
|
|
|
|
package External_Module is
|
|
key : Integer;
|
|
pragma Import (C, key);
|
|
pragma Weak_External (key);
|
|
function Present return boolean;
|
|
end External_Module;
|
|
|
|
with System; use System;
|
|
package body External_Module is
|
|
function Present return boolean is
|
|
begin
|
|
return key'Address /= System.Null_Address;
|
|
end Present;
|
|
end External_Module;
|
|
@end smallexample
|
|
|
|
@node Pragma Wide_Character_Encoding
|
|
@unnumberedsec Pragma Wide_Character_Encoding
|
|
@findex Wide_Character_Encoding
|
|
@noindent
|
|
Syntax:
|
|
|
|
@smallexample @c ada
|
|
pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This pragma specifies the wide character encoding to be used in program
|
|
source text appearing subsequently. It is a configuration pragma, but may
|
|
also be used at any point that a pragma is allowed, and it is permissible
|
|
to have more than one such pragma in a file, allowing multiple encodings
|
|
to appear within the same file.
|
|
|
|
The argument can be an identifier or a character literal. In the identifier
|
|
case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
|
|
@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
|
|
case it is correspondingly one of the characters @samp{h}, @samp{u},
|
|
@samp{s}, @samp{e}, @samp{8}, or @samp{b}.
|
|
|
|
Note that when the pragma is used within a file, it affects only the
|
|
encoding within that file, and does not affect withed units, specs,
|
|
or subunits.
|
|
|
|
@node Implementation Defined Attributes
|
|
@chapter Implementation Defined Attributes
|
|
Ada defines (throughout the Ada reference manual,
|
|
summarized in Annex K),
|
|
a set of attributes that provide useful additional functionality in all
|
|
areas of the language. These language defined attributes are implemented
|
|
in GNAT and work as described in the Ada Reference Manual.
|
|
|
|
In addition, Ada allows implementations to define additional
|
|
attributes whose meaning is defined by the implementation. GNAT provides
|
|
a number of these implementation-dependent attributes which can be used
|
|
to extend and enhance the functionality of the compiler. This section of
|
|
the GNAT reference manual describes these additional attributes.
|
|
|
|
Note that any program using these attributes may not be portable to
|
|
other compilers (although GNAT implements this set of attributes on all
|
|
platforms). Therefore if portability to other compilers is an important
|
|
consideration, you should minimize the use of these attributes.
|
|
|
|
@menu
|
|
* Abort_Signal::
|
|
* Address_Size::
|
|
* Asm_Input::
|
|
* Asm_Output::
|
|
* AST_Entry::
|
|
* Bit::
|
|
* Bit_Position::
|
|
* Compiler_Version::
|
|
* Code_Address::
|
|
* Default_Bit_Order::
|
|
* Descriptor_Size::
|
|
* Elaborated::
|
|
* Elab_Body::
|
|
* Elab_Spec::
|
|
* Elab_Subp_Body::
|
|
* Emax::
|
|
* Enabled::
|
|
* Enum_Rep::
|
|
* Enum_Val::
|
|
* Epsilon::
|
|
* Fixed_Value::
|
|
* Has_Access_Values::
|
|
* Has_Discriminants::
|
|
* Img::
|
|
* Integer_Value::
|
|
* Invalid_Value::
|
|
* Large::
|
|
* Machine_Size::
|
|
* Mantissa::
|
|
* Max_Interrupt_Priority::
|
|
* Max_Priority::
|
|
* Maximum_Alignment::
|
|
* Mechanism_Code::
|
|
* Null_Parameter::
|
|
* Object_Size::
|
|
* Old::
|
|
* Passed_By_Reference::
|
|
* Pool_Address::
|
|
* Range_Length::
|
|
* Ref::
|
|
* Result::
|
|
* Safe_Emax::
|
|
* Safe_Large::
|
|
* Simple_Storage_Pool::
|
|
* Small::
|
|
* Storage_Unit::
|
|
* Stub_Type::
|
|
* System_Allocator_Alignment::
|
|
* Target_Name::
|
|
* Tick::
|
|
* To_Address::
|
|
* Type_Class::
|
|
* UET_Address::
|
|
* Unconstrained_Array::
|
|
* Universal_Literal_String::
|
|
* Unrestricted_Access::
|
|
* VADS_Size::
|
|
* Value_Size::
|
|
* Wchar_T_Size::
|
|
* Word_Size::
|
|
@end menu
|
|
|
|
@node Abort_Signal
|
|
@unnumberedsec Abort_Signal
|
|
@findex Abort_Signal
|
|
@noindent
|
|
@code{Standard'Abort_Signal} (@code{Standard} is the only allowed
|
|
prefix) provides the entity for the special exception used to signal
|
|
task abort or asynchronous transfer of control. Normally this attribute
|
|
should only be used in the tasking runtime (it is highly peculiar, and
|
|
completely outside the normal semantics of Ada, for a user program to
|
|
intercept the abort exception).
|
|
|
|
@node Address_Size
|
|
@unnumberedsec Address_Size
|
|
@cindex Size of @code{Address}
|
|
@findex Address_Size
|
|
@noindent
|
|
@code{Standard'Address_Size} (@code{Standard} is the only allowed
|
|
prefix) is a static constant giving the number of bits in an
|
|
@code{Address}. It is the same value as System.Address'Size,
|
|
but has the advantage of being static, while a direct
|
|
reference to System.Address'Size is non-static because Address
|
|
is a private type.
|
|
|
|
@node Asm_Input
|
|
@unnumberedsec Asm_Input
|
|
@findex Asm_Input
|
|
@noindent
|
|
The @code{Asm_Input} attribute denotes a function that takes two
|
|
parameters. The first is a string, the second is an expression of the
|
|
type designated by the prefix. The first (string) argument is required
|
|
to be a static expression, and is the constraint for the parameter,
|
|
(e.g.@: what kind of register is required). The second argument is the
|
|
value to be used as the input argument. The possible values for the
|
|
constant are the same as those used in the RTL, and are dependent on
|
|
the configuration file used to built the GCC back end.
|
|
@ref{Machine Code Insertions}
|
|
|
|
@node Asm_Output
|
|
@unnumberedsec Asm_Output
|
|
@findex Asm_Output
|
|
@noindent
|
|
The @code{Asm_Output} attribute denotes a function that takes two
|
|
parameters. The first is a string, the second is the name of a variable
|
|
of the type designated by the attribute prefix. The first (string)
|
|
argument is required to be a static expression and designates the
|
|
constraint for the parameter (e.g.@: what kind of register is
|
|
required). The second argument is the variable to be updated with the
|
|
result. The possible values for constraint are the same as those used in
|
|
the RTL, and are dependent on the configuration file used to build the
|
|
GCC back end. If there are no output operands, then this argument may
|
|
either be omitted, or explicitly given as @code{No_Output_Operands}.
|
|
@ref{Machine Code Insertions}
|
|
|
|
@node AST_Entry
|
|
@unnumberedsec AST_Entry
|
|
@cindex OpenVMS
|
|
@findex AST_Entry
|
|
@noindent
|
|
This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
|
|
the name of an entry, it yields a value of the predefined type AST_Handler
|
|
(declared in the predefined package System, as extended by the use of
|
|
pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
|
|
be called when an AST occurs. For further details, refer to the @cite{DEC Ada
|
|
Language Reference Manual}, section 9.12a.
|
|
|
|
@node Bit
|
|
@unnumberedsec Bit
|
|
@findex Bit
|
|
@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
|
|
offset within the storage unit (byte) that contains the first bit of
|
|
storage allocated for the object. The value of this attribute is of the
|
|
type @code{Universal_Integer}, and is always a non-negative number not
|
|
exceeding the value of @code{System.Storage_Unit}.
|
|
|
|
For an object that is a variable or a constant allocated in a register,
|
|
the value is zero. (The use of this attribute does not force the
|
|
allocation of a variable to memory).
|
|
|
|
For an object that is a formal parameter, this attribute applies
|
|
to either the matching actual parameter or to a copy of the
|
|
matching actual parameter.
|
|
|
|
For an access object the value is zero. Note that
|
|
@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
|
|
designated object. Similarly for a record component
|
|
@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
|
|
@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
|
|
are subject to index checks.
|
|
|
|
This attribute is designed to be compatible with the DEC Ada 83 definition
|
|
and implementation of the @code{Bit} attribute.
|
|
|
|
@node Bit_Position
|
|
@unnumberedsec Bit_Position
|
|
@findex Bit_Position
|
|
@noindent
|
|
@code{@var{R.C}'Bit_Position}, where @var{R} is a record object and C is one
|
|
of the fields of the record type, yields the bit
|
|
offset within the record contains the first bit of
|
|
storage allocated for the object. The value of this attribute is of the
|
|
type @code{Universal_Integer}. The value depends only on the field
|
|
@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 "@value{EDITION} @i{version} (20090221)".
|
|
|
|
@node Code_Address
|
|
@unnumberedsec Code_Address
|
|
@findex Code_Address
|
|
@cindex Subprogram address
|
|
@cindex Address of subprogram code
|
|
@noindent
|
|
The @code{'Address}
|
|
attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
|
|
intended effect seems to be to provide
|
|
an address value which can be used to call the subprogram by means of
|
|
an address clause as in the following example:
|
|
|
|
@smallexample @c ada
|
|
procedure K is @dots{}
|
|
|
|
procedure L;
|
|
for L'Address use K'Address;
|
|
pragma Import (Ada, L);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A call to @code{L} is then expected to result in a call to @code{K}@.
|
|
In Ada 83, where there were no access-to-subprogram values, this was
|
|
a common work-around for getting the effect of an indirect call.
|
|
GNAT implements the above use of @code{Address} and the technique
|
|
illustrated by the example code works correctly.
|
|
|
|
However, for some purposes, it is useful to have the address of the start
|
|
of the generated code for the subprogram. On some architectures, this is
|
|
not necessarily the same as the @code{Address} value described above.
|
|
For example, the @code{Address} value may reference a subprogram
|
|
descriptor rather than the subprogram itself.
|
|
|
|
The @code{'Code_Address} attribute, which can only be applied to
|
|
subprogram entities, always returns the address of the start of the
|
|
generated code of the specified subprogram, which may or may not be
|
|
the same value as is returned by the corresponding @code{'Address}
|
|
attribute.
|
|
|
|
@node Default_Bit_Order
|
|
@unnumberedsec Default_Bit_Order
|
|
@cindex Big endian
|
|
@cindex Little endian
|
|
@findex Default_Bit_Order
|
|
@noindent
|
|
@code{Standard'Default_Bit_Order} (@code{Standard} is the only
|
|
permissible prefix), provides the value @code{System.Default_Bit_Order}
|
|
as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
|
|
@code{Low_Order_First}). This is used to construct the definition of
|
|
@code{Default_Bit_Order} in package @code{System}.
|
|
|
|
@node Descriptor_Size
|
|
@unnumberedsec Descriptor_Size
|
|
@cindex Descriptor
|
|
@cindex Dope vector
|
|
@findex Descriptor_Size
|
|
@noindent
|
|
Non-static attribute @code{Descriptor_Size} returns the size in bits of the
|
|
descriptor allocated for a type. The result is non-zero only for unconstrained
|
|
array types and the returned value is of type universal integer. In GNAT, an
|
|
array descriptor contains bounds information and is located immediately before
|
|
the first element of the array.
|
|
|
|
@smallexample @c ada
|
|
type Unconstr_Array is array (Positive range <>) of Boolean;
|
|
Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The attribute takes into account any additional padding due to type alignment.
|
|
In the example above, the descriptor contains two values of type
|
|
@code{Positive} representing the low and high bound. Since @code{Positive} has
|
|
a size of 31 bits and an alignment of 4, the descriptor size is @code{2 *
|
|
Positive'Size + 2} or 64 bits.
|
|
|
|
@node Elaborated
|
|
@unnumberedsec Elaborated
|
|
@findex Elaborated
|
|
@noindent
|
|
The prefix of the @code{'Elaborated} attribute must be a unit name. The
|
|
value is a Boolean which indicates whether or not the given unit has been
|
|
elaborated. This attribute is primarily intended for internal use by the
|
|
generated code for dynamic elaboration checking, but it can also be used
|
|
in user programs. The value will always be True once elaboration of all
|
|
units has been completed. An exception is for units which need no
|
|
elaboration, the value is always False for such units.
|
|
|
|
@node Elab_Body
|
|
@unnumberedsec Elab_Body
|
|
@findex Elab_Body
|
|
@noindent
|
|
This attribute can only be applied to a program unit name. It returns
|
|
the entity for the corresponding elaboration procedure for elaborating
|
|
the body of the referenced unit. This is used in the main generated
|
|
elaboration procedure by the binder and is not normally used in any
|
|
other context. However, there may be specialized situations in which it
|
|
is useful to be able to call this elaboration procedure from Ada code,
|
|
e.g.@: if it is necessary to do selective re-elaboration to fix some
|
|
error.
|
|
|
|
@node Elab_Spec
|
|
@unnumberedsec Elab_Spec
|
|
@findex Elab_Spec
|
|
@noindent
|
|
This attribute can only be applied to a program unit name. It returns
|
|
the entity for the corresponding elaboration procedure for elaborating
|
|
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
|
|
Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
|
|
some error.
|
|
|
|
@node Elab_Subp_Body
|
|
@unnumberedsec Elab_Subp_Body
|
|
@findex Elab_Subp_Body
|
|
@noindent
|
|
This attribute can only be applied to a library level subprogram
|
|
name and is only allowed in CodePeer mode. It returns the entity
|
|
for the corresponding elaboration procedure for elaborating the body
|
|
of the referenced subprogram unit. This is used in the main generated
|
|
elaboration procedure by the binder in CodePeer mode only and is unrecognized
|
|
otherwise.
|
|
|
|
@node Emax
|
|
@unnumberedsec Emax
|
|
@cindex Ada 83 attributes
|
|
@findex Emax
|
|
@noindent
|
|
The @code{Emax} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Enabled
|
|
@unnumberedsec Enabled
|
|
@findex Enabled
|
|
@noindent
|
|
The @code{Enabled} attribute allows an application program to check at compile
|
|
time to see if the designated check is currently enabled. The prefix is a
|
|
simple identifier, referencing any predefined check name (other than
|
|
@code{All_Checks}) or a check name introduced by pragma Check_Name. If
|
|
no argument is given for the attribute, the check is for the general state
|
|
of the check, if an argument is given, then it is an entity name, and the
|
|
check indicates whether an @code{Suppress} or @code{Unsuppress} has been
|
|
given naming the entity (if not, then the argument is ignored).
|
|
|
|
Note that instantiations inherit the check status at the point of the
|
|
instantiation, so a useful idiom is to have a library package that
|
|
introduces a check name with @code{pragma Check_Name}, and then contains
|
|
generic packages or subprograms which use the @code{Enabled} attribute
|
|
to see if the check is enabled. A user of this package can then issue
|
|
a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
|
|
the package or subprogram, controlling whether the check will be present.
|
|
|
|
@node Enum_Rep
|
|
@unnumberedsec Enum_Rep
|
|
@cindex Representation of enums
|
|
@findex Enum_Rep
|
|
@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 : @var{S}'Base)
|
|
return @i{Universal_Integer};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
It is also allowable to apply @code{Enum_Rep} directly to an object of an
|
|
enumeration type or to a non-overloaded enumeration
|
|
literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
|
|
@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
|
|
enumeration literal or object.
|
|
|
|
The function returns the representation value for the given enumeration
|
|
value. This will be equal to value of the @code{Pos} attribute in the
|
|
absence of an enumeration representation clause. This is a static
|
|
attribute (i.e.@: the result is static if the argument is static).
|
|
|
|
@code{@var{S}'Enum_Rep} can also be used with integer types and objects,
|
|
in which case it simply returns the integer value. The reason for this
|
|
is to allow it to be used for @code{(<>)} discrete formal arguments in
|
|
a generic unit that can be instantiated with either enumeration types
|
|
or integer types. Note that if @code{Enum_Rep} is used on a modular
|
|
type whose upper bound exceeds the upper bound of the largest signed
|
|
integer type, and the argument is a variable, so that the universal
|
|
integer calculation is done at run time, then the call to @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_Val} denotes a
|
|
function with the following spec:
|
|
|
|
@smallexample @c ada
|
|
function @var{S}'Enum_Val (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
|
|
@findex Epsilon
|
|
@noindent
|
|
The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Fixed_Value
|
|
@unnumberedsec Fixed_Value
|
|
@findex Fixed_Value
|
|
@noindent
|
|
For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
|
|
function with the following specification:
|
|
|
|
@smallexample @c ada
|
|
function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
|
|
return @var{S};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The value returned is the fixed-point value @var{V} such that
|
|
|
|
@smallexample @c ada
|
|
@var{V} = Arg * @var{S}'Small
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The effect is thus similar to first converting the argument to the
|
|
integer type used to represent @var{S}, and then doing an unchecked
|
|
conversion to the fixed-point type. The difference is
|
|
that there are full range checks, to ensure that the result is in range.
|
|
This attribute is primarily intended for use in implementation of the
|
|
input-output functions for fixed-point values.
|
|
|
|
@node Has_Access_Values
|
|
@unnumberedsec Has_Access_Values
|
|
@cindex Access values, testing for
|
|
@findex Has_Access_Values
|
|
@noindent
|
|
The prefix of the @code{Has_Access_Values} attribute is a type. The result
|
|
is a Boolean value which is True if the is an access type, or is a composite
|
|
type with a component (at any nesting depth) that is an access type, and is
|
|
False otherwise.
|
|
The intended use of this attribute is in conjunction with generic
|
|
definitions. If the attribute is applied to a generic private type, it
|
|
indicates whether or not the corresponding actual type has access values.
|
|
|
|
@node Has_Discriminants
|
|
@unnumberedsec Has_Discriminants
|
|
@cindex Discriminants, testing for
|
|
@findex Has_Discriminants
|
|
@noindent
|
|
The prefix of the @code{Has_Discriminants} attribute is a type. The result
|
|
is a Boolean value which is True if the type has discriminants, and False
|
|
otherwise. The intended use of this attribute is in conjunction with generic
|
|
definitions. If the attribute is applied to a generic private type, it
|
|
indicates whether or not the corresponding actual type has discriminants.
|
|
|
|
@node Img
|
|
@unnumberedsec Img
|
|
@findex Img
|
|
@noindent
|
|
The @code{Img} attribute differs from @code{Image} in that it may be
|
|
applied to objects as well as types, in which case it gives the
|
|
@code{Image} for the subtype of the object. This is convenient for
|
|
debugging:
|
|
|
|
@smallexample @c ada
|
|
Put_Line ("X = " & X'Img);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
has the same meaning as the more verbose:
|
|
|
|
@smallexample @c ada
|
|
Put_Line ("X = " & @var{T}'Image (X));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{T} is the (sub)type of the object @code{X}.
|
|
|
|
@node Integer_Value
|
|
@unnumberedsec Integer_Value
|
|
@findex Integer_Value
|
|
@noindent
|
|
For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
|
|
function with the following spec:
|
|
|
|
@smallexample @c ada
|
|
function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
|
|
return @var{S};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The value returned is the integer value @var{V}, such that
|
|
|
|
@smallexample @c ada
|
|
Arg = @var{V} * @var{T}'Small
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{T} is the type of @code{Arg}.
|
|
The effect is thus similar to first doing an unchecked conversion from
|
|
the fixed-point type to its corresponding implementation type, and then
|
|
converting the result to the target integer type. The difference is
|
|
that there are full range checks, to ensure that the result is in range.
|
|
This attribute is primarily intended for use in implementation of the
|
|
standard input-output functions for fixed-point values.
|
|
|
|
@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
|
|
@findex Large
|
|
@noindent
|
|
The @code{Large} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Machine_Size
|
|
@unnumberedsec Machine_Size
|
|
@findex Machine_Size
|
|
@noindent
|
|
This attribute is identical to the @code{Object_Size} attribute. It is
|
|
provided for compatibility with the DEC Ada 83 attribute of this name.
|
|
|
|
@node Mantissa
|
|
@unnumberedsec Mantissa
|
|
@cindex Ada 83 attributes
|
|
@findex Mantissa
|
|
@noindent
|
|
The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Max_Interrupt_Priority
|
|
@unnumberedsec Max_Interrupt_Priority
|
|
@cindex Interrupt priority, maximum
|
|
@findex Max_Interrupt_Priority
|
|
@noindent
|
|
@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
|
|
permissible prefix), provides the same value as
|
|
@code{System.Max_Interrupt_Priority}.
|
|
|
|
@node Max_Priority
|
|
@unnumberedsec Max_Priority
|
|
@cindex Priority, maximum
|
|
@findex Max_Priority
|
|
@noindent
|
|
@code{Standard'Max_Priority} (@code{Standard} is the only permissible
|
|
prefix) provides the same value as @code{System.Max_Priority}.
|
|
|
|
@node Maximum_Alignment
|
|
@unnumberedsec Maximum_Alignment
|
|
@cindex Alignment, maximum
|
|
@findex Maximum_Alignment
|
|
@noindent
|
|
@code{Standard'Maximum_Alignment} (@code{Standard} is the only
|
|
permissible prefix) provides the maximum useful alignment value for the
|
|
target. This is a static value that can be used to specify the alignment
|
|
for an object, guaranteeing that it is properly aligned in all
|
|
cases.
|
|
|
|
@node Mechanism_Code
|
|
@unnumberedsec Mechanism_Code
|
|
@cindex Return values, passing mechanism
|
|
@cindex Parameters, passing mechanism
|
|
@findex Mechanism_Code
|
|
@noindent
|
|
@code{@var{function}'Mechanism_Code} yields an integer code for the
|
|
mechanism used for the result of function, and
|
|
@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
|
|
used for formal parameter number @var{n} (a static integer value with 1
|
|
meaning the first parameter) of @var{subprogram}. The code returned is:
|
|
|
|
@table @asis
|
|
@item 1
|
|
by copy (value)
|
|
@item 2
|
|
by reference
|
|
@item 3
|
|
by descriptor (default descriptor class)
|
|
@item 4
|
|
by descriptor (UBS: unaligned bit string)
|
|
@item 5
|
|
by descriptor (UBSB: aligned bit string with arbitrary bounds)
|
|
@item 6
|
|
by descriptor (UBA: unaligned bit array)
|
|
@item 7
|
|
by descriptor (S: string, also scalar access type parameter)
|
|
@item 8
|
|
by descriptor (SB: string with arbitrary bounds)
|
|
@item 9
|
|
by descriptor (A: contiguous array)
|
|
@item 10
|
|
by descriptor (NCA: non-contiguous array)
|
|
@end table
|
|
|
|
@noindent
|
|
Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
|
|
@cindex OpenVMS
|
|
|
|
@node Null_Parameter
|
|
@unnumberedsec Null_Parameter
|
|
@cindex Zero address, passing
|
|
@findex Null_Parameter
|
|
@noindent
|
|
A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
|
|
type or subtype @var{T} allocated at machine address zero. The attribute
|
|
is allowed only as the default expression of a formal parameter, or as
|
|
an actual expression of a subprogram call. In either case, the
|
|
subprogram must be imported.
|
|
|
|
The identity of the object is represented by the address zero in the
|
|
argument list, independent of the passing mechanism (explicit or
|
|
default).
|
|
|
|
This capability is needed to specify that a zero address should be
|
|
passed for a record or other composite object passed by reference.
|
|
There is no way of indicating this without the @code{Null_Parameter}
|
|
attribute.
|
|
|
|
@node Object_Size
|
|
@unnumberedsec Object_Size
|
|
@cindex Size, used for objects
|
|
@findex Object_Size
|
|
@noindent
|
|
The size of an object is not necessarily the same as the size of the type
|
|
of an object. This is because by default object sizes are increased to be
|
|
a multiple of the alignment of the object. For example,
|
|
@code{Natural'Size} is
|
|
31, but by default objects of type @code{Natural} will have a size of 32 bits.
|
|
Similarly, a record containing an integer and a character:
|
|
|
|
@smallexample @c ada
|
|
type Rec is record
|
|
I : Integer;
|
|
C : Character;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
will have a size of 40 (that is @code{Rec'Size} will be 40). The
|
|
alignment will be 4, because of the
|
|
integer field, and so the default size of record objects for this type
|
|
will be 64 (8 bytes).
|
|
|
|
@node Old
|
|
@unnumberedsec Old
|
|
@cindex Capturing Old values
|
|
@cindex Postconditions
|
|
@noindent
|
|
The attribute Prefix'Old can be used within a
|
|
subprogram body or within a precondition or
|
|
postcondition pragma. The effect is 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.
|
|
The prefix must denote an object of a nonlimited type (since limited types
|
|
cannot be copied to capture their values) and it must not reference a local
|
|
variable (since local variables do not exist at subprogram entry time). Note
|
|
that the variable introduced by a quantified expression is a local variable.
|
|
The following example shows the use of 'Old to implement
|
|
a test of a postcondition:
|
|
|
|
@smallexample @c ada
|
|
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
|
|
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
|
|
@cindex Parameters, when passed by reference
|
|
@findex Passed_By_Reference
|
|
@noindent
|
|
@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
|
|
a value of type @code{Boolean} value that is @code{True} if the type is
|
|
normally passed by reference and @code{False} if the type is normally
|
|
passed by copy in calls. For scalar types, the result is always @code{False}
|
|
and is static. For non-scalar types, the result is non-static.
|
|
|
|
@node Pool_Address
|
|
@unnumberedsec Pool_Address
|
|
@cindex Parameters, when passed by reference
|
|
@findex Pool_Address
|
|
@noindent
|
|
@code{@var{X}'Pool_Address} for any object @var{X} returns the address
|
|
of X within its storage pool. This is the same as
|
|
@code{@var{X}'Address}, except that for an unconstrained array whose
|
|
bounds are allocated just before the first component,
|
|
@code{@var{X}'Pool_Address} returns the address of those bounds,
|
|
whereas @code{@var{X}'Address} returns the address of the first
|
|
component.
|
|
|
|
Here, we are interpreting ``storage pool'' broadly to mean ``wherever
|
|
the object is allocated'', which could be a user-defined storage pool,
|
|
the global heap, on the stack, or in a static memory area. For an
|
|
object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is
|
|
what is passed to @code{Allocate} and returned from @code{Deallocate}.
|
|
|
|
@node Range_Length
|
|
@unnumberedsec Range_Length
|
|
@findex Range_Length
|
|
@noindent
|
|
@code{@var{type}'Range_Length} for any discrete type @var{type} yields
|
|
the number of values represented by the subtype (zero for a null
|
|
range). The result is static for static subtypes. @code{Range_Length}
|
|
applied to the index subtype of a one dimensional array always gives the
|
|
same result as @code{Range} applied to the array itself.
|
|
|
|
@node Ref
|
|
@unnumberedsec Ref
|
|
@findex Ref
|
|
@noindent
|
|
The @code{System.Address'Ref}
|
|
(@code{System.Address} is the only permissible prefix)
|
|
denotes a function identical to
|
|
@code{System.Storage_Elements.To_Address} except that
|
|
it is a static attribute. See @ref{To_Address} for more details.
|
|
|
|
@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
|
|
@findex Safe_Emax
|
|
@noindent
|
|
The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Safe_Large
|
|
@unnumberedsec Safe_Large
|
|
@cindex Ada 83 attributes
|
|
@findex Safe_Large
|
|
@noindent
|
|
The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute.
|
|
|
|
@node Simple_Storage_Pool
|
|
@unnumberedsec Simple_Storage_Pool
|
|
@cindex Storage pool, simple
|
|
@cindex Simple storage pool
|
|
@findex Simple_Storage_Pool
|
|
@noindent
|
|
For every nonformal, nonderived access-to-object type @var{Acc}, the
|
|
representation attribute @code{Simple_Storage_Pool} may be specified
|
|
via an attribute_definition_clause (or by specifying the equivalent aspect):
|
|
|
|
@smallexample @c ada
|
|
|
|
My_Pool : My_Simple_Storage_Pool_Type;
|
|
|
|
type Acc is access My_Data_Type;
|
|
|
|
for Acc'Simple_Storage_Pool use My_Pool;
|
|
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The name given in an attribute_definition_clause for the
|
|
@code{Simple_Storage_Pool} attribute shall denote a variable of
|
|
a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}).
|
|
|
|
The use of this attribute is only allowed for a prefix denoting a type
|
|
for which it has been specified. The type of the attribute is the type
|
|
of the variable specified as the simple storage pool of the access type,
|
|
and the attribute denotes that variable.
|
|
|
|
It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
|
|
for the same access type.
|
|
|
|
If the @code{Simple_Storage_Pool} attribute has been specified for an access
|
|
type, then applying the @code{Storage_Pool} attribute to the type is flagged
|
|
with a warning and its evaluation raises the exception @code{Program_Error}.
|
|
|
|
If the Simple_Storage_Pool attribute has been specified for an access
|
|
type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size}
|
|
returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)},
|
|
which is intended to indicate the number of storage elements reserved for
|
|
the simple storage pool. If the Storage_Size function has not been defined
|
|
for the simple storage pool type, then this attribute returns zero.
|
|
|
|
If an access type @var{S} has a specified simple storage pool of type
|
|
@var{SSP}, then the evaluation of an allocator for that access type calls
|
|
the primitive @code{Allocate} procedure for type @var{SSP}, passing
|
|
@code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed
|
|
semantics of such allocators is the same as those defined for allocators
|
|
in section 13.11 of the Ada Reference Manual, with the term
|
|
``simple storage pool'' substituted for ``storage pool''.
|
|
|
|
If an access type @var{S} has a specified simple storage pool of type
|
|
@var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
|
|
for that access type invokes the primitive @code{Deallocate} procedure
|
|
for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool
|
|
parameter. The detailed semantics of such unchecked deallocations is the same
|
|
as defined in section 13.11.2 of the Ada Reference Manual, except that the
|
|
term ``simple storage pool'' is substituted for ``storage pool''.
|
|
|
|
@node Small
|
|
@unnumberedsec Small
|
|
@cindex Ada 83 attributes
|
|
@findex Small
|
|
@noindent
|
|
The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
|
|
fixed-point types.
|
|
GNAT also allows this attribute to be applied to floating-point types
|
|
for compatibility with Ada 83. See
|
|
the Ada 83 reference manual for an exact description of the semantics of
|
|
this attribute when applied to floating-point types.
|
|
|
|
@node Storage_Unit
|
|
@unnumberedsec Storage_Unit
|
|
@findex Storage_Unit
|
|
@noindent
|
|
@code{Standard'Storage_Unit} (@code{Standard} is the only permissible
|
|
prefix) provides the same value as @code{System.Storage_Unit}.
|
|
|
|
@node Stub_Type
|
|
@unnumberedsec Stub_Type
|
|
@findex Stub_Type
|
|
@noindent
|
|
The GNAT implementation of remote access-to-classwide types is
|
|
organized as described in AARM section E.4 (20.t): a value of an RACW type
|
|
(designating a remote object) is represented as a normal access
|
|
value, pointing to a "stub" object which in turn contains the
|
|
necessary information to contact the designated remote object. A
|
|
call on any dispatching operation of such a stub object does the
|
|
remote call, if necessary, using the information in the stub object
|
|
to locate the target partition, etc.
|
|
|
|
For a prefix @code{T} that denotes a remote access-to-classwide type,
|
|
@code{T'Stub_Type} denotes the type of the corresponding stub objects.
|
|
|
|
By construction, the layout of @code{T'Stub_Type} is identical to that of
|
|
type @code{RACW_Stub_Type} declared in the internal implementation-defined
|
|
unit @code{System.Partition_Interface}. Use of this attribute will create
|
|
an implicit dependency on this unit.
|
|
|
|
@node System_Allocator_Alignment
|
|
@unnumberedsec System_Allocator_Alignment
|
|
@cindex Alignment, allocator
|
|
@findex System_Allocator_Alignment
|
|
@noindent
|
|
@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
|
|
permissible prefix) provides the observable guaranted to be honored by
|
|
the system allocator (malloc). This is a static value that can be used
|
|
in user storage pools based on malloc either to reject allocation
|
|
with alignment too large or to enable a realignment circuitry if the
|
|
alignment request is larger than this value.
|
|
|
|
@node Target_Name
|
|
@unnumberedsec Target_Name
|
|
@findex Target_Name
|
|
@noindent
|
|
@code{Standard'Target_Name} (@code{Standard} is the only permissible
|
|
prefix) provides a static string value that identifies the target
|
|
for the current compilation. For GCC implementations, this is the
|
|
standard gcc target name without the terminating slash (for
|
|
example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
|
|
|
|
@node Tick
|
|
@unnumberedsec Tick
|
|
@findex Tick
|
|
@noindent
|
|
@code{Standard'Tick} (@code{Standard} is the only permissible prefix)
|
|
provides the same value as @code{System.Tick},
|
|
|
|
@node To_Address
|
|
@unnumberedsec To_Address
|
|
@findex To_Address
|
|
@noindent
|
|
The @code{System'To_Address}
|
|
(@code{System} is the only permissible prefix)
|
|
denotes a function identical to
|
|
@code{System.Storage_Elements.To_Address} except that
|
|
it is a static attribute. This means that if its argument is
|
|
a static expression, then the result of the attribute is a
|
|
static expression. The result is that such an expression can be
|
|
used in contexts (e.g.@: preelaborable packages) which require a
|
|
static expression and where the function call could not be used
|
|
(since the function call is always non-static, even if its
|
|
argument is static).
|
|
|
|
@node Type_Class
|
|
@unnumberedsec Type_Class
|
|
@findex Type_Class
|
|
@noindent
|
|
@code{@var{type}'Type_Class} for any type or subtype @var{type} yields
|
|
the value of the type class for the full type of @var{type}. If
|
|
@var{type} is a generic formal type, the value is the value for the
|
|
corresponding actual subtype. The value of this attribute is of type
|
|
@code{System.Aux_DEC.Type_Class}, which has the following definition:
|
|
|
|
@smallexample @c ada
|
|
type Type_Class is
|
|
(Type_Class_Enumeration,
|
|
Type_Class_Integer,
|
|
Type_Class_Fixed_Point,
|
|
Type_Class_Floating_Point,
|
|
Type_Class_Array,
|
|
Type_Class_Record,
|
|
Type_Class_Access,
|
|
Type_Class_Task,
|
|
Type_Class_Address);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Protected types yield the value @code{Type_Class_Task}, which thus
|
|
applies to all concurrent types. This attribute is designed to
|
|
be compatible with the DEC Ada 83 attribute of the same name.
|
|
|
|
@node UET_Address
|
|
@unnumberedsec UET_Address
|
|
@findex UET_Address
|
|
@noindent
|
|
The @code{UET_Address} attribute can only be used for a prefix which
|
|
denotes a library package. It yields the address of the unit exception
|
|
table when zero cost exception handling is used. This attribute is
|
|
intended only for use within the GNAT implementation. See the unit
|
|
@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
|
|
for details on how this attribute is used in the implementation.
|
|
|
|
@node Unconstrained_Array
|
|
@unnumberedsec Unconstrained_Array
|
|
@findex Unconstrained_Array
|
|
@noindent
|
|
The @code{Unconstrained_Array} attribute can be used with a prefix that
|
|
denotes any type or subtype. It is a static attribute that yields
|
|
@code{True} if the prefix designates an unconstrained array,
|
|
and @code{False} otherwise. In a generic instance, the result is
|
|
still static, and yields the result of applying this test to the
|
|
generic actual.
|
|
|
|
@node Universal_Literal_String
|
|
@unnumberedsec Universal_Literal_String
|
|
@cindex Named numbers, representation of
|
|
@findex Universal_Literal_String
|
|
@noindent
|
|
The prefix of @code{Universal_Literal_String} must be a named
|
|
number. The static result is the string consisting of the characters of
|
|
the number as defined in the original source. This allows the user
|
|
program to access the actual text of named numbers without intermediate
|
|
conversions and without the need to enclose the strings in quotes (which
|
|
would preclude their use as numbers).
|
|
|
|
For example, the following program prints the first 50 digits of pi:
|
|
|
|
@smallexample @c ada
|
|
with Text_IO; use Text_IO;
|
|
with Ada.Numerics;
|
|
procedure Pi is
|
|
begin
|
|
Put (Ada.Numerics.Pi'Universal_Literal_String);
|
|
end;
|
|
@end smallexample
|
|
|
|
@node Unrestricted_Access
|
|
@unnumberedsec Unrestricted_Access
|
|
@cindex @code{Access}, unrestricted
|
|
@findex Unrestricted_Access
|
|
@noindent
|
|
The @code{Unrestricted_Access} attribute is similar to @code{Access}
|
|
except that all accessibility and aliased view checks are omitted. This
|
|
is a user-beware attribute. It is similar to
|
|
@code{Address}, for which it is a desirable replacement where the value
|
|
desired is an access type. In other words, its effect is identical to
|
|
first applying the @code{Address} attribute and then doing an unchecked
|
|
conversion to a desired access type. In GNAT, but not necessarily in
|
|
other implementations, the use of static chains for inner level
|
|
subprograms means that @code{Unrestricted_Access} applied to a
|
|
subprogram yields a value that can be called as long as the subprogram
|
|
is in scope (normal Ada accessibility rules restrict this usage).
|
|
|
|
It is possible to use @code{Unrestricted_Access} for any type, but care
|
|
must be exercised if it is used to create pointers to unconstrained
|
|
objects. In this case, the resulting pointer has the same scope as the
|
|
context of the attribute, and may not be returned to some enclosing
|
|
scope. For instance, a function cannot use @code{Unrestricted_Access}
|
|
to create a unconstrained pointer and then return that value to the
|
|
caller.
|
|
|
|
@node VADS_Size
|
|
@unnumberedsec VADS_Size
|
|
@cindex @code{Size}, VADS compatibility
|
|
@findex VADS_Size
|
|
@noindent
|
|
The @code{'VADS_Size} attribute is intended to make it easier to port
|
|
legacy code which relies on the semantics of @code{'Size} as implemented
|
|
by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
|
|
same semantic interpretation. In particular, @code{'VADS_Size} applied
|
|
to a predefined or other primitive type with no Size clause yields the
|
|
Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
|
|
typical machines). In addition @code{'VADS_Size} applied to an object
|
|
gives the result that would be obtained by applying the attribute to
|
|
the corresponding type.
|
|
|
|
@node Value_Size
|
|
@unnumberedsec Value_Size
|
|
@cindex @code{Size}, setting for not-first subtype
|
|
@findex Value_Size
|
|
@code{@var{type}'Value_Size} is the number of bits required to represent
|
|
a value of the given subtype. It is the same as @code{@var{type}'Size},
|
|
but, unlike @code{Size}, may be set for non-first subtypes.
|
|
|
|
@node Wchar_T_Size
|
|
@unnumberedsec Wchar_T_Size
|
|
@findex Wchar_T_Size
|
|
@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
|
|
prefix) provides the size in bits of the C @code{wchar_t} type
|
|
primarily for constructing the definition of this type in
|
|
package @code{Interfaces.C}.
|
|
|
|
@node Word_Size
|
|
@unnumberedsec Word_Size
|
|
@findex Word_Size
|
|
@code{Standard'Word_Size} (@code{Standard} is the only permissible
|
|
prefix) provides the value @code{System.Word_Size}.
|
|
|
|
@node Implementation Defined Restrictions
|
|
@chapter Implementation Defined Restrictions
|
|
|
|
@noindent
|
|
All RM defined Restriction identifiers are implemented:
|
|
|
|
@itemize @bullet
|
|
@item language-defined restrictions (see 13.12.1)
|
|
@item tasking restrictions (see D.7)
|
|
@item high integrity restrictions (see H.4)
|
|
@end itemize
|
|
|
|
@noindent
|
|
GNAT implements additional restriction identifiers. All restrictions, whether
|
|
language defined or GNAT-specific, are listed in the following.
|
|
|
|
@menu
|
|
* Partition-Wide Restrictions::
|
|
* Program Unit Level Restrictions::
|
|
@end menu
|
|
|
|
@node Partition-Wide Restrictions
|
|
@section Partition-Wide Restrictions
|
|
|
|
There are two separate lists of restriction identifiers. The first
|
|
set requires consistency throughout a partition (in other words, if the
|
|
restriction identifier is used for any compilation unit in the partition,
|
|
then all compilation units in the partition must obey the restriction).
|
|
|
|
@menu
|
|
* Immediate_Reclamation::
|
|
* Max_Asynchronous_Select_Nesting::
|
|
* Max_Entry_Queue_Length::
|
|
* Max_Protected_Entries::
|
|
* Max_Select_Alternatives::
|
|
* Max_Storage_At_Blocking::
|
|
* Max_Task_Entries::
|
|
* Max_Tasks::
|
|
* No_Abort_Statements::
|
|
* No_Access_Parameter_Allocators::
|
|
* No_Access_Subprograms::
|
|
* No_Allocators::
|
|
* No_Anonymous_Allocators::
|
|
* No_Calendar::
|
|
* No_Coextensions::
|
|
* No_Default_Initialization::
|
|
* No_Delay::
|
|
* No_Dependence::
|
|
* No_Direct_Boolean_Operators::
|
|
* No_Dispatch::
|
|
* No_Dispatching_Calls::
|
|
* No_Dynamic_Attachment::
|
|
* No_Dynamic_Priorities::
|
|
* No_Entry_Calls_In_Elaboration_Code::
|
|
* No_Enumeration_Maps::
|
|
* No_Exception_Handlers::
|
|
* No_Exception_Propagation::
|
|
* No_Exception_Registration::
|
|
* No_Exceptions::
|
|
* No_Finalization::
|
|
* No_Fixed_Point::
|
|
* No_Floating_Point::
|
|
* No_Implicit_Conditionals::
|
|
* No_Implicit_Dynamic_Code::
|
|
* No_Implicit_Heap_Allocations::
|
|
* No_Implicit_Loops::
|
|
* No_Initialize_Scalars::
|
|
* No_IO::
|
|
* No_Local_Allocators::
|
|
* No_Local_Protected_Objects::
|
|
* No_Local_Timing_Events::
|
|
* No_Nested_Finalization::
|
|
* No_Protected_Type_Allocators::
|
|
* No_Protected_Types::
|
|
* No_Recursion::
|
|
* No_Reentrancy::
|
|
* No_Relative_Delay::
|
|
* No_Requeue_Statements::
|
|
* No_Secondary_Stack::
|
|
* No_Select_Statements::
|
|
* No_Specific_Termination_Handlers::
|
|
* No_Specification_of_Aspect::
|
|
* No_Standard_Allocators_After_Elaboration::
|
|
* No_Standard_Storage_Pools::
|
|
* No_Stream_Optimizations::
|
|
* No_Streams::
|
|
* No_Task_Allocators::
|
|
* No_Task_Attributes_Package::
|
|
* No_Task_Hierarchy::
|
|
* No_Task_Termination::
|
|
* No_Tasking::
|
|
* No_Terminate_Alternatives::
|
|
* No_Unchecked_Access::
|
|
* Simple_Barriers::
|
|
* Static_Priorities::
|
|
* Static_Storage_Size::
|
|
@end menu
|
|
|
|
@node Immediate_Reclamation
|
|
@unnumberedsubsec Immediate_Reclamation
|
|
@findex Immediate_Reclamation
|
|
[RM H.4] This restriction ensures that, except for storage occupied by
|
|
objects created by allocators and not deallocated via unchecked
|
|
deallocation, any storage reserved at run time for an object is
|
|
immediately reclaimed when the object no longer exists.
|
|
|
|
@node Max_Asynchronous_Select_Nesting
|
|
@unnumberedsubsec Max_Asynchronous_Select_Nesting
|
|
@findex Max_Asynchronous_Select_Nesting
|
|
[RM D.7] Specifies the maximum dynamic nesting level of asynchronous
|
|
selects. Violations of this restriction with a value of zero are
|
|
detected at compile time. Violations of this restriction with values
|
|
other than zero cause Storage_Error to be raised.
|
|
|
|
@node Max_Entry_Queue_Length
|
|
@unnumberedsubsec Max_Entry_Queue_Length
|
|
@findex Max_Entry_Queue_Length
|
|
[RM D.7] This restriction is a declaration that any protected entry compiled in
|
|
the scope of the restriction has at most the specified number of
|
|
tasks waiting on the entry at any one time, and so no queue is required.
|
|
Note that this restriction is checked at run time. Violation of this
|
|
restriction results in the raising of Program_Error exception at the point of
|
|
the call.
|
|
|
|
@node Max_Protected_Entries
|
|
@unnumberedsubsec Max_Protected_Entries
|
|
@findex Max_Protected_Entries
|
|
[RM D.7] Specifies the maximum number of entries per protected type. The
|
|
bounds of every entry family of a protected unit shall be static, or shall be
|
|
defined by a discriminant of a subtype whose corresponding bound is static.
|
|
|
|
@node Max_Select_Alternatives
|
|
@unnumberedsubsec Max_Select_Alternatives
|
|
@findex Max_Select_Alternatives
|
|
[RM D.7] Specifies the maximum number of alternatives in a selective accept.
|
|
|
|
@node Max_Storage_At_Blocking
|
|
@unnumberedsubsec Max_Storage_At_Blocking
|
|
@findex Max_Storage_At_Blocking
|
|
[RM D.7] Specifies the maximum portion (in storage elements) of a task's
|
|
Storage_Size that can be retained by a blocked task. A violation of this
|
|
restriction causes Storage_Error to be raised.
|
|
|
|
@node Max_Task_Entries
|
|
@unnumberedsubsec Max_Task_Entries
|
|
@findex Max_Task_Entries
|
|
[RM D.7] Specifies the maximum number of entries
|
|
per task. The bounds of every entry family
|
|
of a task unit shall be static, or shall be
|
|
defined by a discriminant of a subtype whose
|
|
corresponding bound is static.
|
|
|
|
@node Max_Tasks
|
|
@unnumberedsubsec Max_Tasks
|
|
@findex Max_Tasks
|
|
[RM D.7] Specifies the maximum number of task that may be created, not
|
|
counting the creation of the environment task. Violations of this
|
|
restriction with a value of zero are detected at compile
|
|
time. Violations of this restriction with values other than zero cause
|
|
Storage_Error to be raised.
|
|
|
|
@node No_Abort_Statements
|
|
@unnumberedsubsec No_Abort_Statements
|
|
@findex No_Abort_Statements
|
|
[RM D.7] There are no abort_statements, and there are
|
|
no calls to Task_Identification.Abort_Task.
|
|
|
|
@node No_Access_Parameter_Allocators
|
|
@unnumberedsubsec No_Access_Parameter_Allocators
|
|
@findex No_Access_Parameter_Allocators
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of an allocator as the actual parameter to an access
|
|
parameter.
|
|
|
|
@node No_Access_Subprograms
|
|
@unnumberedsubsec No_Access_Subprograms
|
|
@findex No_Access_Subprograms
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
declarations of access-to-subprogram types.
|
|
|
|
@node No_Allocators
|
|
@unnumberedsubsec No_Allocators
|
|
@findex No_Allocators
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of an allocator.
|
|
|
|
@node No_Anonymous_Allocators
|
|
@unnumberedsubsec No_Anonymous_Allocators
|
|
@findex No_Anonymous_Allocators
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of an allocator of anonymous access type.
|
|
|
|
@node No_Calendar
|
|
@unnumberedsubsec No_Calendar
|
|
@findex No_Calendar
|
|
[GNAT] This restriction ensures at compile time that there is no implicit or
|
|
explicit dependence on the package @code{Ada.Calendar}.
|
|
|
|
@node No_Coextensions
|
|
@unnumberedsubsec No_Coextensions
|
|
@findex No_Coextensions
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
coextensions. See 3.10.2.
|
|
|
|
@node No_Default_Initialization
|
|
@unnumberedsubsec No_Default_Initialization
|
|
@findex No_Default_Initialization
|
|
|
|
[GNAT] 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).
|
|
|
|
@node No_Delay
|
|
@unnumberedsubsec No_Delay
|
|
@findex No_Delay
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
delay statements and no dependences on package Calendar.
|
|
|
|
@node No_Dependence
|
|
@unnumberedsubsec No_Dependence
|
|
@findex No_Dependence
|
|
[RM 13.12.1] This restriction checks at compile time that there are no
|
|
dependence on a library unit.
|
|
|
|
@node No_Direct_Boolean_Operators
|
|
@unnumberedsubsec No_Direct_Boolean_Operators
|
|
@findex No_Direct_Boolean_Operators
|
|
[GNAT] 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.
|
|
|
|
@node No_Dispatch
|
|
@unnumberedsubsec No_Dispatch
|
|
@findex No_Dispatch
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
|
|
|
|
@node No_Dispatching_Calls
|
|
@unnumberedsubsec No_Dispatching_Calls
|
|
@findex No_Dispatching_Calls
|
|
[GNAT] This restriction ensures at compile time that the code generated by the
|
|
compiler involves no dispatching calls. The use of this restriction allows the
|
|
safe use of record extensions, classwide membership tests and other classwide
|
|
features not involving implicit dispatching. This restriction ensures that
|
|
the code contains no indirect calls through a dispatching mechanism. Note that
|
|
this includes internally-generated calls created by the compiler, for example
|
|
in the implementation of class-wide objects assignments. The
|
|
membership test is allowed in the presence of this restriction, because its
|
|
implementation requires no dispatching.
|
|
This restriction is comparable to the official Ada restriction
|
|
@code{No_Dispatch} except that it is a bit less restrictive in that it allows
|
|
all classwide constructs that do not imply dispatching.
|
|
The following example indicates constructs that violate this restriction.
|
|
|
|
@smallexample
|
|
package Pkg is
|
|
type T is tagged record
|
|
Data : Natural;
|
|
end record;
|
|
procedure P (X : T);
|
|
|
|
type DT is new T with record
|
|
More_Data : Natural;
|
|
end record;
|
|
procedure Q (X : DT);
|
|
end Pkg;
|
|
|
|
with Pkg; use Pkg;
|
|
procedure Example is
|
|
procedure Test (O : T'Class) is
|
|
N : Natural := O'Size;-- Error: Dispatching call
|
|
C : T'Class := O; -- Error: implicit Dispatching Call
|
|
begin
|
|
if O in DT'Class then -- OK : Membership test
|
|
Q (DT (O)); -- OK : Type conversion plus direct call
|
|
else
|
|
P (O); -- Error: Dispatching call
|
|
end if;
|
|
end Test;
|
|
|
|
Obj : DT;
|
|
begin
|
|
P (Obj); -- OK : Direct call
|
|
P (T (Obj)); -- OK : Type conversion plus direct call
|
|
P (T'Class (Obj)); -- Error: Dispatching call
|
|
|
|
Test (Obj); -- OK : Type conversion
|
|
|
|
if Obj in T'Class then -- OK : Membership test
|
|
null;
|
|
end if;
|
|
end Example;
|
|
@end smallexample
|
|
|
|
@node No_Dynamic_Attachment
|
|
@unnumberedsubsec No_Dynamic_Attachment
|
|
@findex No_Dynamic_Attachment
|
|
[RM D.7] This restriction ensures that there is no call to any of the
|
|
operations defined in package Ada.Interrupts
|
|
(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
|
|
Detach_Handler, and Reference).
|
|
|
|
@node No_Dynamic_Priorities
|
|
@unnumberedsubsec No_Dynamic_Priorities
|
|
@findex No_Dynamic_Priorities
|
|
[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
|
|
|
|
@node No_Entry_Calls_In_Elaboration_Code
|
|
@unnumberedsubsec No_Entry_Calls_In_Elaboration_Code
|
|
@findex No_Entry_Calls_In_Elaboration_Code
|
|
[GNAT] This restriction ensures at compile time that no task or protected entry
|
|
calls are made during elaboration code. As a result of the use of this
|
|
restriction, the compiler can assume that no code past an accept statement
|
|
in a task can be executed at elaboration time.
|
|
|
|
@node No_Enumeration_Maps
|
|
@unnumberedsubsec No_Enumeration_Maps
|
|
@findex No_Enumeration_Maps
|
|
[GNAT] This restriction ensures at compile time that no operations requiring
|
|
enumeration maps are used (that is Image and Value attributes applied
|
|
to enumeration types).
|
|
|
|
@node No_Exception_Handlers
|
|
@unnumberedsubsec No_Exception_Handlers
|
|
@findex No_Exception_Handlers
|
|
[GNAT] This restriction ensures at compile time that there are no explicit
|
|
exception handlers. It also indicates that no exception propagation will
|
|
be provided. In this mode, exceptions may be raised but will result in
|
|
an immediate call to the last chance handler, a routine that the user
|
|
must define with the following profile:
|
|
|
|
@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.
|
|
|
|
@node No_Exception_Propagation
|
|
@unnumberedsubsec No_Exception_Propagation
|
|
@findex No_Exception_Propagation
|
|
[GNAT] This restriction guarantees that exceptions are never propagated
|
|
to an outer subprogram scope. The only case in which an exception may
|
|
be raised is when the handler is statically in the same subprogram, so
|
|
that the effect of a raise is essentially like a goto statement. Any
|
|
other raise statement (implicit or explicit) will be considered
|
|
unhandled. Exception handlers are allowed, but may not contain an
|
|
exception occurrence identifier (exception choice). In addition, use of
|
|
the package GNAT.Current_Exception is not permitted, and reraise
|
|
statements (raise with no operand) are not permitted.
|
|
|
|
@node No_Exception_Registration
|
|
@unnumberedsubsec No_Exception_Registration
|
|
@findex No_Exception_Registration
|
|
[GNAT] This restriction ensures at compile time that no stream operations for
|
|
types Exception_Id or Exception_Occurrence are used. This also makes it
|
|
impossible to pass exceptions to or from a partition with this restriction
|
|
in a distributed environment. If this exception is active, then the generated
|
|
code is simplified by omitting the otherwise-required global registration
|
|
of exceptions when they are declared.
|
|
|
|
@node No_Exceptions
|
|
@unnumberedsubsec No_Exceptions
|
|
@findex No_Exceptions
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
raise statements and no exception handlers.
|
|
|
|
@node No_Finalization
|
|
@unnumberedsubsec No_Finalization
|
|
@findex No_Finalization
|
|
[GNAT] This restriction disables the language features described in
|
|
chapter 7.6 of the Ada 2005 RM as well as all form of code generation
|
|
performed by the compiler to support these features. The following types
|
|
are no longer considered controlled when this restriction is in effect:
|
|
@itemize @bullet
|
|
@item
|
|
@code{Ada.Finalization.Controlled}
|
|
@item
|
|
@code{Ada.Finalization.Limited_Controlled}
|
|
@item
|
|
Derivations from @code{Controlled} or @code{Limited_Controlled}
|
|
@item
|
|
Class-wide types
|
|
@item
|
|
Protected types
|
|
@item
|
|
Task types
|
|
@item
|
|
Array and record types with controlled components
|
|
@end itemize
|
|
The compiler no longer generates code to initialize, finalize or adjust an
|
|
object or a nested component, either declared on the stack or on the heap. The
|
|
deallocation of a controlled object no longer finalizes its contents.
|
|
|
|
@node No_Fixed_Point
|
|
@unnumberedsubsec No_Fixed_Point
|
|
@findex No_Fixed_Point
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of fixed point types and operations.
|
|
|
|
@node No_Floating_Point
|
|
@unnumberedsubsec No_Floating_Point
|
|
@findex No_Floating_Point
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of floating point types and operations.
|
|
|
|
@node No_Implicit_Conditionals
|
|
@unnumberedsubsec No_Implicit_Conditionals
|
|
@findex No_Implicit_Conditionals
|
|
[GNAT] This restriction ensures that the generated code does not contain any
|
|
implicit conditionals, either by modifying the generated code where possible,
|
|
or by rejecting any construct that would otherwise generate an implicit
|
|
conditional. Note that this check does not include run time constraint
|
|
checks, which on some targets may generate implicit conditionals as
|
|
well. To control the latter, constraint checks can be suppressed in the
|
|
normal manner. Constructs generating implicit conditionals include comparisons
|
|
of composite objects and the Max/Min attributes.
|
|
|
|
@node No_Implicit_Dynamic_Code
|
|
@unnumberedsubsec No_Implicit_Dynamic_Code
|
|
@findex No_Implicit_Dynamic_Code
|
|
@cindex trampoline
|
|
[GNAT] 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
|
|
built for the following features: @code{Access},
|
|
@code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
|
|
nested task bodies; primitive operations of nested tagged types.
|
|
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.
|
|
|
|
@node No_Implicit_Heap_Allocations
|
|
@unnumberedsubsec No_Implicit_Heap_Allocations
|
|
@findex No_Implicit_Heap_Allocations
|
|
[RM D.7] No constructs are allowed to cause implicit heap allocation.
|
|
|
|
@node No_Implicit_Loops
|
|
@unnumberedsubsec No_Implicit_Loops
|
|
@findex No_Implicit_Loops
|
|
[GNAT] This restriction ensures that the generated code does not contain any
|
|
implicit @code{for} loops, either by modifying
|
|
the generated code where possible,
|
|
or by rejecting any construct that would otherwise generate an implicit
|
|
@code{for} loop. If this restriction is active, it is possible to build
|
|
large array aggregates with all static components without generating an
|
|
intermediate temporary, and without generating a loop to initialize individual
|
|
components. Otherwise, a loop is created for arrays larger than about 5000
|
|
scalar components.
|
|
|
|
@node No_Initialize_Scalars
|
|
@unnumberedsubsec No_Initialize_Scalars
|
|
@findex No_Initialize_Scalars
|
|
[GNAT] This restriction ensures that no unit in the partition is compiled with
|
|
pragma Initialize_Scalars. This allows the generation of more efficient
|
|
code, and in particular eliminates dummy null initialization routines that
|
|
are otherwise generated for some record and array types.
|
|
|
|
@node No_IO
|
|
@unnumberedsubsec No_IO
|
|
@findex No_IO
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
dependences on any of the library units Sequential_IO, Direct_IO,
|
|
Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
|
|
|
|
@node No_Local_Allocators
|
|
@unnumberedsubsec No_Local_Allocators
|
|
@findex No_Local_Allocators
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of an allocator in subprograms, generic subprograms, tasks,
|
|
and entry bodies.
|
|
|
|
@node No_Local_Protected_Objects
|
|
@unnumberedsubsec No_Local_Protected_Objects
|
|
@findex No_Local_Protected_Objects
|
|
[RM D.7] This restriction ensures at compile time that protected objects are
|
|
only declared at the library level.
|
|
|
|
@node No_Local_Timing_Events
|
|
@unnumberedsubsec No_Local_Timing_Events
|
|
@findex No_Local_Timing_Events
|
|
[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
|
|
declared at the library level.
|
|
|
|
@node No_Nested_Finalization
|
|
@unnumberedsubsec No_Nested_Finalization
|
|
@findex No_Nested_Finalization
|
|
[RM D.7] All objects requiring finalization are declared at the library level.
|
|
|
|
@node No_Protected_Type_Allocators
|
|
@unnumberedsubsec No_Protected_Type_Allocators
|
|
@findex No_Protected_Type_Allocators
|
|
[RM D.7] This restriction ensures at compile time that there are no allocator
|
|
expressions that attempt to allocate protected objects.
|
|
|
|
@node No_Protected_Types
|
|
@unnumberedsubsec No_Protected_Types
|
|
@findex No_Protected_Types
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
declarations of protected types or protected objects.
|
|
|
|
@node No_Recursion
|
|
@unnumberedsubsec No_Recursion
|
|
@findex No_Recursion
|
|
[RM H.4] A program execution is erroneous if a subprogram is invoked as
|
|
part of its execution.
|
|
|
|
@node No_Reentrancy
|
|
@unnumberedsubsec No_Reentrancy
|
|
@findex No_Reentrancy
|
|
[RM H.4] A program execution is erroneous if a subprogram is executed by
|
|
two tasks at the same time.
|
|
|
|
@node No_Relative_Delay
|
|
@unnumberedsubsec No_Relative_Delay
|
|
@findex No_Relative_Delay
|
|
[RM D.7] This restriction ensures at compile time that there are no delay
|
|
relative statements and prevents expressions such as @code{delay 1.23;} from
|
|
appearing in source code.
|
|
|
|
@node No_Requeue_Statements
|
|
@unnumberedsubsec No_Requeue_Statements
|
|
@findex No_Requeue_Statements
|
|
[RM D.7] This restriction ensures at compile time that no requeue statements
|
|
are permitted and prevents keyword @code{requeue} from being used in source
|
|
code.
|
|
|
|
@node No_Secondary_Stack
|
|
@unnumberedsubsec No_Secondary_Stack
|
|
@findex No_Secondary_Stack
|
|
[GNAT] This restriction ensures at compile time that the generated code
|
|
does not contain any reference to the secondary stack. The secondary
|
|
stack is used to implement functions returning unconstrained objects
|
|
(arrays or records) on some targets.
|
|
|
|
@node No_Select_Statements
|
|
@unnumberedsubsec No_Select_Statements
|
|
@findex No_Select_Statements
|
|
[RM D.7] This restriction ensures at compile time no select statements of any
|
|
kind are permitted, that is the keyword @code{select} may not appear.
|
|
|
|
@node No_Specific_Termination_Handlers
|
|
@unnumberedsubsec No_Specific_Termination_Handlers
|
|
@findex 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.
|
|
|
|
@node No_Specification_of_Aspect
|
|
@unnumberedsubsec No_Specification_of_Aspect
|
|
@findex No_Specification_of_Aspect
|
|
[RM 13.12.1] This restriction checks at compile time that no aspect
|
|
specification, attribute definition clause, or pragma is given for a
|
|
given aspect.
|
|
|
|
@node No_Standard_Allocators_After_Elaboration
|
|
@unnumberedsubsec No_Standard_Allocators_After_Elaboration
|
|
@findex No_Standard_Allocators_After_Elaboration
|
|
[RM D.7] Specifies that an allocator using a standard storage pool
|
|
should never be evaluated at run time after the elaboration of the
|
|
library items of the partition has completed. Otherwise, Storage_Error
|
|
is raised.
|
|
|
|
@node No_Standard_Storage_Pools
|
|
@unnumberedsubsec No_Standard_Storage_Pools
|
|
@findex No_Standard_Storage_Pools
|
|
[GNAT] This restriction ensures at compile time that no access types
|
|
use the standard default storage pool. Any access type declared must
|
|
have an explicit Storage_Pool attribute defined specifying a
|
|
user-defined storage pool.
|
|
|
|
@node No_Stream_Optimizations
|
|
@unnumberedsubsec No_Stream_Optimizations
|
|
@findex No_Stream_Optimizations
|
|
[GNAT] This restriction affects the performance of stream operations on types
|
|
@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
|
|
compiler uses block reads and writes when manipulating @code{String} objects
|
|
due to their supperior performance. When this restriction is in effect, the
|
|
compiler performs all IO operations on a per-character basis.
|
|
|
|
@node No_Streams
|
|
@unnumberedsubsec No_Streams
|
|
@findex No_Streams
|
|
[GNAT] This restriction ensures at compile/bind time that there are no
|
|
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 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.
|
|
|
|
@node No_Task_Allocators
|
|
@unnumberedsubsec No_Task_Allocators
|
|
@findex No_Task_Allocators
|
|
[RM D.7] There are no allocators for task types
|
|
or types containing task subcomponents.
|
|
|
|
@node No_Task_Attributes_Package
|
|
@unnumberedsubsec No_Task_Attributes_Package
|
|
@findex No_Task_Attributes_Package
|
|
[GNAT] This restriction ensures at compile time that there are no implicit or
|
|
explicit dependencies on the package @code{Ada.Task_Attributes}.
|
|
|
|
@node No_Task_Hierarchy
|
|
@unnumberedsubsec No_Task_Hierarchy
|
|
@findex No_Task_Hierarchy
|
|
[RM D.7] All (non-environment) tasks depend
|
|
directly on the environment task of the partition.
|
|
|
|
@node No_Task_Termination
|
|
@unnumberedsubsec No_Task_Termination
|
|
@findex No_Task_Termination
|
|
[RM D.7] Tasks which terminate are erroneous.
|
|
|
|
@node No_Tasking
|
|
@unnumberedsubsec No_Tasking
|
|
@findex No_Tasking
|
|
[GNAT] This restriction prevents the declaration of tasks or task types
|
|
throughout the partition. It is similar in effect to the use of
|
|
@code{Max_Tasks => 0} except that violations are caught at compile time
|
|
and cause an error message to be output either by the compiler or
|
|
binder.
|
|
|
|
@node No_Terminate_Alternatives
|
|
@unnumberedsubsec No_Terminate_Alternatives
|
|
@findex No_Terminate_Alternatives
|
|
[RM D.7] There are no selective accepts with terminate alternatives.
|
|
|
|
@node No_Unchecked_Access
|
|
@unnumberedsubsec No_Unchecked_Access
|
|
@findex No_Unchecked_Access
|
|
[RM H.4] This restriction ensures at compile time that there are no
|
|
occurrences of the Unchecked_Access attribute.
|
|
|
|
@node Simple_Barriers
|
|
@unnumberedsubsec Simple_Barriers
|
|
@findex Simple_Barriers
|
|
[RM D.7] This restriction ensures at compile time that barriers in entry
|
|
declarations for protected types are restricted to either static boolean
|
|
expressions or references to simple boolean variables defined in the private
|
|
part of the protected type. No other form of entry barriers is permitted.
|
|
|
|
@node Static_Priorities
|
|
@unnumberedsubsec Static_Priorities
|
|
@findex Static_Priorities
|
|
[GNAT] This restriction ensures at compile time that all priority expressions
|
|
are static, and that there are no dependences on the package
|
|
@code{Ada.Dynamic_Priorities}.
|
|
|
|
@node Static_Storage_Size
|
|
@unnumberedsubsec Static_Storage_Size
|
|
@findex Static_Storage_Size
|
|
[GNAT] This restriction ensures at compile time that any expression appearing
|
|
in a Storage_Size pragma or attribute definition clause is static.
|
|
|
|
@node Program Unit Level Restrictions
|
|
@section Program Unit Level Restrictions
|
|
|
|
@noindent
|
|
The second set of restriction identifiers
|
|
does not require partition-wide consistency.
|
|
The restriction may be enforced for a single
|
|
compilation unit without any effect on any of the
|
|
other compilation units in the partition.
|
|
|
|
@menu
|
|
* No_Elaboration_Code::
|
|
* No_Entry_Queue::
|
|
* No_Implementation_Aspect_Specifications::
|
|
* No_Implementation_Attributes::
|
|
* No_Implementation_Identifiers::
|
|
* No_Implementation_Pragmas::
|
|
* No_Implementation_Restrictions::
|
|
* No_Implementation_Units::
|
|
* No_Implicit_Aliasing::
|
|
* No_Obsolescent_Features::
|
|
* No_Wide_Characters::
|
|
* SPARK::
|
|
@end menu
|
|
|
|
@node No_Elaboration_Code
|
|
@unnumberedsubsec No_Elaboration_Code
|
|
@findex No_Elaboration_Code
|
|
[GNAT] This restriction ensures at compile time that no elaboration code is
|
|
generated. Note that this is not the same condition as is enforced
|
|
by pragma @code{Preelaborate}. There are cases in which pragma
|
|
@code{Preelaborate} still permits code to be generated (e.g.@: code
|
|
to initialize a large array to all zeroes), and there are cases of units
|
|
which do not meet the requirements for pragma @code{Preelaborate},
|
|
but for which no elaboration code is generated. Generally, it is
|
|
the case that preelaborable units will meet the restrictions, with
|
|
the exception of large aggregates initialized with an others_clause,
|
|
and exception declarations (which generate calls to a run-time
|
|
registry procedure). This restriction is enforced on
|
|
a unit by unit basis, it need not be obeyed consistently
|
|
throughout a partition.
|
|
|
|
In the case of aggregates with others, if the aggregate has a dynamic
|
|
size, there is no way to eliminate the elaboration code (such dynamic
|
|
bounds would be incompatible with @code{Preelaborate} in any case). If
|
|
the bounds are static, then use of this restriction actually modifies
|
|
the code choice of the compiler to avoid generating a loop, and instead
|
|
generate the aggregate statically if possible, no matter how many times
|
|
the data for the others clause must be repeatedly generated.
|
|
|
|
It is not possible to precisely document
|
|
the constructs which are compatible with this restriction, since,
|
|
unlike most other restrictions, this is not a restriction on the
|
|
source code, but a restriction on the generated object code. For
|
|
example, if the source contains a declaration:
|
|
|
|
@smallexample
|
|
Val : constant Integer := X;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where X is not a static constant, it may be possible, depending
|
|
on complex optimization circuitry, for the compiler to figure
|
|
out the value of X at compile time, in which case this initialization
|
|
can be done by the loader, and requires no initialization code. It
|
|
is not possible to document the precise conditions under which the
|
|
optimizer can figure this out.
|
|
|
|
Note that this the implementation of this restriction requires full
|
|
code generation. If it is used in conjunction with "semantics only"
|
|
checking, then some cases of violations may be missed.
|
|
|
|
@node No_Entry_Queue
|
|
@unnumberedsubsec No_Entry_Queue
|
|
@findex No_Entry_Queue
|
|
[GNAT] This restriction is a declaration that any protected entry compiled in
|
|
the scope of the restriction has at most one task waiting on the entry
|
|
at any one time, and so no queue is required. This restriction is not
|
|
checked at compile time. A program execution is erroneous if an attempt
|
|
is made to queue a second task on such an entry.
|
|
|
|
@node No_Implementation_Aspect_Specifications
|
|
@unnumberedsubsec No_Implementation_Aspect_Specifications
|
|
@findex No_Implementation_Aspect_Specifications
|
|
[RM 13.12.1] This restriction checks at compile time that no
|
|
GNAT-defined aspects are present. With this restriction, the only
|
|
aspects that can be used are those defined in the Ada Reference Manual.
|
|
|
|
@node No_Implementation_Attributes
|
|
@unnumberedsubsec No_Implementation_Attributes
|
|
@findex No_Implementation_Attributes
|
|
[RM 13.12.1] This restriction checks at compile time that no
|
|
GNAT-defined attributes are present. With this restriction, the only
|
|
attributes that can be used are those defined in the Ada Reference
|
|
Manual.
|
|
|
|
@node No_Implementation_Identifiers
|
|
@unnumberedsubsec No_Implementation_Identifiers
|
|
@findex No_Implementation_Identifiers
|
|
[RM 13.12.1] This restriction checks at compile time that no
|
|
implementation-defined identifiers occur within language-defined
|
|
packages.
|
|
|
|
@node No_Implementation_Pragmas
|
|
@unnumberedsubsec No_Implementation_Pragmas
|
|
@findex No_Implementation_Pragmas
|
|
[RM 13.12.1] This restriction checks at compile time that no
|
|
GNAT-defined pragmas are present. With this restriction, the only
|
|
pragmas that can be used are those defined in the Ada Reference Manual.
|
|
|
|
@node No_Implementation_Restrictions
|
|
@unnumberedsubsec No_Implementation_Restrictions
|
|
@findex No_Implementation_Restrictions
|
|
[GNAT] This restriction checks at compile time that no GNAT-defined restriction
|
|
identifiers (other than @code{No_Implementation_Restrictions} itself)
|
|
are present. With this restriction, the only other restriction identifiers
|
|
that can be used are those defined in the Ada Reference Manual.
|
|
|
|
@node No_Implementation_Units
|
|
@unnumberedsubsec No_Implementation_Units
|
|
@findex No_Implementation_Units
|
|
[RM 13.12.1] This restriction checks at compile time that there is no
|
|
mention in the context clause of any implementation-defined descendants
|
|
of packages Ada, Interfaces, or System.
|
|
|
|
@node No_Implicit_Aliasing
|
|
@unnumberedsubsec No_Implicit_Aliasing
|
|
@findex No_Implicit_Aliasing
|
|
[GNAT] This restriction, which is not required to be partition-wide consistent,
|
|
requires an explicit aliased keyword for an object to which 'Access,
|
|
'Unchecked_Access, or 'Address is applied, and forbids entirely the use of
|
|
the 'Unrestricted_Access attribute for objects. Note: the reason that
|
|
Unrestricted_Access is forbidden is that it would require the prefix
|
|
to be aliased, and in such cases, it can always be replaced by
|
|
the standard attribute Unchecked_Access which is preferable.
|
|
|
|
@node No_Obsolescent_Features
|
|
@unnumberedsubsec No_Obsolescent_Features
|
|
@findex No_Obsolescent_Features
|
|
[RM 13.12.1] This restriction checks at compile time that no obsolescent
|
|
features are used, as defined in Annex J of the Ada Reference Manual.
|
|
|
|
@node No_Wide_Characters
|
|
@unnumberedsubsec No_Wide_Characters
|
|
@findex No_Wide_Characters
|
|
[GNAT] This restriction ensures at compile time that no uses of the types
|
|
@code{Wide_Character} or @code{Wide_String} or corresponding wide
|
|
wide types
|
|
appear, and that no wide or wide wide string or character literals
|
|
appear in the program (that is literals representing characters not in
|
|
type @code{Character}.
|
|
|
|
@node SPARK
|
|
@unnumberedsubsec SPARK
|
|
@findex SPARK
|
|
[GNAT] This restriction checks at compile time that some constructs
|
|
forbidden in SPARK are not present. The SPARK version used as a
|
|
reference is the same as the Ada mode for the unit, so a unit compiled
|
|
in Ada 95 mode with SPARK restrictions will be checked for constructs
|
|
forbidden in SPARK 95. Error messages related to SPARK restriction have
|
|
the form:
|
|
|
|
@smallexample
|
|
violation of restriction "SPARK" at <file>
|
|
<error message>
|
|
@end smallexample
|
|
|
|
This is not a replacement for the semantic checks performed by the
|
|
SPARK Examiner tool, as the compiler only deals currently with code,
|
|
not at all with SPARK annotations and does not guarantee catching all
|
|
cases of constructs forbidden by SPARK.
|
|
|
|
Thus it may well be the case that code which
|
|
passes the compiler in SPARK mode is rejected by the SPARK Examiner,
|
|
e.g. due to the different visibility rules of the Examiner based on
|
|
SPARK @code{inherit} annotations.
|
|
|
|
This restriction can be useful in providing an initial filter for
|
|
code developed using SPARK, or in examining legacy code to see how far
|
|
it is from meeting SPARK restrictions.
|
|
|
|
@c ------------------------
|
|
@node Implementation Advice
|
|
@chapter Implementation Advice
|
|
@noindent
|
|
The main text of the Ada Reference Manual describes the required
|
|
behavior of all Ada compilers, and the GNAT compiler conforms to
|
|
these requirements.
|
|
|
|
In addition, there are sections throughout the Ada Reference Manual headed
|
|
by the phrase ``Implementation advice''. These sections are not normative,
|
|
i.e., they do not specify requirements that all compilers must
|
|
follow. Rather they provide advice on generally desirable behavior. You
|
|
may wonder why they are not requirements. The most typical answer is
|
|
that they describe behavior that seems generally desirable, but cannot
|
|
be provided on all systems, or which may be undesirable on some systems.
|
|
|
|
As far as practical, GNAT follows the implementation advice sections in
|
|
the Ada Reference Manual. This chapter contains a table giving the
|
|
reference manual section number, paragraph number and several keywords
|
|
for each advice. Each entry consists of the text of the advice followed
|
|
by the GNAT interpretation of this advice. Most often, this simply says
|
|
``followed'', which means that GNAT follows the advice. However, in a
|
|
number of cases, GNAT deliberately deviates from this advice, in which
|
|
case the text describes what GNAT does and why.
|
|
|
|
@cindex Error detection
|
|
@unnumberedsec 1.1.3(20): Error Detection
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation detects the use of an unsupported Specialized Needs
|
|
Annex feature at run time, it should raise @code{Program_Error} if
|
|
feasible.
|
|
@end cartouche
|
|
Not relevant. All specialized needs annex features are either supported,
|
|
or diagnosed at compile time.
|
|
|
|
@cindex Child Units
|
|
@unnumberedsec 1.1.3(31): Child Units
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation wishes to provide implementation-defined
|
|
extensions to the functionality of a language-defined library unit, it
|
|
should normally do so by adding children to the library unit.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Bounded errors
|
|
@unnumberedsec 1.1.5(12): Bounded Errors
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation detects a bounded error or erroneous
|
|
execution, it should raise @code{Program_Error}.
|
|
@end cartouche
|
|
Followed in all cases in which the implementation detects a bounded
|
|
error or erroneous execution. Not all such situations are detected at
|
|
runtime.
|
|
|
|
@cindex Pragmas
|
|
@unnumberedsec 2.8(16): Pragmas
|
|
@sp 1
|
|
@cartouche
|
|
Normally, implementation-defined pragmas should have no semantic effect
|
|
for error-free programs; that is, if the implementation-defined pragmas
|
|
are removed from a working program, the program should still be legal,
|
|
and should still have the same semantics.
|
|
@end cartouche
|
|
The following implementation defined pragmas are exceptions to this
|
|
rule:
|
|
|
|
@table @code
|
|
@item Abort_Defer
|
|
Affects semantics
|
|
@item Ada_83
|
|
Affects legality
|
|
@item Assert
|
|
Affects semantics
|
|
@item CPP_Class
|
|
Affects semantics
|
|
@item CPP_Constructor
|
|
Affects semantics
|
|
@item Debug
|
|
Affects semantics
|
|
@item Interface_Name
|
|
Affects semantics
|
|
@item Machine_Attribute
|
|
Affects semantics
|
|
@item Unimplemented_Unit
|
|
Affects legality
|
|
@item Unchecked_Union
|
|
Affects semantics
|
|
@end table
|
|
|
|
@noindent
|
|
In each of the above cases, it is essential to the purpose of the pragma
|
|
that this advice not be followed. For details see the separate section
|
|
on implementation defined pragmas.
|
|
|
|
@unnumberedsec 2.8(17-19): Pragmas
|
|
@sp 1
|
|
@cartouche
|
|
Normally, an implementation should not define pragmas that can
|
|
make an illegal program legal, except as follows:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
A pragma used to complete a declaration, such as a pragma @code{Import};
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
A pragma used to configure the environment by adding, removing, or
|
|
replacing @code{library_items}.
|
|
@end cartouche
|
|
See response to paragraph 16 of this same section.
|
|
|
|
@cindex Character Sets
|
|
@cindex Alternative Character Sets
|
|
@unnumberedsec 3.5.2(5): Alternative Character Sets
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation supports a mode with alternative interpretations
|
|
for @code{Character} and @code{Wide_Character}, the set of graphic
|
|
characters of @code{Character} should nevertheless remain a proper
|
|
subset of the set of graphic characters of @code{Wide_Character}. Any
|
|
character set ``localizations'' should be reflected in the results of
|
|
the subprograms defined in the language-defined package
|
|
@code{Characters.Handling} (see A.3) available in such a mode. In a mode with
|
|
an alternative interpretation of @code{Character}, the implementation should
|
|
also support a corresponding change in what is a legal
|
|
@code{identifier_letter}.
|
|
@end cartouche
|
|
Not all wide character modes follow this advice, in particular the JIS
|
|
and IEC modes reflect standard usage in Japan, and in these encoding,
|
|
the upper half of the Latin-1 set is not part of the wide-character
|
|
subset, since the most significant bit is used for wide character
|
|
encoding. However, this only applies to the external forms. Internally
|
|
there is no such restriction.
|
|
|
|
@cindex Integer types
|
|
@unnumberedsec 3.5.4(28): Integer Types
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support @code{Long_Integer} in addition to
|
|
@code{Integer} if the target machine supports 32-bit (or longer)
|
|
arithmetic. No other named integer subtypes are recommended for package
|
|
@code{Standard}. Instead, appropriate named integer subtypes should be
|
|
provided in the library package @code{Interfaces} (see B.2).
|
|
@end cartouche
|
|
@code{Long_Integer} is supported. Other standard integer types are supported
|
|
so this advice is not fully followed. These types
|
|
are supported for convenient interface to C, and so that all hardware
|
|
types of the machine are easily available.
|
|
@unnumberedsec 3.5.4(29): Integer Types
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation for a two's complement machine should support
|
|
modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
|
|
implementation should support a non-binary modules up to @code{Integer'Last}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Enumeration values
|
|
@unnumberedsec 3.5.5(8): Enumeration Values
|
|
@sp 1
|
|
@cartouche
|
|
For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
|
|
subtype, if the value of the operand does not correspond to the internal
|
|
code for any enumeration literal of its type (perhaps due to an
|
|
un-initialized variable), then the implementation should raise
|
|
@code{Program_Error}. This is particularly important for enumeration
|
|
types with noncontiguous internal codes specified by an
|
|
enumeration_representation_clause.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Float types
|
|
@unnumberedsec 3.5.7(17): Float Types
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support @code{Long_Float} in addition to
|
|
@code{Float} if the target machine supports 11 or more digits of
|
|
precision. No other named floating point subtypes are recommended for
|
|
package @code{Standard}. Instead, appropriate named floating point subtypes
|
|
should be provided in the library package @code{Interfaces} (see B.2).
|
|
@end cartouche
|
|
@code{Short_Float} and @code{Long_Long_Float} are also provided. The
|
|
former provides improved compatibility with other implementations
|
|
supporting this type. The latter corresponds to the highest precision
|
|
floating-point type supported by the hardware. On most machines, this
|
|
will be the same as @code{Long_Float}, but on some machines, it will
|
|
correspond to the IEEE extended form. The notable case is all ia32
|
|
(x86) implementations, where @code{Long_Long_Float} corresponds to
|
|
the 80-bit extended precision format supported in hardware on this
|
|
processor. Note that the 128-bit format on SPARC is not supported,
|
|
since this is a software rather than a hardware format.
|
|
|
|
@cindex Multidimensional arrays
|
|
@cindex Arrays, multidimensional
|
|
@unnumberedsec 3.6.2(11): Multidimensional Arrays
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should normally represent multidimensional arrays in
|
|
row-major order, consistent with the notation used for multidimensional
|
|
array aggregates (see 4.3.3). However, if a pragma @code{Convention}
|
|
(@code{Fortran}, @dots{}) applies to a multidimensional array type, then
|
|
column-major order should be used instead (see B.5, ``Interfacing with
|
|
Fortran'').
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@findex Duration'Small
|
|
@unnumberedsec 9.6(30-31): Duration'Small
|
|
@sp 1
|
|
@cartouche
|
|
Whenever possible in an implementation, the value of @code{Duration'Small}
|
|
should be no greater than 100 microseconds.
|
|
@end cartouche
|
|
Followed. (@code{Duration'Small} = 10**(@minus{}9)).
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The time base for @code{delay_relative_statements} should be monotonic;
|
|
it need not be the same time base as used for @code{Calendar.Clock}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@unnumberedsec 10.2.1(12): Consistent Representation
|
|
@sp 1
|
|
@cartouche
|
|
In an implementation, a type declared in a pre-elaborated package should
|
|
have the same representation in every elaboration of a given version of
|
|
the package, whether the elaborations occur in distinct executions of
|
|
the same program, or in executions of distinct programs or partitions
|
|
that include the given version.
|
|
@end cartouche
|
|
Followed, except in the case of tagged types. Tagged types involve
|
|
implicit pointers to a local copy of a dispatch table, and these pointers
|
|
have representations which thus depend on a particular elaboration of the
|
|
package. It is not easy to see how it would be possible to follow this
|
|
advice without severely impacting efficiency of execution.
|
|
|
|
@cindex Exception information
|
|
@unnumberedsec 11.4.1(19): Exception Information
|
|
@sp 1
|
|
@cartouche
|
|
@code{Exception_Message} by default and @code{Exception_Information}
|
|
should produce information useful for
|
|
debugging. @code{Exception_Message} should be short, about one
|
|
line. @code{Exception_Information} can be long. @code{Exception_Message}
|
|
should not include the
|
|
@code{Exception_Name}. @code{Exception_Information} should include both
|
|
the @code{Exception_Name} and the @code{Exception_Message}.
|
|
@end cartouche
|
|
Followed. For each exception that doesn't have a specified
|
|
@code{Exception_Message}, the compiler generates one containing the location
|
|
of the raise statement. This location has the form ``file:line'', where
|
|
file is the short file name (without path information) and line is the line
|
|
number in the file. Note that in the case of the Zero Cost Exception
|
|
mechanism, these messages become redundant with the Exception_Information that
|
|
contains a full backtrace of the calling sequence, so they are disabled.
|
|
To disable explicitly the generation of the source location message, use the
|
|
Pragma @code{Discard_Names}.
|
|
|
|
@cindex Suppression of checks
|
|
@cindex Checks, suppression of
|
|
@unnumberedsec 11.5(28): Suppression of Checks
|
|
@sp 1
|
|
@cartouche
|
|
The implementation should minimize the code executed for checks that
|
|
have been suppressed.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Representation clauses
|
|
@unnumberedsec 13.1 (21-24): Representation Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for all representation items is
|
|
qualified as follows:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support representation items containing
|
|
non-static expressions, except that an implementation should support a
|
|
representation item for a given entity if each non-static expression in
|
|
the representation item is a name that statically denotes a constant
|
|
declared before the entity.
|
|
@end cartouche
|
|
Followed. In fact, GNAT goes beyond the recommended level of support
|
|
by allowing nonstatic expressions in some representation clauses even
|
|
without the need to declare constants initialized with the values of
|
|
such expressions.
|
|
For example:
|
|
|
|
@smallexample @c ada
|
|
X : Integer;
|
|
Y : Float;
|
|
for Y'Address use X'Address;>>
|
|
@end smallexample
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support a specification for the @code{Size}
|
|
for a given composite subtype, nor the size or storage place for an
|
|
object (including a component) of a given composite subtype, unless the
|
|
constraints on the subtype and its composite subcomponents (if any) are
|
|
all static constraints.
|
|
@end cartouche
|
|
Followed. Size Clauses are not permitted on non-static components, as
|
|
described above.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An aliased component, or a component whose type is by-reference, should
|
|
always be allocated at an addressable location.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Packed types
|
|
@unnumberedsec 13.2(6-8): Packed Types
|
|
@sp 1
|
|
@cartouche
|
|
If a type is packed, then the implementation should try to minimize
|
|
storage allocated to objects of the type, possibly at the expense of
|
|
speed of accessing components, subject to reasonable complexity in
|
|
addressing calculations.
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support pragma @code{Pack} is:
|
|
|
|
For a packed record type, the components should be packed as tightly as
|
|
possible subject to the Sizes of the component subtypes, and subject to
|
|
any @code{record_representation_clause} that applies to the type; the
|
|
implementation may, but need not, reorder components or cross aligned
|
|
word boundaries to improve the packing. A component whose @code{Size} is
|
|
greater than the word size may be allocated an integral number of words.
|
|
@end cartouche
|
|
Followed. Tight packing of arrays is supported for all component sizes
|
|
up to 64-bits. If the array component size is 1 (that is to say, if
|
|
the component is a boolean type or an enumeration type with two values)
|
|
then values of the type are implicitly initialized to zero. This
|
|
happens both for objects of the packed type, and for objects that have a
|
|
subcomponent of the packed type.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support Address clauses for imported
|
|
subprograms.
|
|
@end cartouche
|
|
Followed.
|
|
@cindex @code{Address} clauses
|
|
@unnumberedsec 13.3(14-19): Address Clauses
|
|
|
|
@sp 1
|
|
@cartouche
|
|
For an array @var{X}, @code{@var{X}'Address} should point at the first
|
|
component of the array, and not at the array bounds.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Address} attribute is:
|
|
|
|
@code{@var{X}'Address} should produce a useful result if @var{X} is an
|
|
object that is aliased or of a by-reference type, or is an entity whose
|
|
@code{Address} has been specified.
|
|
@end cartouche
|
|
Followed. A valid address will be produced even if none of those
|
|
conditions have been met. If necessary, the object is forced into
|
|
memory to ensure the address is valid.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support @code{Address} clauses for imported
|
|
subprograms.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Objects (including subcomponents) that are aliased or of a by-reference
|
|
type should be allocated on storage element boundaries.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
If the @code{Address} of an object is specified, or it is imported or exported,
|
|
then the implementation should not perform optimizations based on
|
|
assumptions of no aliases.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex @code{Alignment} clauses
|
|
@unnumberedsec 13.3(29-35): Alignment Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Alignment} attribute for
|
|
subtypes is:
|
|
|
|
An implementation should support specified Alignments that are factors
|
|
and multiples of the number of storage elements per word, subject to the
|
|
following:
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support specified @code{Alignment}s for
|
|
combinations of @code{Size}s and @code{Alignment}s that cannot be easily
|
|
loaded and stored by available machine instructions.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support specified @code{Alignment}s that are
|
|
greater than the maximum @code{Alignment} the implementation ever returns by
|
|
default.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Alignment} attribute for
|
|
objects is:
|
|
|
|
Same as above, for subtypes, but in addition:
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
For stand-alone library-level objects of statically constrained
|
|
subtypes, the implementation should support all @code{Alignment}s
|
|
supported by the target linker. For example, page alignment is likely to
|
|
be supported for such objects, but not for subtypes.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex @code{Size} clauses
|
|
@unnumberedsec 13.3(42-43): Size Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Size} attribute of
|
|
objects is:
|
|
|
|
A @code{Size} clause should be supported for an object if the specified
|
|
@code{Size} is at least as large as its subtype's @code{Size}, and
|
|
corresponds to a size in storage elements that is a multiple of the
|
|
object's @code{Alignment} (if the @code{Alignment} is nonzero).
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@unnumberedsec 13.3(50-56): Size Clauses
|
|
@sp 1
|
|
@cartouche
|
|
If the @code{Size} of a subtype is specified, and allows for efficient
|
|
independent addressability (see 9.10) on the target architecture, then
|
|
the @code{Size} of the following objects of the subtype should equal the
|
|
@code{Size} of the subtype:
|
|
|
|
Aliased objects (including components).
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@code{Size} clause on a composite subtype should not affect the
|
|
internal layout of components.
|
|
@end cartouche
|
|
Followed. But note that this can be overridden by use of the implementation
|
|
pragma Implicit_Packing in the case of packed arrays.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Size} attribute of subtypes is:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
The @code{Size} (if not specified) of a static discrete or fixed point
|
|
subtype should be the number of bits needed to represent each value
|
|
belonging to the subtype using an unbiased representation, leaving space
|
|
for a sign bit only if the subtype contains negative values. If such a
|
|
subtype is a first subtype, then an implementation should support a
|
|
specified @code{Size} for it that reflects this representation.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
For a subtype implemented with levels of indirection, the @code{Size}
|
|
should include the size of the pointers, but not the size of what they
|
|
point at.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex @code{Component_Size} clauses
|
|
@unnumberedsec 13.3(71-73): Component Size Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the @code{Component_Size}
|
|
attribute is:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support specified @code{Component_Sizes} that are
|
|
less than the @code{Size} of the component subtype.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support specified @code{Component_Size}s that
|
|
are factors and multiples of the word size. For such
|
|
@code{Component_Size}s, the array should contain no gaps between
|
|
components. For other @code{Component_Size}s (if supported), the array
|
|
should contain no gaps between components when packing is also
|
|
specified; the implementation should forbid this combination in cases
|
|
where it cannot support a no-gaps representation.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Enumeration representation clauses
|
|
@cindex Representation clauses, enumeration
|
|
@unnumberedsec 13.4(9-10): Enumeration Representation Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for enumeration representation clauses
|
|
is:
|
|
|
|
An implementation need not support enumeration representation clauses
|
|
for boolean types, but should at minimum support the internal codes in
|
|
the range @code{System.Min_Int.System.Max_Int}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Record representation clauses
|
|
@cindex Representation clauses, records
|
|
@unnumberedsec 13.5.1(17-22): Record Representation Clauses
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for
|
|
@*@code{record_representation_clauses} is:
|
|
|
|
An implementation should support storage places that can be extracted
|
|
with a load, mask, shift sequence of machine code, and set with a load,
|
|
shift, mask, store sequence, given the available machine instructions
|
|
and run-time model.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
A storage place should be supported if its size is equal to the
|
|
@code{Size} of the component subtype, and it starts and ends on a
|
|
boundary that obeys the @code{Alignment} of the component subtype.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
If the default bit ordering applies to the declaration of a given type,
|
|
then for a component whose subtype's @code{Size} is less than the word
|
|
size, any storage place that does not cross an aligned word boundary
|
|
should be supported.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation may reserve a storage place for the tag field of a
|
|
tagged type, and disallow other components from overlapping that place.
|
|
@end cartouche
|
|
Followed. The storage place for the tag field is the beginning of the tagged
|
|
record, and its size is Address'Size. GNAT will reject an explicit component
|
|
clause for the tag field.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation need not support a @code{component_clause} for a
|
|
component of an extension part if the storage place is not after the
|
|
storage places of all components of the parent type, whether or not
|
|
those storage places had been specified.
|
|
@end cartouche
|
|
Followed. The above advice on record representation clauses is followed,
|
|
and all mentioned features are implemented.
|
|
|
|
@cindex Storage place attributes
|
|
@unnumberedsec 13.5.2(5): Storage Place Attributes
|
|
@sp 1
|
|
@cartouche
|
|
If a component is represented using some form of pointer (such as an
|
|
offset) to the actual data of the component, and this data is contiguous
|
|
with the rest of the object, then the storage place attributes should
|
|
reflect the place of the actual data, not the pointer. If a component is
|
|
allocated discontinuously from the rest of the object, then a warning
|
|
should be generated upon reference to one of its storage place
|
|
attributes.
|
|
@end cartouche
|
|
Followed. There are no such components in GNAT@.
|
|
|
|
@cindex Bit ordering
|
|
@unnumberedsec 13.5.3(7-8): Bit Ordering
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for the non-default bit ordering is:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
If @code{Word_Size} = @code{Storage_Unit}, then the implementation
|
|
should support the non-default bit ordering in addition to the default
|
|
bit ordering.
|
|
@end cartouche
|
|
Followed. Word size does not equal storage size in this implementation.
|
|
Thus non-default bit ordering is not supported.
|
|
|
|
@cindex @code{Address}, as private type
|
|
@unnumberedsec 13.7(37): Address as Private
|
|
@sp 1
|
|
@cartouche
|
|
@code{Address} should be of a private type.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Operations, on @code{Address}
|
|
@cindex @code{Address}, operations of
|
|
@unnumberedsec 13.7.1(16): Address Operations
|
|
@sp 1
|
|
@cartouche
|
|
Operations in @code{System} and its children should reflect the target
|
|
environment semantics as closely as is reasonable. For example, on most
|
|
machines, it makes sense for address arithmetic to ``wrap around''.
|
|
Operations that do not make sense should raise @code{Program_Error}.
|
|
@end cartouche
|
|
Followed. Address arithmetic is modular arithmetic that wraps around. No
|
|
operation raises @code{Program_Error}, since all operations make sense.
|
|
|
|
@cindex Unchecked conversion
|
|
@unnumberedsec 13.9(14-17): Unchecked Conversion
|
|
@sp 1
|
|
@cartouche
|
|
The @code{Size} of an array object should not include its bounds; hence,
|
|
the bounds should not be part of the converted data.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The implementation should not generate unnecessary run-time checks to
|
|
ensure that the representation of @var{S} is a representation of the
|
|
target type. It should take advantage of the permission to return by
|
|
reference when possible. Restrictions on unchecked conversions should be
|
|
avoided unless required by the target environment.
|
|
@end cartouche
|
|
Followed. There are no restrictions on unchecked conversion. A warning is
|
|
generated if the source and target types do not have the same size since
|
|
the semantics in this case may be target dependent.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The recommended level of support for unchecked conversions is:
|
|
@end cartouche
|
|
@sp 1
|
|
@cartouche
|
|
Unchecked conversions should be supported and should be reversible in
|
|
the cases where this clause defines the result. To enable meaningful use
|
|
of unchecked conversion, a contiguous representation should be used for
|
|
elementary subtypes, for statically constrained array subtypes whose
|
|
component subtype is one of the subtypes described in this paragraph,
|
|
and for record subtypes without discriminants whose component subtypes
|
|
are described in this paragraph.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Heap usage, implicit
|
|
@unnumberedsec 13.11(23-25): Implicit Heap Usage
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should document any cases in which it dynamically
|
|
allocates heap storage for a purpose other than the evaluation of an
|
|
allocator.
|
|
@end cartouche
|
|
Followed, the only other points at which heap storage is dynamically
|
|
allocated are as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
At initial elaboration time, to allocate dynamically sized global
|
|
objects.
|
|
|
|
@item
|
|
To allocate space for a task when a task is created.
|
|
|
|
@item
|
|
To extend the secondary stack dynamically when needed. The secondary
|
|
stack is used for returning variable length results.
|
|
@end itemize
|
|
|
|
@sp 1
|
|
@cartouche
|
|
A default (implementation-provided) storage pool for an
|
|
access-to-constant type should not have overhead to support deallocation of
|
|
individual objects.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
A storage pool for an anonymous access type should be created at the
|
|
point of an allocator for the type, and be reclaimed when the designated
|
|
object becomes inaccessible.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Unchecked deallocation
|
|
@unnumberedsec 13.11.2(17): Unchecked De-allocation
|
|
@sp 1
|
|
@cartouche
|
|
For a standard storage pool, @code{Free} should actually reclaim the
|
|
storage.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Stream oriented attributes
|
|
@unnumberedsec 13.13.2(17): Stream Oriented Attributes
|
|
@sp 1
|
|
@cartouche
|
|
If a stream element is the same size as a storage element, then the
|
|
normal in-memory representation should be used by @code{Read} and
|
|
@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
|
|
should use the smallest number of stream elements needed to represent
|
|
all values in the base range of the scalar type.
|
|
@end cartouche
|
|
|
|
Followed. By default, GNAT uses the interpretation suggested by AI-195,
|
|
which specifies using the size of the first subtype.
|
|
However, such an implementation is based on direct binary
|
|
representations and is therefore target- and endianness-dependent.
|
|
To address this issue, GNAT also supplies an alternate implementation
|
|
of the stream attributes @code{Read} and @code{Write},
|
|
which uses the target-independent XDR standard representation
|
|
for scalar types.
|
|
@cindex XDR representation
|
|
@cindex @code{Read} attribute
|
|
@cindex @code{Write} attribute
|
|
@cindex Stream oriented attributes
|
|
The XDR implementation is provided as an alternative body of the
|
|
@code{System.Stream_Attributes} package, in the file
|
|
@file{s-stratt-xdr.adb} in the GNAT library.
|
|
There is no @file{s-stratt-xdr.ads} file.
|
|
In order to install the XDR implementation, do the following:
|
|
@enumerate
|
|
@item Replace the default implementation of the
|
|
@code{System.Stream_Attributes} package with the XDR implementation.
|
|
For example on a Unix platform issue the commands:
|
|
@smallexample
|
|
$ mv s-stratt.adb s-stratt-default.adb
|
|
$ mv s-stratt-xdr.adb s-stratt.adb
|
|
@end smallexample
|
|
|
|
@item
|
|
Rebuild the GNAT run-time library as documented in
|
|
@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
|
|
@end enumerate
|
|
|
|
@unnumberedsec A.1(52): Names of Predefined Numeric Types
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation provides additional named predefined integer types,
|
|
then the names should end with @samp{Integer} as in
|
|
@samp{Long_Integer}. If an implementation provides additional named
|
|
predefined floating point types, then the names should end with
|
|
@samp{Float} as in @samp{Long_Float}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@findex Ada.Characters.Handling
|
|
@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation provides a localized definition of @code{Character}
|
|
or @code{Wide_Character}, then the effects of the subprograms in
|
|
@code{Characters.Handling} should reflect the localizations. See also
|
|
3.5.2.
|
|
@end cartouche
|
|
Followed. GNAT provides no such localized definitions.
|
|
|
|
@cindex Bounded-length strings
|
|
@unnumberedsec A.4.4(106): Bounded-Length String Handling
|
|
@sp 1
|
|
@cartouche
|
|
Bounded string objects should not be implemented by implicit pointers
|
|
and dynamic allocation.
|
|
@end cartouche
|
|
Followed. No implicit pointers or dynamic allocation are used.
|
|
|
|
@cindex Random number generation
|
|
@unnumberedsec A.5.2(46-47): Random Number Generation
|
|
@sp 1
|
|
@cartouche
|
|
Any storage associated with an object of type @code{Generator} should be
|
|
reclaimed on exit from the scope of the object.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
If the generator period is sufficiently long in relation to the number
|
|
of distinct initiator values, then each possible value of
|
|
@code{Initiator} passed to @code{Reset} should initiate a sequence of
|
|
random numbers that does not, in a practical sense, overlap the sequence
|
|
initiated by any other value. If this is not possible, then the mapping
|
|
between initiator values and generator states should be a rapidly
|
|
varying function of the initiator value.
|
|
@end cartouche
|
|
Followed. The generator period is sufficiently long for the first
|
|
condition here to hold true.
|
|
|
|
@findex Get_Immediate
|
|
@unnumberedsec A.10.7(23): @code{Get_Immediate}
|
|
@sp 1
|
|
@cartouche
|
|
The @code{Get_Immediate} procedures should be implemented with
|
|
unbuffered input. For a device such as a keyboard, input should be
|
|
@dfn{available} if a key has already been typed, whereas for a disk
|
|
file, input should always be available except at end of file. For a file
|
|
associated with a keyboard-like device, any line-editing features of the
|
|
underlying operating system should be disabled during the execution of
|
|
@code{Get_Immediate}.
|
|
@end cartouche
|
|
Followed on all targets except VxWorks. For VxWorks, there is no way to
|
|
provide this functionality that does not result in the input buffer being
|
|
flushed before the @code{Get_Immediate} call. A special unit
|
|
@code{Interfaces.Vxworks.IO} is provided that contains routines to enable
|
|
this functionality.
|
|
|
|
@findex Export
|
|
@unnumberedsec B.1(39-41): Pragma @code{Export}
|
|
@sp 1
|
|
@cartouche
|
|
If an implementation supports pragma @code{Export} to a given language,
|
|
then it should also allow the main subprogram to be written in that
|
|
language. It should support some mechanism for invoking the elaboration
|
|
of the Ada library units included in the system, and for invoking the
|
|
finalization of the environment task. On typical systems, the
|
|
recommended mechanism is to provide two subprograms whose link names are
|
|
@code{adainit} and @code{adafinal}. @code{adainit} should contain the
|
|
elaboration code for library units. @code{adafinal} should contain the
|
|
finalization code. These subprograms should have no effect the second
|
|
and subsequent time they are called.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Automatic elaboration of pre-elaborated packages should be
|
|
provided when pragma @code{Export} is supported.
|
|
@end cartouche
|
|
Followed when the main program is in Ada. If the main program is in a
|
|
foreign language, then
|
|
@code{adainit} must be called to elaborate pre-elaborated
|
|
packages.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
For each supported convention @var{L} other than @code{Intrinsic}, an
|
|
implementation should support @code{Import} and @code{Export} pragmas
|
|
for objects of @var{L}-compatible types and for subprograms, and pragma
|
|
@code{Convention} for @var{L}-eligible types and for subprograms,
|
|
presuming the other language has corresponding features. Pragma
|
|
@code{Convention} need not be supported for scalar types.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Package @code{Interfaces}
|
|
@findex Interfaces
|
|
@unnumberedsec B.2(12-13): Package @code{Interfaces}
|
|
@sp 1
|
|
@cartouche
|
|
For each implementation-defined convention identifier, there should be a
|
|
child package of package Interfaces with the corresponding name. This
|
|
package should contain any declarations that would be useful for
|
|
interfacing to the language (implementation) represented by the
|
|
convention. Any declarations useful for interfacing to any language on
|
|
the given hardware architecture should be provided directly in
|
|
@code{Interfaces}.
|
|
@end cartouche
|
|
Followed. An additional package not defined
|
|
in the Ada Reference Manual is @code{Interfaces.CPP}, used
|
|
for interfacing to C++.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An implementation supporting an interface to C, COBOL, or Fortran should
|
|
provide the corresponding package or packages described in the following
|
|
clauses.
|
|
@end cartouche
|
|
Followed. GNAT provides all the packages described in this section.
|
|
|
|
@cindex C, interfacing with
|
|
@unnumberedsec B.3(63-71): Interfacing with C
|
|
@sp 1
|
|
@cartouche
|
|
An implementation should support the following interface correspondences
|
|
between Ada and C@.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada procedure corresponds to a void-returning C function.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada function corresponds to a non-void C function.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada @code{in} scalar parameter is passed as a scalar argument to a C
|
|
function.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada @code{in} parameter of an access-to-object type with designated
|
|
type @var{T} is passed as a @code{@var{t}*} argument to a C function,
|
|
where @var{t} is the C type corresponding to the Ada type @var{T}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
|
|
parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
|
|
argument to a C function, where @var{t} is the C type corresponding to
|
|
the Ada type @var{T}. In the case of an elementary @code{out} or
|
|
@code{in out} parameter, a pointer to a temporary copy is used to
|
|
preserve by-copy semantics.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada parameter of a record type @var{T}, of any mode, is passed as a
|
|
@code{@var{t}*} argument to a C function, where @var{t} is the C
|
|
structure corresponding to the Ada type @var{T}.
|
|
@end cartouche
|
|
Followed. This convention may be overridden by the use of the C_Pass_By_Copy
|
|
pragma, or Convention, or by explicitly specifying the mechanism for a given
|
|
call using an extended import or export pragma.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada parameter of an array type with component type @var{T}, of any
|
|
mode, is passed as a @code{@var{t}*} argument to a C function, where
|
|
@var{t} is the C type corresponding to the Ada type @var{T}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada parameter of an access-to-subprogram type is passed as a pointer
|
|
to a C function whose prototype corresponds to the designated
|
|
subprogram's specification.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex COBOL, interfacing with
|
|
@unnumberedsec B.4(95-98): Interfacing with COBOL
|
|
@sp 1
|
|
@cartouche
|
|
An Ada implementation should support the following interface
|
|
correspondences between Ada and COBOL@.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
|
|
the COBOL type corresponding to @var{T}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
|
|
the corresponding COBOL type.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
|
|
COBOL type corresponding to the Ada parameter type; for scalars, a local
|
|
copy is used if necessary to ensure by-copy semantics.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Fortran, interfacing with
|
|
@unnumberedsec B.5(22-26): Interfacing with Fortran
|
|
@sp 1
|
|
@cartouche
|
|
An Ada implementation should support the following interface
|
|
correspondences between Ada and Fortran:
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada procedure corresponds to a Fortran subroutine.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada function corresponds to a Fortran function.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada parameter of an elementary, array, or record type @var{T} is
|
|
passed as a @var{T} argument to a Fortran procedure, where @var{T} is
|
|
the Fortran type corresponding to the Ada type @var{T}, and where the
|
|
INTENT attribute of the corresponding dummy argument matches the Ada
|
|
formal parameter mode; the Fortran implementation's parameter passing
|
|
conventions are used. For elementary types, a local copy is used if
|
|
necessary to ensure by-copy semantics.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
An Ada parameter of an access-to-subprogram type is passed as a
|
|
reference to a Fortran procedure whose interface corresponds to the
|
|
designated subprogram's specification.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Machine operations
|
|
@unnumberedsec C.1(3-5): Access to Machine Operations
|
|
@sp 1
|
|
@cartouche
|
|
The machine code or intrinsic support should allow access to all
|
|
operations normally available to assembly language programmers for the
|
|
target environment, including privileged instructions, if any.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The interfacing pragmas (see Annex B) should support interface to
|
|
assembler; the default assembler should be associated with the
|
|
convention identifier @code{Assembler}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
If an entity is exported to assembly language, then the implementation
|
|
should allocate it at an addressable location, and should ensure that it
|
|
is retained by the linking process, even if not otherwise referenced
|
|
from the Ada code. The implementation should assume that any call to a
|
|
machine code or assembler subprogram is allowed to read or update every
|
|
object that is specified as exported.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@unnumberedsec C.1(10-16): Access to Machine Operations
|
|
@sp 1
|
|
@cartouche
|
|
The implementation should ensure that little or no overhead is
|
|
associated with calling intrinsic and machine-code subprograms.
|
|
@end cartouche
|
|
Followed for both intrinsics and machine-code subprograms.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
It is recommended that intrinsic subprograms be provided for convenient
|
|
access to any machine operations that provide special capabilities or
|
|
efficiency and that are not otherwise available through the language
|
|
constructs.
|
|
@end cartouche
|
|
Followed. A full set of machine operation intrinsic subprograms is provided.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Atomic read-modify-write operations---e.g.@:, test and set, compare and
|
|
swap, decrement and test, enqueue/dequeue.
|
|
@end cartouche
|
|
Followed on any target supporting such operations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Standard numeric functions---e.g.@:, sin, log.
|
|
@end cartouche
|
|
Followed on any target supporting such operations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
String manipulation operations---e.g.@:, translate and test.
|
|
@end cartouche
|
|
Followed on any target supporting such operations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Vector operations---e.g.@:, compare vector against thresholds.
|
|
@end cartouche
|
|
Followed on any target supporting such operations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Direct operations on I/O ports.
|
|
@end cartouche
|
|
Followed on any target supporting such operations.
|
|
|
|
@cindex Interrupt support
|
|
@unnumberedsec C.3(28): Interrupt Support
|
|
@sp 1
|
|
@cartouche
|
|
If the @code{Ceiling_Locking} policy is not in effect, the
|
|
implementation should provide means for the application to specify which
|
|
interrupts are to be blocked during protected actions, if the underlying
|
|
system allows for a finer-grain control of interrupt blocking.
|
|
@end cartouche
|
|
Followed. The underlying system does not allow for finer-grain control
|
|
of interrupt blocking.
|
|
|
|
@cindex Protected procedure handlers
|
|
@unnumberedsec C.3.1(20-21): Protected Procedure Handlers
|
|
@sp 1
|
|
@cartouche
|
|
Whenever possible, the implementation should allow interrupt handlers to
|
|
be called directly by the hardware.
|
|
@end cartouche
|
|
@c SGI info:
|
|
@ignore
|
|
This is never possible under IRIX, so this is followed by default.
|
|
@end ignore
|
|
Followed on any target where the underlying operating system permits
|
|
such direct calls.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Whenever practical, violations of any
|
|
implementation-defined restrictions should be detected before run time.
|
|
@end cartouche
|
|
Followed. Compile time warnings are given when possible.
|
|
|
|
@cindex Package @code{Interrupts}
|
|
@findex Interrupts
|
|
@unnumberedsec C.3.2(25): Package @code{Interrupts}
|
|
|
|
@sp 1
|
|
@cartouche
|
|
If implementation-defined forms of interrupt handler procedures are
|
|
supported, such as protected procedures with parameters, then for each
|
|
such form of a handler, a type analogous to @code{Parameterless_Handler}
|
|
should be specified in a child package of @code{Interrupts}, with the
|
|
same operations as in the predefined package Interrupts.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Pre-elaboration requirements
|
|
@unnumberedsec C.4(14): Pre-elaboration Requirements
|
|
@sp 1
|
|
@cartouche
|
|
It is recommended that pre-elaborated packages be implemented in such a
|
|
way that there should be little or no code executed at run time for the
|
|
elaboration of entities not already covered by the Implementation
|
|
Requirements.
|
|
@end cartouche
|
|
Followed. Executable code is generated in some cases, e.g.@: loops
|
|
to initialize large arrays.
|
|
|
|
@unnumberedsec C.5(8): Pragma @code{Discard_Names}
|
|
@sp 1
|
|
@cartouche
|
|
If the pragma applies to an entity, then the implementation should
|
|
reduce the amount of storage used for storing names associated with that
|
|
entity.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Package @code{Task_Attributes}
|
|
@findex Task_Attributes
|
|
@unnumberedsec C.7.2(30): The Package Task_Attributes
|
|
@sp 1
|
|
@cartouche
|
|
Some implementations are targeted to domains in which memory use at run
|
|
time must be completely deterministic. For such implementations, it is
|
|
recommended that the storage for task attributes will be pre-allocated
|
|
statically and not from the heap. This can be accomplished by either
|
|
placing restrictions on the number and the size of the task's
|
|
attributes, or by using the pre-allocated storage for the first @var{N}
|
|
attribute objects, and the heap for the others. In the latter case,
|
|
@var{N} should be documented.
|
|
@end cartouche
|
|
Not followed. This implementation is not targeted to such a domain.
|
|
|
|
@cindex Locking Policies
|
|
@unnumberedsec D.3(17): Locking Policies
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The implementation should use names that end with @samp{_Locking} for
|
|
locking policies defined by the implementation.
|
|
@end cartouche
|
|
Followed. Two implementation-defined locking policies are defined,
|
|
whose names (@code{Inheritance_Locking} and
|
|
@code{Concurrent_Readers_Locking}) follow this suggestion.
|
|
|
|
@cindex Entry queuing policies
|
|
@unnumberedsec D.4(16): Entry Queuing Policies
|
|
@sp 1
|
|
@cartouche
|
|
Names that end with @samp{_Queuing} should be used
|
|
for all implementation-defined queuing policies.
|
|
@end cartouche
|
|
Followed. No such implementation-defined queuing policies exist.
|
|
|
|
@cindex Preemptive abort
|
|
@unnumberedsec D.6(9-10): Preemptive Abort
|
|
@sp 1
|
|
@cartouche
|
|
Even though the @code{abort_statement} is included in the list of
|
|
potentially blocking operations (see 9.5.1), it is recommended that this
|
|
statement be implemented in a way that never requires the task executing
|
|
the @code{abort_statement} to block.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
On a multi-processor, the delay associated with aborting a task on
|
|
another processor should be bounded; the implementation should use
|
|
periodic polling, if necessary, to achieve this.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Tasking restrictions
|
|
@unnumberedsec D.7(21): Tasking Restrictions
|
|
@sp 1
|
|
@cartouche
|
|
When feasible, the implementation should take advantage of the specified
|
|
restrictions to produce a more efficient implementation.
|
|
@end cartouche
|
|
GNAT currently takes advantage of these restrictions by providing an optimized
|
|
run time when the Ravenscar profile and the GNAT restricted run time set
|
|
of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
|
|
pragma @code{Profile (Restricted)} for more details.
|
|
|
|
@cindex Time, monotonic
|
|
@unnumberedsec D.8(47-49): Monotonic Time
|
|
@sp 1
|
|
@cartouche
|
|
When appropriate, implementations should provide configuration
|
|
mechanisms to change the value of @code{Tick}.
|
|
@end cartouche
|
|
Such configuration mechanisms are not appropriate to this implementation
|
|
and are thus not supported.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
|
|
be implemented as transformations of the same time base.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
It is recommended that the @dfn{best} time base which exists in
|
|
the underlying system be available to the application through
|
|
@code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Partition communication subsystem
|
|
@cindex PCS
|
|
@unnumberedsec E.5(28-29): Partition Communication Subsystem
|
|
@sp 1
|
|
@cartouche
|
|
Whenever possible, the PCS on the called partition should allow for
|
|
multiple tasks to call the RPC-receiver with different messages and
|
|
should allow them to block until the corresponding subprogram body
|
|
returns.
|
|
@end cartouche
|
|
Followed by GLADE, a separately supplied PCS that can be used with
|
|
GNAT.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The @code{Write} operation on a stream of type @code{Params_Stream_Type}
|
|
should raise @code{Storage_Error} if it runs out of space trying to
|
|
write the @code{Item} into the stream.
|
|
@end cartouche
|
|
Followed by GLADE, a separately supplied PCS that can be used with
|
|
GNAT@.
|
|
|
|
@cindex COBOL support
|
|
@unnumberedsec F(7): COBOL Support
|
|
@sp 1
|
|
@cartouche
|
|
If COBOL (respectively, C) is widely supported in the target
|
|
environment, implementations supporting the Information Systems Annex
|
|
should provide the child package @code{Interfaces.COBOL} (respectively,
|
|
@code{Interfaces.C}) specified in Annex B and should support a
|
|
@code{convention_identifier} of COBOL (respectively, C) in the interfacing
|
|
pragmas (see Annex B), thus allowing Ada programs to interface with
|
|
programs written in that language.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Decimal radix support
|
|
@unnumberedsec F.1(2): Decimal Radix Support
|
|
@sp 1
|
|
@cartouche
|
|
Packed decimal should be used as the internal representation for objects
|
|
of subtype @var{S} when @var{S}'Machine_Radix = 10.
|
|
@end cartouche
|
|
Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
|
|
representations.
|
|
|
|
@cindex Numerics
|
|
@unnumberedsec G: Numerics
|
|
@sp 2
|
|
@cartouche
|
|
If Fortran (respectively, C) is widely supported in the target
|
|
environment, implementations supporting the Numerics Annex
|
|
should provide the child package @code{Interfaces.Fortran} (respectively,
|
|
@code{Interfaces.C}) specified in Annex B and should support a
|
|
@code{convention_identifier} of Fortran (respectively, C) in the interfacing
|
|
pragmas (see Annex B), thus allowing Ada programs to interface with
|
|
programs written in that language.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Complex types
|
|
@unnumberedsec G.1.1(56-58): Complex Types
|
|
@sp 2
|
|
@cartouche
|
|
Because the usual mathematical meaning of multiplication of a complex
|
|
operand and a real operand is that of the scaling of both components of
|
|
the former by the latter, an implementation should not perform this
|
|
operation by first promoting the real operand to complex type and then
|
|
performing a full complex multiplication. In systems that, in the
|
|
future, support an Ada binding to IEC 559:1989, the latter technique
|
|
will not generate the required result when one of the components of the
|
|
complex operand is infinite. (Explicit multiplication of the infinite
|
|
component by the zero component obtained during promotion yields a NaN
|
|
that propagates into the final result.) Analogous advice applies in the
|
|
case of multiplication of a complex operand and a pure-imaginary
|
|
operand, and in the case of division of a complex operand by a real or
|
|
pure-imaginary operand.
|
|
@end cartouche
|
|
Not followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Similarly, because the usual mathematical meaning of addition of a
|
|
complex operand and a real operand is that the imaginary operand remains
|
|
unchanged, an implementation should not perform this operation by first
|
|
promoting the real operand to complex type and then performing a full
|
|
complex addition. In implementations in which the @code{Signed_Zeros}
|
|
attribute of the component type is @code{True} (and which therefore
|
|
conform to IEC 559:1989 in regard to the handling of the sign of zero in
|
|
predefined arithmetic operations), the latter technique will not
|
|
generate the required result when the imaginary component of the complex
|
|
operand is a negatively signed zero. (Explicit addition of the negative
|
|
zero to the zero obtained during promotion yields a positive zero.)
|
|
Analogous advice applies in the case of addition of a complex operand
|
|
and a pure-imaginary operand, and in the case of subtraction of a
|
|
complex operand and a real or pure-imaginary operand.
|
|
@end cartouche
|
|
Not followed.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
Implementations in which @code{Real'Signed_Zeros} is @code{True} should
|
|
attempt to provide a rational treatment of the signs of zero results and
|
|
result components. As one example, the result of the @code{Argument}
|
|
function should have the sign of the imaginary component of the
|
|
parameter @code{X} when the point represented by that parameter lies on
|
|
the positive real axis; as another, the sign of the imaginary component
|
|
of the @code{Compose_From_Polar} function should be the same as
|
|
(respectively, the opposite of) that of the @code{Argument} parameter when that
|
|
parameter has a value of zero and the @code{Modulus} parameter has a
|
|
nonnegative (respectively, negative) value.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Complex elementary functions
|
|
@unnumberedsec G.1.2(49): Complex Elementary Functions
|
|
@sp 1
|
|
@cartouche
|
|
Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
|
|
@code{True} should attempt to provide a rational treatment of the signs
|
|
of zero results and result components. For example, many of the complex
|
|
elementary functions have components that are odd functions of one of
|
|
the parameter components; in these cases, the result component should
|
|
have the sign of the parameter component at the origin. Other complex
|
|
elementary functions have zero components whose sign is opposite that of
|
|
a parameter component at the origin, or is always positive or always
|
|
negative.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Accuracy requirements
|
|
@unnumberedsec G.2.4(19): Accuracy Requirements
|
|
@sp 1
|
|
@cartouche
|
|
The versions of the forward trigonometric functions without a
|
|
@code{Cycle} parameter should not be implemented by calling the
|
|
corresponding version with a @code{Cycle} parameter of
|
|
@code{2.0*Numerics.Pi}, since this will not provide the required
|
|
accuracy in some portions of the domain. For the same reason, the
|
|
version of @code{Log} without a @code{Base} parameter should not be
|
|
implemented by calling the corresponding version with a @code{Base}
|
|
parameter of @code{Numerics.e}.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@cindex Complex arithmetic accuracy
|
|
@cindex Accuracy, complex arithmetic
|
|
@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
|
|
|
|
@sp 1
|
|
@cartouche
|
|
The version of the @code{Compose_From_Polar} function without a
|
|
@code{Cycle} parameter should not be implemented by calling the
|
|
corresponding version with a @code{Cycle} parameter of
|
|
@code{2.0*Numerics.Pi}, since this will not provide the required
|
|
accuracy in some portions of the domain.
|
|
@end cartouche
|
|
Followed.
|
|
|
|
@c -----------------------------------------
|
|
@node Implementation Defined Characteristics
|
|
@chapter Implementation Defined Characteristics
|
|
|
|
@noindent
|
|
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 and are designated as
|
|
implementation-defined. These are mentioned 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
|
|
followed by a description in italic font of how GNAT
|
|
@c SGI info:
|
|
@ignore
|
|
in the ProDev Ada
|
|
implementation on IRIX 5.3 operating system or greater
|
|
@end ignore
|
|
handles the implementation dependence.
|
|
|
|
You can use this chapter as a guide to minimizing implementation
|
|
dependent features in your programs if portability to other compilers
|
|
and other operating systems is an important consideration. The numbers
|
|
in each section below correspond to the paragraph number in the Ada
|
|
Reference Manual.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{2}. Whether or not each recommendation given in Implementation
|
|
Advice is followed. See 1.1.2(37).
|
|
@end cartouche
|
|
@noindent
|
|
@xref{Implementation Advice}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
|
|
@end cartouche
|
|
@noindent
|
|
The complexity of programs that can be processed is limited only by the
|
|
total amount of available virtual memory, and disk space for the
|
|
generated object files.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{4}. Variations from the standard that are impractical to avoid
|
|
given the implementation's execution environment. See 1.1.3(6).
|
|
@end cartouche
|
|
@noindent
|
|
There are no variations from the standard.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{5}. Which @code{code_statement}s cause external
|
|
interactions. See 1.1.3(10).
|
|
@end cartouche
|
|
@noindent
|
|
Any @code{code_statement} can potentially cause external interactions.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{6}. The coded representation for the text of an Ada
|
|
program. See 2.1(4).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on source representation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{7}. The control functions allowed in comments. See 2.1(14).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on source representation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{8}. The representation for an end of line. See 2.2(2).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on source representation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{9}. Maximum supported line length and lexical element
|
|
length. See 2.2(15).
|
|
@end cartouche
|
|
@noindent
|
|
The maximum line length is 255 characters and the maximum length of a
|
|
lexical element is also 255 characters.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{10}. Implementation defined pragmas. See 2.8(14).
|
|
@end cartouche
|
|
@noindent
|
|
|
|
@xref{Implementation Defined Pragmas}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
|
|
@end cartouche
|
|
@noindent
|
|
Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
|
|
parameter, checks that the optimization flag is set, and aborts if it is
|
|
not.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{12}. The sequence of characters of the value returned by
|
|
@code{@var{S}'Image} when some of the graphic characters of
|
|
@code{@var{S}'Wide_Image} are not defined in @code{Character}. See
|
|
3.5(37).
|
|
@end cartouche
|
|
@noindent
|
|
The sequence of characters is as defined by the wide character encoding
|
|
method used for the source. See section on source representation for
|
|
further details.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{13}. The predefined integer types declared in
|
|
@code{Standard}. See 3.5.4(25).
|
|
@end cartouche
|
|
@noindent
|
|
@table @code
|
|
@item Short_Short_Integer
|
|
8 bit signed
|
|
@item Short_Integer
|
|
(Short) 16 bit signed
|
|
@item Integer
|
|
32 bit signed
|
|
@item Long_Integer
|
|
64 bit signed (on most 64 bit targets, depending on the C definition of long).
|
|
32 bit signed (all other targets)
|
|
@item Long_Long_Integer
|
|
64 bit signed
|
|
@end table
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{14}. Any nonstandard integer types and the operators defined
|
|
for them. See 3.5.4(26).
|
|
@end cartouche
|
|
@noindent
|
|
There are no nonstandard integer types.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{15}. Any nonstandard real types and the operators defined for
|
|
them. See 3.5.6(8).
|
|
@end cartouche
|
|
@noindent
|
|
There are no nonstandard real types.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{16}. What combinations of requested decimal precision and range
|
|
are supported for floating point types. See 3.5.7(7).
|
|
@end cartouche
|
|
@noindent
|
|
The precision and range is as defined by the IEEE standard.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{17}. The predefined floating point types declared in
|
|
@code{Standard}. See 3.5.7(16).
|
|
@end cartouche
|
|
@noindent
|
|
@table @code
|
|
@item Short_Float
|
|
32 bit IEEE short
|
|
@item Float
|
|
(Short) 32 bit IEEE short
|
|
@item Long_Float
|
|
64 bit IEEE long
|
|
@item Long_Long_Float
|
|
64 bit IEEE long (80 bit IEEE long on x86 processors)
|
|
@end table
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
|
|
@end cartouche
|
|
@noindent
|
|
@code{Fine_Delta} is 2**(@minus{}63)
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{19}. What combinations of small, range, and digits are
|
|
supported for fixed point types. See 3.5.9(10).
|
|
@end cartouche
|
|
@noindent
|
|
Any combinations are permitted that do not result in a small less than
|
|
@code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
|
|
If the mantissa is larger than 53 bits on machines where Long_Long_Float
|
|
is 64 bits (true of all architectures except ia32), then the output from
|
|
Text_IO is accurate to only 53 bits, rather than the full mantissa. This
|
|
is because floating-point conversions are used to convert fixed point.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{20}. The result of @code{Tags.Expanded_Name} for types declared
|
|
within an unnamed @code{block_statement}. See 3.9(10).
|
|
@end cartouche
|
|
@noindent
|
|
Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
|
|
decimal integer are allocated.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{21}. Implementation-defined attributes. See 4.1.4(12).
|
|
@end cartouche
|
|
@noindent
|
|
@xref{Implementation Defined Attributes}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{22}. Any implementation-defined time types. See 9.6(6).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined time types.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{23}. The time base associated with relative delays.
|
|
@end cartouche
|
|
@noindent
|
|
See 9.6(20). The time base used is that provided by the C library
|
|
function @code{gettimeofday}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{24}. The time base of the type @code{Calendar.Time}. See
|
|
9.6(23).
|
|
@end cartouche
|
|
@noindent
|
|
The time base used is that provided by the C library function
|
|
@code{gettimeofday}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{25}. The time zone used for package @code{Calendar}
|
|
operations. See 9.6(24).
|
|
@end cartouche
|
|
@noindent
|
|
The time zone used by package @code{Calendar} is the current system time zone
|
|
setting for local time, as accessed by the C library function
|
|
@code{localtime}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{26}. Any limit on @code{delay_until_statements} of
|
|
@code{select_statements}. See 9.6(29).
|
|
@end cartouche
|
|
@noindent
|
|
There are no such limits.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{27}. Whether or not two non-overlapping parts of a composite
|
|
object are independently addressable, in the case where packing, record
|
|
layout, or @code{Component_Size} is specified for the object. See
|
|
9.10(1).
|
|
@end cartouche
|
|
@noindent
|
|
Separate components are independently addressable if they do not share
|
|
overlapping storage units.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{28}. The representation for a compilation. See 10.1(2).
|
|
@end cartouche
|
|
@noindent
|
|
A compilation is represented by a sequence of files presented to the
|
|
compiler in a single invocation of the @command{gcc} command.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{29}. Any restrictions on compilations that contain multiple
|
|
compilation_units. See 10.1(4).
|
|
@end cartouche
|
|
@noindent
|
|
No single file can contain more than one compilation unit, but any
|
|
sequence of files can be presented to the compiler as a single
|
|
compilation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{30}. The mechanisms for creating an environment and for adding
|
|
and replacing compilation units. See 10.1.4(3).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on compilation model.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{31}. The manner of explicitly assigning library units to a
|
|
partition. See 10.2(2).
|
|
@end cartouche
|
|
@noindent
|
|
If a unit contains an Ada main program, then the Ada units for the partition
|
|
are determined by recursive application of the rules in the Ada Reference
|
|
Manual section 10.2(2-6). In other words, the Ada units will be those that
|
|
are needed by the main program, and then this definition of need is applied
|
|
recursively to those units, and the partition contains the transitive
|
|
closure determined by this relationship. In short, all the necessary units
|
|
are included, with no need to explicitly specify the list. If additional
|
|
units are required, e.g.@: by foreign language units, then all units must be
|
|
mentioned in the context clause of one of the needed Ada units.
|
|
|
|
If the partition contains no main program, or if the main program is in
|
|
a language other than Ada, then GNAT
|
|
provides the binder options @option{-z} and @option{-n} respectively, and in
|
|
this case a list of units can be explicitly supplied to the binder for
|
|
inclusion in the partition (all units needed by these units will also
|
|
be included automatically). For full details on the use of these
|
|
options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
|
|
@value{EDITION} User's Guide}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{32}. The implementation-defined means, if any, of specifying
|
|
which compilation units are needed by a given compilation unit. See
|
|
10.2(2).
|
|
@end cartouche
|
|
@noindent
|
|
The units needed by a given compilation unit are as defined in
|
|
the Ada Reference Manual section 10.2(2-6). There are no
|
|
implementation-defined pragmas or other implementation-defined
|
|
means for specifying needed units.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{33}. The manner of designating the main subprogram of a
|
|
partition. See 10.2(7).
|
|
@end cartouche
|
|
@noindent
|
|
The main program is designated by providing the name of the
|
|
corresponding @file{ALI} file as the input parameter to the binder.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{34}. The order of elaboration of @code{library_items}. See
|
|
10.2(18).
|
|
@end cartouche
|
|
@noindent
|
|
The first constraint on ordering is that it meets the requirements of
|
|
Chapter 10 of the Ada Reference Manual. This still leaves some
|
|
implementation dependent choices, which are resolved by first
|
|
elaborating bodies as early as possible (i.e., in preference to specs
|
|
where there is a choice), and second by evaluating the immediate with
|
|
clauses of a unit to determine the probably best choice, and
|
|
third by elaborating in alphabetical order of unit names
|
|
where a choice still remains.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{35}. Parameter passing and function return for the main
|
|
subprogram. See 10.2(21).
|
|
@end cartouche
|
|
@noindent
|
|
The main program has no parameters. It may be a procedure, or a function
|
|
returning an integer type. In the latter case, the returned integer
|
|
value is the return code of the program (overriding any value that
|
|
may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{36}. The mechanisms for building and running partitions. See
|
|
10.2(24).
|
|
@end cartouche
|
|
@noindent
|
|
GNAT itself supports programs with only a single partition. The GNATDIST
|
|
tool provided with the GLADE package (which also includes an implementation
|
|
of the PCS) provides a completely flexible method for building and running
|
|
programs consisting of multiple partitions. See the separate GLADE manual
|
|
for details.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{37}. The details of program execution, including program
|
|
termination. See 10.2(25).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on compilation model.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{38}. The semantics of any non-active partitions supported by the
|
|
implementation. See 10.2(28).
|
|
@end cartouche
|
|
@noindent
|
|
Passive partitions are supported on targets where shared memory is
|
|
provided by the operating system. See the GLADE reference manual for
|
|
further details.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{39}. The information returned by @code{Exception_Message}. See
|
|
11.4.1(10).
|
|
@end cartouche
|
|
@noindent
|
|
Exception message returns the null string unless a specific message has
|
|
been passed by the program.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{40}. The result of @code{Exceptions.Exception_Name} for types
|
|
declared within an unnamed @code{block_statement}. See 11.4.1(12).
|
|
@end cartouche
|
|
@noindent
|
|
Blocks have implementation defined names of the form @code{B@var{nnn}}
|
|
where @var{nnn} is an integer.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{41}. The information returned by
|
|
@code{Exception_Information}. See 11.4.1(13).
|
|
@end cartouche
|
|
@noindent
|
|
@code{Exception_Information} returns a string in the following format:
|
|
|
|
@smallexample
|
|
@emph{Exception_Name:} nnnnn
|
|
@emph{Message:} mmmmm
|
|
@emph{PID:} ppp
|
|
@emph{Call stack traceback locations:}
|
|
0xhhhh 0xhhhh 0xhhhh ... 0xhhh
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{nnnn} is the fully qualified name of the exception in all upper
|
|
case letters. This line is always present.
|
|
|
|
@item
|
|
@code{mmmm} is the message (this line present only if message is non-null)
|
|
|
|
@item
|
|
@code{ppp} is the Process Id value as a decimal integer (this line is
|
|
present only if the Process Id is nonzero). Currently we are
|
|
not making use of this field.
|
|
|
|
@item
|
|
The Call stack traceback locations line and the following values
|
|
are present only if at least one traceback location was recorded.
|
|
The values are given in C style format, with lower case letters
|
|
for a-f, and only as many digits present as are necessary.
|
|
@end itemize
|
|
|
|
@noindent
|
|
The line terminator sequence at the end of each line, including
|
|
the last line is a single @code{LF} character (@code{16#0A#}).
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{42}. Implementation-defined check names. See 11.5(27).
|
|
@end cartouche
|
|
@noindent
|
|
The implementation defined check name Alignment_Check controls checking of
|
|
address clause values for proper alignment (that is, the address supplied
|
|
must be consistent with the alignment of the type).
|
|
|
|
In addition, a user program can add implementation-defined check names
|
|
by means of the pragma Check_Name.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{43}. The interpretation of each aspect of representation. See
|
|
13.1(20).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on data representations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{44}. Any restrictions placed upon representation items. See
|
|
13.1(20).
|
|
@end cartouche
|
|
@noindent
|
|
See separate section on data representations.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{45}. The meaning of @code{Size} for indefinite subtypes. See
|
|
13.3(48).
|
|
@end cartouche
|
|
@noindent
|
|
Size for an indefinite subtype is the maximum possible size, except that
|
|
for the case of a subprogram parameter, the size of the parameter object
|
|
is the actual size.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{46}. The default external representation for a type tag. See
|
|
13.3(75).
|
|
@end cartouche
|
|
@noindent
|
|
The default external representation for a type tag is the fully expanded
|
|
name of the type in upper case letters.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{47}. What determines whether a compilation unit is the same in
|
|
two different partitions. See 13.3(76).
|
|
@end cartouche
|
|
@noindent
|
|
A compilation unit is the same in two different partitions if and only
|
|
if it derives from the same source file.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{48}. Implementation-defined components. See 13.5.1(15).
|
|
@end cartouche
|
|
@noindent
|
|
The only implementation defined component is the tag for a tagged type,
|
|
which contains a pointer to the dispatching table.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
|
|
ordering. See 13.5.3(5).
|
|
@end cartouche
|
|
@noindent
|
|
@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
|
|
implementation, so no non-default bit ordering is supported. The default
|
|
bit ordering corresponds to the natural endianness of the target architecture.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{50}. The contents of the visible part of package @code{System}
|
|
and its language-defined children. See 13.7(2).
|
|
@end cartouche
|
|
@noindent
|
|
See the definition of these packages in files @file{system.ads} and
|
|
@file{s-stoele.ads}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{51}. The contents of the visible part of package
|
|
@code{System.Machine_Code}, and the meaning of
|
|
@code{code_statements}. See 13.8(7).
|
|
@end cartouche
|
|
@noindent
|
|
See the definition and documentation in file @file{s-maccod.ads}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{52}. The effect of unchecked conversion. See 13.9(11).
|
|
@end cartouche
|
|
@noindent
|
|
Unchecked conversion between types of the same size
|
|
results in an uninterpreted transmission of the bits from one type
|
|
to the other. If the types are of unequal sizes, then in the case of
|
|
discrete types, a shorter source is first zero or sign extended as
|
|
necessary, and a shorter target is simply truncated on the left.
|
|
For all non-discrete types, the source is first copied if necessary
|
|
to ensure that the alignment requirements of the target are met, then
|
|
a pointer is constructed to the source value, and the result is obtained
|
|
by dereferencing this pointer after converting it to be a pointer to the
|
|
target type. Unchecked conversions where the target subtype is an
|
|
unconstrained array are not permitted. If the target alignment is
|
|
greater than the source alignment, then a copy of the result is
|
|
made with appropriate alignment
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{53}. The semantics of operations on invalid representations.
|
|
See 13.9.2(10-11).
|
|
@end cartouche
|
|
@noindent
|
|
For assignments and other operations where the use of invalid values cannot
|
|
result in erroneous behavior, the compiler ignores the possibility of invalid
|
|
values. An exception is raised at the point where an invalid value would
|
|
result in erroneous behavior. For example executing:
|
|
|
|
@smallexample @c ada
|
|
procedure invalidvals is
|
|
X : Integer := -1;
|
|
Y : Natural range 1 .. 10;
|
|
for Y'Address use X'Address;
|
|
Z : Natural range 1 .. 10;
|
|
A : array (Natural range 1 .. 10) of Integer;
|
|
begin
|
|
Z := Y; -- no exception
|
|
A (Z) := 3; -- exception raised;
|
|
end;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
As indicated, an exception is raised on the array assignment, but not
|
|
on the simple assignment of the invalid negative value from Y to Z.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{53}. The manner of choosing a storage pool for an access type
|
|
when @code{Storage_Pool} is not specified for the type. See 13.11(17).
|
|
@end cartouche
|
|
@noindent
|
|
There are 3 different standard pools used by the compiler when
|
|
@code{Storage_Pool} is not specified depending whether the type is local
|
|
to a subprogram or defined at the library level and whether
|
|
@code{Storage_Size}is specified or not. See documentation in the runtime
|
|
library units @code{System.Pool_Global}, @code{System.Pool_Size} and
|
|
@code{System.Pool_Local} in files @file{s-poosiz.ads},
|
|
@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
|
|
default pools used.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{54}. Whether or not the implementation provides user-accessible
|
|
names for the standard pool type(s). See 13.11(17).
|
|
@end cartouche
|
|
@noindent
|
|
|
|
See documentation in the sources of the run time mentioned in paragraph
|
|
@strong{53} . All these pools are accessible by means of @code{with}'ing
|
|
these units.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
|
|
@end cartouche
|
|
@noindent
|
|
@code{Storage_Size} is measured in storage units, and refers to the
|
|
total space available for an access type collection, or to the primary
|
|
stack space for a task.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{56}. Implementation-defined aspects of storage pools. See
|
|
13.11(22).
|
|
@end cartouche
|
|
@noindent
|
|
See documentation in the sources of the run time mentioned in paragraph
|
|
@strong{53} for details on GNAT-defined aspects of storage pools.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{57}. The set of restrictions allowed in a pragma
|
|
@code{Restrictions}. See 13.12(7).
|
|
@end cartouche
|
|
@noindent
|
|
@xref{Implementation Defined Restrictions}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{58}. The consequences of violating limitations on
|
|
@code{Restrictions} pragmas. See 13.12(9).
|
|
@end cartouche
|
|
@noindent
|
|
Restrictions that can be checked at compile time result in illegalities
|
|
if violated. Currently there are no other consequences of violating
|
|
restrictions.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{59}. The representation used by the @code{Read} and
|
|
@code{Write} attributes of elementary types in terms of stream
|
|
elements. See 13.13.2(9).
|
|
@end cartouche
|
|
@noindent
|
|
The representation is the in-memory representation of the base type of
|
|
the type, using the number of bits corresponding to the
|
|
@code{@var{type}'Size} value, and the natural ordering of the machine.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{60}. The names and characteristics of the numeric subtypes
|
|
declared in the visible part of package @code{Standard}. See A.1(3).
|
|
@end cartouche
|
|
@noindent
|
|
See items describing the integer and floating-point types supported.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{61}. The accuracy actually achieved by the elementary
|
|
functions. See A.5.1(1).
|
|
@end cartouche
|
|
@noindent
|
|
The elementary functions correspond to the functions available in the C
|
|
library. Only fast math mode is implemented.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{62}. The sign of a zero result from some of the operators or
|
|
functions in @code{Numerics.Generic_Elementary_Functions}, when
|
|
@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
|
|
@end cartouche
|
|
@noindent
|
|
The sign of zeroes follows the requirements of the IEEE 754 standard on
|
|
floating-point.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{63}. The value of
|
|
@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
|
|
@end cartouche
|
|
@noindent
|
|
Maximum image width is 6864, see library file @file{s-rannum.ads}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{64}. The value of
|
|
@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
|
|
@end cartouche
|
|
@noindent
|
|
Maximum image width is 6864, see library file @file{s-rannum.ads}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{65}. The algorithms for random number generation. See
|
|
A.5.2(32).
|
|
@end cartouche
|
|
@noindent
|
|
The algorithm is the Mersenne Twister, as documented in the source file
|
|
@file{s-rannum.adb}. This version of the algorithm has a period of
|
|
2**19937-1.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{66}. The string representation of a random number generator's
|
|
state. See A.5.2(38).
|
|
@end cartouche
|
|
@noindent
|
|
The value returned by the Image function is the concatenation of
|
|
the fixed-width decimal representations of the 624 32-bit integers
|
|
of the state vector.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{67}. The minimum time interval between calls to the
|
|
time-dependent Reset procedure that are guaranteed to initiate different
|
|
random number sequences. See A.5.2(45).
|
|
@end cartouche
|
|
@noindent
|
|
The minimum period between reset calls to guarantee distinct series of
|
|
random numbers is one microsecond.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{68}. The values of the @code{Model_Mantissa},
|
|
@code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
|
|
@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
|
|
Annex is not supported. See A.5.3(72).
|
|
@end cartouche
|
|
@noindent
|
|
Run the compiler with @option{-gnatS} to produce a listing of package
|
|
@code{Standard}, has the values of all numeric attributes.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{69}. Any implementation-defined characteristics of the
|
|
input-output packages. See A.7(14).
|
|
@end cartouche
|
|
@noindent
|
|
There are no special implementation defined characteristics for these
|
|
packages.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
|
|
A.9(10).
|
|
@end cartouche
|
|
@noindent
|
|
All type representations are contiguous, and the @code{Buffer_Size} is
|
|
the value of @code{@var{type}'Size} rounded up to the next storage unit
|
|
boundary.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{71}. External files for standard input, standard output, and
|
|
standard error See A.10(5).
|
|
@end cartouche
|
|
@noindent
|
|
These files are mapped onto the files provided by the C streams
|
|
libraries. See source file @file{i-cstrea.ads} for further details.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{72}. The accuracy of the value produced by @code{Put}. See
|
|
A.10.9(36).
|
|
@end cartouche
|
|
@noindent
|
|
If more digits are requested in the output than are represented by the
|
|
precision of the value, zeroes are output in the corresponding least
|
|
significant digit positions.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
|
|
@code{Command_Name}. See A.15(1).
|
|
@end cartouche
|
|
@noindent
|
|
These are mapped onto the @code{argv} and @code{argc} parameters of the
|
|
main program in the natural manner.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{74}. The interpretation of the @code{Form} parameter in procedure
|
|
@code{Create_Directory}. See A.16(56).
|
|
@end cartouche
|
|
@noindent
|
|
The @code{Form} parameter is not used.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{75}. The interpretation of the @code{Form} parameter in procedure
|
|
@code{Create_Path}. See A.16(60).
|
|
@end cartouche
|
|
@noindent
|
|
The @code{Form} parameter is not used.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{76}. The interpretation of the @code{Form} parameter in procedure
|
|
@code{Copy_File}. See A.16(68).
|
|
@end cartouche
|
|
@noindent
|
|
The @code{Form} parameter is case-insensitive.
|
|
|
|
Two fields are recognized in the @code{Form} parameter:
|
|
|
|
@table @code
|
|
|
|
@item preserve=<value>
|
|
|
|
@item mode=<value>
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
<value> starts immediately after the character '=' and ends with the
|
|
character immediately preceding the next comma (',') or with the last
|
|
character of the parameter.
|
|
|
|
The only possible values for preserve= are:
|
|
|
|
@table @code
|
|
|
|
@item no_attributes
|
|
Do not try to preserve any file attributes. This is the default if no
|
|
preserve= is found in Form.
|
|
|
|
@item all_attributes
|
|
Try to preserve all file attributes (timestamps, access rights).
|
|
|
|
@item timestamps
|
|
Preserve the timestamp of the copied file, but not the other file attributes.
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
The only possible values for mode= are:
|
|
|
|
@table @code
|
|
|
|
@item copy
|
|
Only do the copy if the destination file does not already exist. If it already
|
|
exists, Copy_File fails.
|
|
|
|
@item overwrite
|
|
Copy the file in all cases. Overwrite an already existing destination file.
|
|
|
|
@item append
|
|
Append the original file to the destination file. If the destination file does
|
|
not exist, the destination file is a copy of the source file. When mode=append,
|
|
the field preserve=, if it exists, is not taken into account.
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
If the Form parameter includes one or both of the fields and the value or
|
|
values are incorrect, Copy_file fails with Use_Error.
|
|
|
|
Examples of correct Forms:
|
|
|
|
@smallexample
|
|
Form => "preserve=no_attributes,mode=overwrite" (the default)
|
|
Form => "mode=append"
|
|
Form => "mode=copy, preserve=all_attributes"
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Examples of incorrect Forms
|
|
|
|
@smallexample
|
|
Form => "preserve=junk"
|
|
Form => "mode=internal, preserve=timestamps"
|
|
@end smallexample
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{77}. Implementation-defined convention names. See B.1(11).
|
|
@end cartouche
|
|
@noindent
|
|
The following convention names are supported
|
|
|
|
@table @code
|
|
@item Ada
|
|
Ada
|
|
@item Ada_Pass_By_Copy
|
|
Allowed for any types except by-reference types such as limited
|
|
records. Compatible with convention Ada, but causes any parameters
|
|
with this convention to be passed by copy.
|
|
@item Ada_Pass_By_Reference
|
|
Allowed for any types except by-copy types such as scalars.
|
|
Compatible with convention Ada, but causes any parameters
|
|
with this convention to be passed by reference.
|
|
@item Assembler
|
|
Assembly language
|
|
@item Asm
|
|
Synonym for Assembler
|
|
@item Assembly
|
|
Synonym for Assembler
|
|
@item C
|
|
C
|
|
@item C_Pass_By_Copy
|
|
Allowed only for record types, like C, but also notes that record
|
|
is to be passed by copy rather than reference.
|
|
@item COBOL
|
|
COBOL
|
|
@item C_Plus_Plus (or CPP)
|
|
C++
|
|
@item Default
|
|
Treated the same as C
|
|
@item External
|
|
Treated the same as C
|
|
@item Fortran
|
|
Fortran
|
|
@item Intrinsic
|
|
For support of pragma @code{Import} with convention Intrinsic, see
|
|
separate section on Intrinsic Subprograms.
|
|
@item Stdcall
|
|
Stdcall (used for Windows implementations only). This convention correspond
|
|
to the WINAPI (previously called Pascal convention) C/C++ convention under
|
|
Windows. A routine with this convention cleans the stack before
|
|
exit. This pragma cannot be applied to a dispatching call.
|
|
@item DLL
|
|
Synonym for Stdcall
|
|
@item Win32
|
|
Synonym for Stdcall
|
|
@item Stubbed
|
|
Stubbed is a special convention used to indicate that the body of the
|
|
subprogram will be entirely ignored. Any call to the subprogram
|
|
is converted into a raise of the @code{Program_Error} exception. If a
|
|
pragma @code{Import} specifies convention @code{stubbed} then no body need
|
|
be present at all. This convention is useful during development for the
|
|
inclusion of subprograms whose body has not yet been written.
|
|
|
|
@end table
|
|
@noindent
|
|
In addition, all otherwise unrecognized convention names are also
|
|
treated as being synonymous with convention C@. In all implementations
|
|
except for VMS, use of such other names results in a warning. In VMS
|
|
implementations, these names are accepted silently.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{78}. The meaning of link names. See B.1(36).
|
|
@end cartouche
|
|
@noindent
|
|
Link names are the actual names used by the linker.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{79}. The manner of choosing link names when neither the link
|
|
name nor the address of an imported or exported entity is specified. See
|
|
B.1(36).
|
|
@end cartouche
|
|
@noindent
|
|
The default linker name is that which would be assigned by the relevant
|
|
external language, interpreting the Ada name as being in all lower case
|
|
letters.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{80}. The effect of pragma @code{Linker_Options}. See B.1(37).
|
|
@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.
|
|
NUL characters if they appear act as argument separators, so for example
|
|
|
|
@smallexample @c ada
|
|
pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
|
|
linker. The order of linker options is preserved for a given unit. The final
|
|
list of options passed to the linker is in reverse order of the elaboration
|
|
order. For example, linker options for a body always appear before the options
|
|
from the corresponding package spec.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{81}. The contents of the visible part of package
|
|
@code{Interfaces} and its language-defined descendants. See B.2(1).
|
|
@end cartouche
|
|
@noindent
|
|
See files with prefix @file{i-} in the distributed library.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{82}. Implementation-defined children of package
|
|
@code{Interfaces}. The contents of the visible part of package
|
|
@code{Interfaces}. See B.2(11).
|
|
@end cartouche
|
|
@noindent
|
|
See files with prefix @file{i-} in the distributed library.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{83}. The types @code{Floating}, @code{Long_Floating},
|
|
@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
|
|
@code{COBOL_Character}; and the initialization of the variables
|
|
@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
|
|
@code{Interfaces.COBOL}. See B.4(50).
|
|
@end cartouche
|
|
@noindent
|
|
@table @code
|
|
@item Floating
|
|
Float
|
|
@item Long_Floating
|
|
(Floating) Long_Float
|
|
@item Binary
|
|
Integer
|
|
@item Long_Binary
|
|
Long_Long_Integer
|
|
@item Decimal_Element
|
|
Character
|
|
@item COBOL_Character
|
|
Character
|
|
@end table
|
|
|
|
@noindent
|
|
For initialization, see the file @file{i-cobol.ads} in the distributed library.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{84}. Support for access to machine instructions. See C.1(1).
|
|
@end cartouche
|
|
@noindent
|
|
See documentation in file @file{s-maccod.ads} in the distributed library.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{85}. Implementation-defined aspects of access to machine
|
|
operations. See C.1(9).
|
|
@end cartouche
|
|
@noindent
|
|
See documentation in file @file{s-maccod.ads} in the distributed library.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{86}. Implementation-defined aspects of interrupts. See C.3(2).
|
|
@end cartouche
|
|
@noindent
|
|
Interrupts are mapped to signals or conditions as appropriate. See
|
|
definition of unit
|
|
@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
|
|
on the interrupts supported on a particular target.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{87}. Implementation-defined aspects of pre-elaboration. See
|
|
C.4(13).
|
|
@end cartouche
|
|
@noindent
|
|
GNAT does not permit a partition to be restarted without reloading,
|
|
except under control of the debugger.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{88}. The semantics of pragma @code{Discard_Names}. See C.5(7).
|
|
@end cartouche
|
|
@noindent
|
|
Pragma @code{Discard_Names} causes names of enumeration literals to
|
|
be suppressed. In the presence of this pragma, the Image attribute
|
|
provides the image of the Pos of the literal, and Value accepts
|
|
Pos values.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{89}. The result of the @code{Task_Identification.Image}
|
|
attribute. See C.7.1(7).
|
|
@end cartouche
|
|
@noindent
|
|
The result of this attribute is a string that identifies
|
|
the object or component that denotes a given task. If a variable @code{Var}
|
|
has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}},
|
|
where the suffix
|
|
is the hexadecimal representation of the virtual address of the corresponding
|
|
task control block. If the variable is an array of tasks, the image of each
|
|
task will have the form of an indexed component indicating the position of a
|
|
given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a
|
|
component of a record, the image of the task will have the form of a selected
|
|
component. These rules are fully recursive, so that the image of a task that
|
|
is a subcomponent of a composite object corresponds to the expression that
|
|
designates this task.
|
|
@noindent
|
|
If a task is created by an allocator, its image depends on the context. If the
|
|
allocator is part of an object declaration, the rules described above are used
|
|
to construct its image, and this image is not affected by subsequent
|
|
assignments. If the allocator appears within an expression, the image
|
|
includes only the name of the task type.
|
|
@noindent
|
|
If the configuration pragma Discard_Names is present, or if the restriction
|
|
No_Implicit_Heap_Allocation is in effect, the image reduces to
|
|
the numeric suffix, that is to say the hexadecimal representation of the
|
|
virtual address of the control block of the task.
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{90}. The value of @code{Current_Task} when in a protected entry
|
|
or interrupt handler. See C.7.1(17).
|
|
@end cartouche
|
|
@noindent
|
|
Protected entries or interrupt handlers can be executed by any
|
|
convenient thread, so the value of @code{Current_Task} is undefined.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{91}. The effect of calling @code{Current_Task} from an entry
|
|
body or interrupt handler. See C.7.1(19).
|
|
@end cartouche
|
|
@noindent
|
|
The effect of calling @code{Current_Task} from an entry body or
|
|
interrupt handler is to return the identification of the task currently
|
|
executing the code.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{92}. Implementation-defined aspects of
|
|
@code{Task_Attributes}. See C.7.2(19).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined aspects of @code{Task_Attributes}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{93}. Values of all @code{Metrics}. See D(2).
|
|
@end cartouche
|
|
@noindent
|
|
The metrics information for GNAT depends on the performance of the
|
|
underlying operating system. The sources of the run-time for tasking
|
|
implementation, together with the output from @option{-gnatG} can be
|
|
used to determine the exact sequence of operating systems calls made
|
|
to implement various tasking constructs. Together with appropriate
|
|
information on the performance of the underlying operating system,
|
|
on the exact target in use, this information can be used to determine
|
|
the required metrics.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{94}. The declarations of @code{Any_Priority} and
|
|
@code{Priority}. See D.1(11).
|
|
@end cartouche
|
|
@noindent
|
|
See declarations in file @file{system.ads}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{95}. Implementation-defined execution resources. See D.1(15).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined execution resources.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{96}. Whether, on a multiprocessor, a task that is waiting for
|
|
access to a protected object keeps its processor busy. See D.2.1(3).
|
|
@end cartouche
|
|
@noindent
|
|
On a multi-processor, a task that is waiting for access to a protected
|
|
object does not keep its processor busy.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{97}. The affect of implementation defined execution resources
|
|
on task dispatching. See D.2.1(9).
|
|
@end cartouche
|
|
@noindent
|
|
@c SGI info
|
|
@ignore
|
|
Tasks map to IRIX threads, and the dispatching policy is as defined by
|
|
the IRIX implementation of threads.
|
|
@end ignore
|
|
Tasks map to threads in the threads package used by GNAT@. Where possible
|
|
and appropriate, these threads correspond to native threads of the
|
|
underlying operating system.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{98}. Implementation-defined @code{policy_identifiers} allowed
|
|
in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined policy-identifiers allowed in this
|
|
pragma.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{99}. Implementation-defined aspects of priority inversion. See
|
|
D.2.2(16).
|
|
@end cartouche
|
|
@noindent
|
|
Execution of a task cannot be preempted by the implementation processing
|
|
of delay expirations for lower priority tasks.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{100}. Implementation-defined task dispatching. See D.2.2(18).
|
|
@end cartouche
|
|
@noindent
|
|
@c SGI info:
|
|
@ignore
|
|
Tasks map to IRIX threads, and the dispatching policy is as defined by
|
|
the IRIX implementation of threads.
|
|
@end ignore
|
|
The policy is the same as that of the underlying threads implementation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{101}. Implementation-defined @code{policy_identifiers} allowed
|
|
in a pragma @code{Locking_Policy}. See D.3(4).
|
|
@end cartouche
|
|
@noindent
|
|
The two implementation defined policies permitted in GNAT are
|
|
@code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On
|
|
targets that support the @code{Inheritance_Locking} policy, locking is
|
|
implemented by inheritance, i.e.@: the task owning the lock operates
|
|
at a priority equal to the highest priority of any task currently
|
|
requesting the lock. On targets that support the
|
|
@code{Conccurent_Readers_Locking} policy, locking is implemented with a
|
|
read/write lock allowing multiple propected object functions to enter
|
|
concurrently.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{102}. Default ceiling priorities. See D.3(10).
|
|
@end cartouche
|
|
@noindent
|
|
The ceiling priority of protected objects of the type
|
|
@code{System.Interrupt_Priority'Last} as described in the Ada
|
|
Reference Manual D.3(10),
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{103}. The ceiling of any protected object used internally by
|
|
the implementation. See D.3(16).
|
|
@end cartouche
|
|
@noindent
|
|
The ceiling priority of internal protected objects is
|
|
@code{System.Priority'Last}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{104}. Implementation-defined queuing policies. See D.4(1).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined queuing policies.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{105}. On a multiprocessor, any conditions that cause the
|
|
completion of an aborted construct to be delayed later than what is
|
|
specified for a single processor. See D.6(3).
|
|
@end cartouche
|
|
@noindent
|
|
The semantics for abort on a multi-processor is the same as on a single
|
|
processor, there are no further delays.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{106}. Any operations that implicitly require heap storage
|
|
allocation. See D.7(8).
|
|
@end cartouche
|
|
@noindent
|
|
The only operation that implicitly requires heap storage allocation is
|
|
task creation.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{107}. Implementation-defined aspects of pragma
|
|
@code{Restrictions}. See D.7(20).
|
|
@end cartouche
|
|
@noindent
|
|
There are no such implementation-defined aspects.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{108}. Implementation-defined aspects of package
|
|
@code{Real_Time}. See D.8(17).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation defined aspects of package @code{Real_Time}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{109}. Implementation-defined aspects of
|
|
@code{delay_statements}. See D.9(8).
|
|
@end cartouche
|
|
@noindent
|
|
Any difference greater than one microsecond will cause the task to be
|
|
delayed (see D.9(7)).
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{110}. The upper bound on the duration of interrupt blocking
|
|
caused by the implementation. See D.12(5).
|
|
@end cartouche
|
|
@noindent
|
|
The upper bound is determined by the underlying operating system. In
|
|
no cases is it more than 10 milliseconds.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{111}. The means for creating and executing distributed
|
|
programs. See E(5).
|
|
@end cartouche
|
|
@noindent
|
|
The GLADE package provides a utility GNATDIST for creating and executing
|
|
distributed programs. See the GLADE reference manual for further details.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{112}. Any events that can result in a partition becoming
|
|
inaccessible. See E.1(7).
|
|
@end cartouche
|
|
@noindent
|
|
See the GLADE reference manual for full details on such events.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{113}. The scheduling policies, treatment of priorities, and
|
|
management of shared resources between partitions in certain cases. See
|
|
E.1(11).
|
|
@end cartouche
|
|
@noindent
|
|
See the GLADE reference manual for full details on these aspects of
|
|
multi-partition execution.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{114}. Events that cause the version of a compilation unit to
|
|
change. See E.3(5).
|
|
@end cartouche
|
|
@noindent
|
|
Editing the source file of a compilation unit, or the source files of
|
|
any units on which it is dependent in a significant way cause the version
|
|
to change. No other actions cause the version number to change. All changes
|
|
are significant except those which affect only layout, capitalization or
|
|
comments.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{115}. Whether the execution of the remote subprogram is
|
|
immediately aborted as a result of cancellation. See E.4(13).
|
|
@end cartouche
|
|
@noindent
|
|
See the GLADE reference manual for details on the effect of abort in
|
|
a distributed application.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{116}. Implementation-defined aspects of the PCS@. See E.5(25).
|
|
@end cartouche
|
|
@noindent
|
|
See the GLADE reference manual for a full description of all implementation
|
|
defined aspects of the PCS@.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{117}. Implementation-defined interfaces in the PCS@. See
|
|
E.5(26).
|
|
@end cartouche
|
|
@noindent
|
|
See the GLADE reference manual for a full description of all
|
|
implementation defined interfaces.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{118}. The values of named numbers in the package
|
|
@code{Decimal}. See F.2(7).
|
|
@end cartouche
|
|
@noindent
|
|
@table @code
|
|
@item Max_Scale
|
|
+18
|
|
@item Min_Scale
|
|
-18
|
|
@item Min_Delta
|
|
1.0E-18
|
|
@item Max_Delta
|
|
1.0E+18
|
|
@item Max_Decimal_Digits
|
|
18
|
|
@end table
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{119}. The value of @code{Max_Picture_Length} in the package
|
|
@code{Text_IO.Editing}. See F.3.3(16).
|
|
@end cartouche
|
|
@noindent
|
|
64
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{120}. The value of @code{Max_Picture_Length} in the package
|
|
@code{Wide_Text_IO.Editing}. See F.3.4(5).
|
|
@end cartouche
|
|
@noindent
|
|
64
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{121}. The accuracy actually achieved by the complex elementary
|
|
functions and by other complex arithmetic operations. See G.1(1).
|
|
@end cartouche
|
|
@noindent
|
|
Standard library functions are used for the complex arithmetic
|
|
operations. Only fast math mode is currently supported.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{122}. The sign of a zero result (or a component thereof) from
|
|
any operator or function in @code{Numerics.Generic_Complex_Types}, when
|
|
@code{Real'Signed_Zeros} is True. See G.1.1(53).
|
|
@end cartouche
|
|
@noindent
|
|
The signs of zero values are as recommended by the relevant
|
|
implementation advice.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{123}. The sign of a zero result (or a component thereof) from
|
|
any operator or function in
|
|
@code{Numerics.Generic_Complex_Elementary_Functions}, when
|
|
@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
|
|
@end cartouche
|
|
@noindent
|
|
The signs of zero values are as recommended by the relevant
|
|
implementation advice.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{124}. Whether the strict mode or the relaxed mode is the
|
|
default. See G.2(2).
|
|
@end cartouche
|
|
@noindent
|
|
The strict mode is the default. There is no separate relaxed mode. GNAT
|
|
provides a highly efficient implementation of strict mode.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{125}. The result interval in certain cases of fixed-to-float
|
|
conversion. See G.2.1(10).
|
|
@end cartouche
|
|
@noindent
|
|
For cases where the result interval is implementation dependent, the
|
|
accuracy is that provided by performing all operations in 64-bit IEEE
|
|
floating-point format.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{126}. The result of a floating point arithmetic operation in
|
|
overflow situations, when the @code{Machine_Overflows} attribute of the
|
|
result type is @code{False}. See G.2.1(13).
|
|
@end cartouche
|
|
@noindent
|
|
Infinite and NaN values are produced as dictated by the IEEE
|
|
floating-point standard.
|
|
|
|
Note that on machines that are not fully compliant with the IEEE
|
|
floating-point standard, such as Alpha, the @option{-mieee} compiler flag
|
|
must be used for achieving IEEE conforming behavior (although at the cost
|
|
of a significant performance penalty), so infinite and NaN values are
|
|
properly generated.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{127}. The result interval for division (or exponentiation by a
|
|
negative exponent), when the floating point hardware implements division
|
|
as multiplication by a reciprocal. See G.2.1(16).
|
|
@end cartouche
|
|
@noindent
|
|
Not relevant, division is IEEE exact.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{128}. The definition of close result set, which determines the
|
|
accuracy of certain fixed point multiplications and divisions. See
|
|
G.2.3(5).
|
|
@end cartouche
|
|
@noindent
|
|
Operations in the close result set are performed using IEEE long format
|
|
floating-point arithmetic. The input operands are converted to
|
|
floating-point, the operation is done in floating-point, and the result
|
|
is converted to the target type.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{129}. Conditions on a @code{universal_real} operand of a fixed
|
|
point multiplication or division for which the result shall be in the
|
|
perfect result set. See G.2.3(22).
|
|
@end cartouche
|
|
@noindent
|
|
The result is only defined to be in the perfect result set if the result
|
|
can be computed by a single scaling operation involving a scale factor
|
|
representable in 64-bits.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{130}. The result of a fixed point arithmetic operation in
|
|
overflow situations, when the @code{Machine_Overflows} attribute of the
|
|
result type is @code{False}. See G.2.3(27).
|
|
@end cartouche
|
|
@noindent
|
|
Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
|
|
types.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{131}. The result of an elementary function reference in
|
|
overflow situations, when the @code{Machine_Overflows} attribute of the
|
|
result type is @code{False}. See G.2.4(4).
|
|
@end cartouche
|
|
@noindent
|
|
IEEE infinite and Nan values are produced as appropriate.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{132}. The value of the angle threshold, within which certain
|
|
elementary functions, complex arithmetic operations, and complex
|
|
elementary functions yield results conforming to a maximum relative
|
|
error bound. See G.2.4(10).
|
|
@end cartouche
|
|
@noindent
|
|
Information on this subject is not yet available.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{133}. The accuracy of certain elementary functions for
|
|
parameters beyond the angle threshold. See G.2.4(10).
|
|
@end cartouche
|
|
@noindent
|
|
Information on this subject is not yet available.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{134}. The result of a complex arithmetic operation or complex
|
|
elementary function reference in overflow situations, when the
|
|
@code{Machine_Overflows} attribute of the corresponding real type is
|
|
@code{False}. See G.2.6(5).
|
|
@end cartouche
|
|
@noindent
|
|
IEEE infinite and Nan values are produced as appropriate.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{135}. The accuracy of certain complex arithmetic operations and
|
|
certain complex elementary functions for parameters (or components
|
|
thereof) beyond the angle threshold. See G.2.6(8).
|
|
@end cartouche
|
|
@noindent
|
|
Information on those subjects is not yet available.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{136}. Information regarding bounded errors and erroneous
|
|
execution. See H.2(1).
|
|
@end cartouche
|
|
@noindent
|
|
Information on this subject is not yet available.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{137}. Implementation-defined aspects of pragma
|
|
@code{Inspection_Point}. See H.3.2(8).
|
|
@end cartouche
|
|
@noindent
|
|
Pragma @code{Inspection_Point} ensures that the variable is live and can
|
|
be examined by the debugger at the inspection point.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{138}. Implementation-defined aspects of pragma
|
|
@code{Restrictions}. See H.4(25).
|
|
@end cartouche
|
|
@noindent
|
|
There are no implementation-defined aspects of pragma @code{Restrictions}. The
|
|
use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
|
|
generated code. Checks must suppressed by use of pragma @code{Suppress}.
|
|
|
|
@sp 1
|
|
@cartouche
|
|
@noindent
|
|
@strong{139}. Any restrictions on pragma @code{Restrictions}. See
|
|
H.4(27).
|
|
@end cartouche
|
|
@noindent
|
|
There are no restrictions on pragma @code{Restrictions}.
|
|
|
|
@node Intrinsic Subprograms
|
|
@chapter Intrinsic Subprograms
|
|
@cindex Intrinsic Subprograms
|
|
|
|
@menu
|
|
* Intrinsic Operators::
|
|
* Enclosing_Entity::
|
|
* Exception_Information::
|
|
* Exception_Message::
|
|
* Exception_Name::
|
|
* File::
|
|
* Line::
|
|
* Shifts and Rotates::
|
|
* Source_Location::
|
|
@end menu
|
|
|
|
@noindent
|
|
GNAT allows a user application program to write the declaration:
|
|
|
|
@smallexample @c ada
|
|
pragma Import (Intrinsic, name);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
providing that the name corresponds to one of the implemented intrinsic
|
|
subprograms in GNAT, and that the parameter profile of the referenced
|
|
subprogram meets the requirements. This chapter describes the set of
|
|
implemented intrinsic subprograms, and the requirements on parameter profiles.
|
|
Note that no body is supplied; as with other uses of pragma Import, the
|
|
body is supplied elsewhere (in this case by the compiler itself). Note
|
|
that any use of this feature is potentially non-portable, since the
|
|
Ada standard does not require Ada compilers to implement this feature.
|
|
|
|
@node Intrinsic Operators
|
|
@section Intrinsic Operators
|
|
@cindex Intrinsic operator
|
|
|
|
@noindent
|
|
All the predefined numeric operators in package Standard
|
|
in @code{pragma Import (Intrinsic,..)}
|
|
declarations. In the binary operator case, the operands must have the same
|
|
size. The operand or operands must also be appropriate for
|
|
the operator. For example, for addition, the operands must
|
|
both be floating-point or both be fixed-point, and the
|
|
right operand for @code{"**"} must have a root type of
|
|
@code{Standard.Integer'Base}.
|
|
You can use an intrinsic operator declaration as in the following example:
|
|
|
|
@smallexample @c ada
|
|
type Int1 is new Integer;
|
|
type Int2 is new Integer;
|
|
|
|
function "+" (X1 : Int1; X2 : Int2) return Int1;
|
|
function "+" (X1 : Int1; X2 : Int2) return Int2;
|
|
pragma Import (Intrinsic, "+");
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This declaration would permit ``mixed mode'' arithmetic on items
|
|
of the differing types @code{Int1} and @code{Int2}.
|
|
It is also possible to specify such operators for private types, if the
|
|
full views are appropriate arithmetic types.
|
|
|
|
@node Enclosing_Entity
|
|
@section Enclosing_Entity
|
|
@cindex Enclosing_Entity
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Source_Info}. The only useful use of the
|
|
intrinsic import in this case is the one in this unit, so an
|
|
application program should simply call the function
|
|
@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
|
|
the current subprogram, package, task, entry, or protected subprogram.
|
|
|
|
@node Exception_Information
|
|
@section Exception_Information
|
|
@cindex Exception_Information'
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Current_Exception}. The only useful
|
|
use of the intrinsic import in this case is the one in this unit,
|
|
so an application program should simply call the function
|
|
@code{GNAT.Current_Exception.Exception_Information} to obtain
|
|
the exception information associated with the current exception.
|
|
|
|
@node Exception_Message
|
|
@section Exception_Message
|
|
@cindex Exception_Message
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Current_Exception}. The only useful
|
|
use of the intrinsic import in this case is the one in this unit,
|
|
so an application program should simply call the function
|
|
@code{GNAT.Current_Exception.Exception_Message} to obtain
|
|
the message associated with the current exception.
|
|
|
|
@node Exception_Name
|
|
@section Exception_Name
|
|
@cindex Exception_Name
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Current_Exception}. The only useful
|
|
use of the intrinsic import in this case is the one in this unit,
|
|
so an application program should simply call the function
|
|
@code{GNAT.Current_Exception.Exception_Name} to obtain
|
|
the name of the current exception.
|
|
|
|
@node File
|
|
@section File
|
|
@cindex File
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Source_Info}. The only useful use of the
|
|
intrinsic import in this case is the one in this unit, so an
|
|
application program should simply call the function
|
|
@code{GNAT.Source_Info.File} to obtain the name of the current
|
|
file.
|
|
|
|
@node Line
|
|
@section Line
|
|
@cindex Line
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Source_Info}. The only useful use of the
|
|
intrinsic import in this case is the one in this unit, so an
|
|
application program should simply call the function
|
|
@code{GNAT.Source_Info.Line} to obtain the number of the current
|
|
source line.
|
|
|
|
@node Shifts and Rotates
|
|
@section Shifts and Rotates
|
|
@cindex Shift_Left
|
|
@cindex Shift_Right
|
|
@cindex Shift_Right_Arithmetic
|
|
@cindex Rotate_Left
|
|
@cindex Rotate_Right
|
|
@noindent
|
|
In standard Ada, the shift and rotate functions are available only
|
|
for the predefined modular types in package @code{Interfaces}. However, in
|
|
GNAT it is possible to define these functions for any integer
|
|
type (signed or modular), as in this example:
|
|
|
|
@smallexample @c ada
|
|
function Shift_Left
|
|
(Value : T;
|
|
Amount : Natural)
|
|
return T;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The function name must be one of
|
|
Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
|
|
Rotate_Right. T must be an integer type. T'Size must be
|
|
8, 16, 32 or 64 bits; if T is modular, the modulus
|
|
must be 2**8, 2**16, 2**32 or 2**64.
|
|
The result type must be the same as the type of @code{Value}.
|
|
The shift amount must be Natural.
|
|
The formal parameter names can be anything.
|
|
|
|
@node Source_Location
|
|
@section Source_Location
|
|
@cindex Source_Location
|
|
@noindent
|
|
This intrinsic subprogram is used in the implementation of the
|
|
library routine @code{GNAT.Source_Info}. The only useful use of the
|
|
intrinsic import in this case is the one in this unit, so an
|
|
application program should simply call the function
|
|
@code{GNAT.Source_Info.Source_Location} to obtain the current
|
|
source file location.
|
|
|
|
@node Representation Clauses and Pragmas
|
|
@chapter Representation Clauses and Pragmas
|
|
@cindex Representation Clauses
|
|
|
|
@menu
|
|
* Alignment Clauses::
|
|
* Size Clauses::
|
|
* Storage_Size Clauses::
|
|
* Size of Variant Record Objects::
|
|
* Biased Representation ::
|
|
* Value_Size and Object_Size Clauses::
|
|
* Component_Size Clauses::
|
|
* Bit_Order Clauses::
|
|
* Effect of Bit_Order on Byte Ordering::
|
|
* Pragma Pack for Arrays::
|
|
* Pragma Pack for Records::
|
|
* Record Representation Clauses::
|
|
* Enumeration Clauses::
|
|
* Address Clauses::
|
|
* Effect of Convention on Representation::
|
|
* Determining the Representations chosen by GNAT::
|
|
@end menu
|
|
|
|
@noindent
|
|
@cindex Representation Clause
|
|
@cindex Representation Pragma
|
|
@cindex Pragma, representation
|
|
This section describes the representation clauses accepted by GNAT, and
|
|
their effect on the representation of corresponding data objects.
|
|
|
|
GNAT fully implements Annex C (Systems Programming). This means that all
|
|
the implementation advice sections in chapter 13 are fully implemented.
|
|
However, these sections only require a minimal level of support for
|
|
representation clauses. GNAT provides much more extensive capabilities,
|
|
and this section describes the additional capabilities provided.
|
|
|
|
@node Alignment Clauses
|
|
@section Alignment Clauses
|
|
@cindex Alignment Clause
|
|
|
|
@noindent
|
|
GNAT requires that all alignment clauses specify a power of 2, and all
|
|
default alignments are always a power of 2. The default alignment
|
|
values are as follows:
|
|
|
|
@itemize @bullet
|
|
@item @emph{Primitive Types}.
|
|
For primitive types, the alignment is the minimum of the actual size of
|
|
objects of the type divided by @code{Storage_Unit},
|
|
and the maximum alignment supported by the target.
|
|
(This maximum alignment is given by the GNAT-specific attribute
|
|
@code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
|
|
@cindex @code{Maximum_Alignment} attribute
|
|
For example, for type @code{Long_Float}, the object size is 8 bytes, and the
|
|
default alignment will be 8 on any target that supports alignments
|
|
this large, but on some targets, the maximum alignment may be smaller
|
|
than 8, in which case objects of type @code{Long_Float} will be maximally
|
|
aligned.
|
|
|
|
@item @emph{Arrays}.
|
|
For arrays, the alignment is equal to the alignment of the component type
|
|
for the normal case where no packing or component size is given. If the
|
|
array is packed, and the packing is effective (see separate section on
|
|
packed arrays), then the alignment will be one for long packed arrays,
|
|
or arrays whose length is not known at compile time. For short packed
|
|
arrays, which are handled internally as modular types, the alignment
|
|
will be as described for primitive types, e.g.@: a packed array of length
|
|
31 bits will have an object size of four bytes, and an alignment of 4.
|
|
|
|
@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 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
|
|
@item
|
|
the size of the record is given explicitly, or a
|
|
full record representation clause is given, and
|
|
@item
|
|
the size of the record is 2, 4, or 8 bytes.
|
|
@end itemize
|
|
@noindent
|
|
In this case, an alignment is chosen to match the
|
|
size of the record. For example, if we have:
|
|
|
|
@smallexample @c ada
|
|
type Small is record
|
|
A, B : Character;
|
|
end record;
|
|
for Small'Size use 16;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then the default alignment of the record type @code{Small} is 2, not 1. This
|
|
leads to more efficient code when the record is treated as a unit, and also
|
|
allows the type to specified as @code{Atomic} on architectures requiring
|
|
strict alignment.
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
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 enumeration, integer and
|
|
fixed point types, as well as for record types, for example
|
|
|
|
@smallexample @c ada
|
|
type V is record
|
|
A : Integer;
|
|
end record;
|
|
|
|
for V'alignment use 1;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@cindex Alignment, default
|
|
The default alignment for the type @code{V} is 4, as a result of the
|
|
Integer field in the record, but it is permissible, as shown, to
|
|
override the default alignment of the record with a smaller value.
|
|
|
|
@cindex Alignment, subtypes
|
|
Note that according to the Ada standard, an alignment clause applies only
|
|
to the first named subtype. If additional subtypes are declared, then the
|
|
compiler is allowed to choose any alignment it likes, and there is no way
|
|
to control this choice. Consider:
|
|
|
|
@smallexample @c ada
|
|
type R is range 1 .. 10_000;
|
|
for R'Alignment use 1;
|
|
subtype RS is R range 1 .. 1000;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The alignment clause specifies an alignment of 1 for the first named subtype
|
|
@code{R} but this does not necessarily apply to @code{RS}. When writing
|
|
portable Ada code, you should avoid writing code that explicitly or
|
|
implicitly relies on the alignment of such subtypes.
|
|
|
|
For the GNAT compiler, if an explicit alignment clause is given, this
|
|
value is also used for any subsequent subtypes. So for GNAT, in the
|
|
above example, you can count on the alignment of @code{RS} being 1. But this
|
|
assumption is non-portable, and other compilers may choose different
|
|
alignments for the subtype @code{RS}.
|
|
|
|
@node Size Clauses
|
|
@section Size Clauses
|
|
@cindex Size Clause
|
|
|
|
@noindent
|
|
The default size for a type @code{T} is obtainable through the
|
|
language-defined attribute @code{T'Size} and also through the
|
|
equivalent GNAT-defined attribute @code{T'Value_Size}.
|
|
For objects of type @code{T}, GNAT will generally increase the type size
|
|
so that the object size (obtainable through the GNAT-defined attribute
|
|
@code{T'Object_Size})
|
|
is a multiple of @code{T'Alignment * Storage_Unit}.
|
|
For example
|
|
|
|
@smallexample @c ada
|
|
type Smallint is range 1 .. 6;
|
|
|
|
type Rec is record
|
|
Y1 : integer;
|
|
Y2 : boolean;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
|
|
as specified by the RM rules,
|
|
but objects of this type will have a size of 8
|
|
(@code{Smallint'Object_Size} = 8),
|
|
since objects by default occupy an integral number
|
|
of storage units. On some targets, notably older
|
|
versions of the Digital Alpha, the size of stand
|
|
alone objects of this type may be 32, reflecting
|
|
the inability of the hardware to do byte load/stores.
|
|
|
|
Similarly, the size of type @code{Rec} is 40 bits
|
|
(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
|
|
the alignment is 4, so objects of this type will have
|
|
their size increased to 64 bits so that it is a multiple
|
|
of the alignment (in bits). This decision is
|
|
in accordance with the specific Implementation Advice in RM 13.3(43):
|
|
|
|
@quotation
|
|
A @code{Size} clause should be supported for an object if the specified
|
|
@code{Size} is at least as large as its subtype's @code{Size}, and corresponds
|
|
to a size in storage elements that is a multiple of the object's
|
|
@code{Alignment} (if the @code{Alignment} is nonzero).
|
|
@end quotation
|
|
|
|
@noindent
|
|
An explicit size clause may be used to override the default size by
|
|
increasing it. For example, if we have:
|
|
|
|
@smallexample @c ada
|
|
type My_Boolean is new Boolean;
|
|
for My_Boolean'Size use 32;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then values of this type will always be 32 bits long. In the case of
|
|
discrete types, the size can be increased up to 64 bits, with the effect
|
|
that the entire specified field is used to hold the value, sign- or
|
|
zero-extended as appropriate. If more than 64 bits is specified, then
|
|
padding space is allocated after the value, and a warning is issued that
|
|
there are unused bits.
|
|
|
|
Similarly the size of records and arrays may be increased, and the effect
|
|
is to add padding bits after the value. This also causes a warning message
|
|
to be generated.
|
|
|
|
The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
|
|
Size in bits, this corresponds to an object of size 256 megabytes (minus
|
|
one). This limitation is true on all targets. The reason for this
|
|
limitation is that it improves the quality of the code in many cases
|
|
if it is known that a Size value can be accommodated in an object of
|
|
type Integer.
|
|
|
|
@node Storage_Size Clauses
|
|
@section Storage_Size Clauses
|
|
@cindex Storage_Size Clause
|
|
|
|
@noindent
|
|
For tasks, the @code{Storage_Size} clause specifies the amount of space
|
|
to be allocated for the task stack. This cannot be extended, and if the
|
|
stack is exhausted, then @code{Storage_Error} will be raised (if stack
|
|
checking is enabled). Use a @code{Storage_Size} attribute definition clause,
|
|
or a @code{Storage_Size} pragma in the task definition to set the
|
|
appropriate required size. A useful technique is to include in every
|
|
task definition a pragma of the form:
|
|
|
|
@smallexample @c ada
|
|
pragma Storage_Size (Default_Stack_Size);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Then @code{Default_Stack_Size} can be defined in a global package, and
|
|
modified as required. Any tasks requiring stack sizes different from the
|
|
default can have an appropriate alternative reference in the pragma.
|
|
|
|
You can also use the @option{-d} binder switch to modify the default stack
|
|
size.
|
|
|
|
For access types, the @code{Storage_Size} clause specifies the maximum
|
|
space available for allocation of objects of the type. If this space is
|
|
exceeded then @code{Storage_Error} will be raised by an allocation attempt.
|
|
In the case where the access type is declared local to a subprogram, the
|
|
use of a @code{Storage_Size} clause triggers automatic use of a special
|
|
predefined storage pool (@code{System.Pool_Size}) that ensures that all
|
|
space for the pool is automatically reclaimed on exit from the scope in
|
|
which the type is declared.
|
|
|
|
A special case recognized by the compiler is the specification of a
|
|
@code{Storage_Size} of zero for an access type. This means that no
|
|
items can be allocated from the pool, and this is recognized at compile
|
|
time, and all the overhead normally associated with maintaining a fixed
|
|
size storage pool is eliminated. Consider the following example:
|
|
|
|
@smallexample @c ada
|
|
procedure p is
|
|
type R is array (Natural) of Character;
|
|
type P is access all R;
|
|
for P'Storage_Size use 0;
|
|
-- Above access type intended only for interfacing purposes
|
|
|
|
y : P;
|
|
|
|
procedure g (m : P);
|
|
pragma Import (C, g);
|
|
|
|
-- @dots{}
|
|
|
|
begin
|
|
-- @dots{}
|
|
y := new R;
|
|
end;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
As indicated in this example, these dummy storage pools are often useful in
|
|
connection with interfacing where no object will ever be allocated. If you
|
|
compile the above example, you get the warning:
|
|
|
|
@smallexample
|
|
p.adb:16:09: warning: allocation from empty storage pool
|
|
p.adb:16:09: warning: Storage_Error will be raised at run time
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Of course in practice, there will not be any explicit allocators in the
|
|
case of such an access declaration.
|
|
|
|
@node Size of Variant Record Objects
|
|
@section Size of Variant Record Objects
|
|
@cindex Size, variant record objects
|
|
@cindex Variant record objects, size
|
|
|
|
@noindent
|
|
In the case of variant record objects, there is a question whether Size gives
|
|
information about a particular variant, or the maximum size required
|
|
for any variant. Consider the following program
|
|
|
|
@smallexample @c ada
|
|
with Text_IO; use Text_IO;
|
|
procedure q is
|
|
type R1 (A : Boolean := False) is record
|
|
case A is
|
|
when True => X : Character;
|
|
when False => null;
|
|
end case;
|
|
end record;
|
|
|
|
V1 : R1 (False);
|
|
V2 : R1;
|
|
|
|
begin
|
|
Put_Line (Integer'Image (V1'Size));
|
|
Put_Line (Integer'Image (V2'Size));
|
|
end q;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here we are dealing with a variant record, where the True variant
|
|
requires 16 bits, and the False variant requires 8 bits.
|
|
In the above example, both V1 and V2 contain the False variant,
|
|
which is only 8 bits long. However, the result of running the
|
|
program is:
|
|
|
|
@smallexample
|
|
8
|
|
16
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The reason for the difference here is that the discriminant value of
|
|
V1 is fixed, and will always be False. It is not possible to assign
|
|
a True variant value to V1, therefore 8 bits is sufficient. On the
|
|
other hand, in the case of V2, the initial discriminant value is
|
|
False (from the default), but it is possible to assign a True
|
|
variant value to V2, therefore 16 bits must be allocated for V2
|
|
in the general case, even fewer bits may be needed at any particular
|
|
point during the program execution.
|
|
|
|
As can be seen from the output of this program, the @code{'Size}
|
|
attribute applied to such an object in GNAT gives the actual allocated
|
|
size of the variable, which is the largest size of any of the variants.
|
|
The Ada Reference Manual is not completely clear on what choice should
|
|
be made here, but the GNAT behavior seems most consistent with the
|
|
language in the RM@.
|
|
|
|
In some cases, it may be desirable to obtain the size of the current
|
|
variant, rather than the size of the largest variant. This can be
|
|
achieved in GNAT by making use of the fact that in the case of a
|
|
subprogram parameter, GNAT does indeed return the size of the current
|
|
variant (because a subprogram has no way of knowing how much space
|
|
is actually allocated for the actual).
|
|
|
|
Consider the following modified version of the above program:
|
|
|
|
@smallexample @c ada
|
|
with Text_IO; use Text_IO;
|
|
procedure q is
|
|
type R1 (A : Boolean := False) is record
|
|
case A is
|
|
when True => X : Character;
|
|
when False => null;
|
|
end case;
|
|
end record;
|
|
|
|
V2 : R1;
|
|
|
|
function Size (V : R1) return Integer is
|
|
begin
|
|
return V'Size;
|
|
end Size;
|
|
|
|
begin
|
|
Put_Line (Integer'Image (V2'Size));
|
|
Put_Line (Integer'IMage (Size (V2)));
|
|
V2 := (True, 'x');
|
|
Put_Line (Integer'Image (V2'Size));
|
|
Put_Line (Integer'IMage (Size (V2)));
|
|
end q;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The output from this program is
|
|
|
|
@smallexample
|
|
16
|
|
8
|
|
16
|
|
16
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here we see that while the @code{'Size} attribute always returns
|
|
the maximum size, regardless of the current variant value, the
|
|
@code{Size} function does indeed return the size of the current
|
|
variant value.
|
|
|
|
@node Biased Representation
|
|
@section Biased Representation
|
|
@cindex Size for biased representation
|
|
@cindex Biased representation
|
|
|
|
@noindent
|
|
In the case of scalars with a range starting at other than zero, it is
|
|
possible in some cases to specify a size smaller than the default minimum
|
|
value, and in such cases, GNAT uses an unsigned biased representation,
|
|
in which zero is used to represent the lower bound, and successive values
|
|
represent successive values of the type.
|
|
|
|
For example, suppose we have the declaration:
|
|
|
|
@smallexample @c ada
|
|
type Small is range -7 .. -4;
|
|
for Small'Size use 2;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Although the default size of type @code{Small} is 4, the @code{Size}
|
|
clause is accepted by GNAT and results in the following representation
|
|
scheme:
|
|
|
|
@smallexample
|
|
-7 is represented as 2#00#
|
|
-6 is represented as 2#01#
|
|
-5 is represented as 2#10#
|
|
-4 is represented as 2#11#
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Biased representation is only used if the specified @code{Size} clause
|
|
cannot be accepted in any other manner. These reduced sizes that force
|
|
biased representation can be used for all discrete types except for
|
|
enumeration types for which a representation clause is given.
|
|
|
|
@node Value_Size and Object_Size Clauses
|
|
@section Value_Size and Object_Size Clauses
|
|
@findex Value_Size
|
|
@findex Object_Size
|
|
@cindex Size, of objects
|
|
|
|
@noindent
|
|
In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
|
|
number of bits required to hold values of type @code{T}.
|
|
Although this interpretation was allowed in Ada 83, it was not required,
|
|
and this requirement in practice can cause some significant difficulties.
|
|
For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
|
|
However, in Ada 95 and Ada 2005,
|
|
@code{Natural'Size} is
|
|
typically 31. This means that code may change in behavior when moving
|
|
from Ada 83 to Ada 95 or Ada 2005. For example, consider:
|
|
|
|
@smallexample @c ada
|
|
type Rec is record;
|
|
A : Natural;
|
|
B : Natural;
|
|
end record;
|
|
|
|
for Rec use record
|
|
at 0 range 0 .. Natural'Size - 1;
|
|
at 0 range Natural'Size .. 2 * Natural'Size - 1;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In the above code, since the typical size of @code{Natural} objects
|
|
is 32 bits and @code{Natural'Size} is 31, the above code can cause
|
|
unexpected inefficient packing in Ada 95 and Ada 2005, and in general
|
|
there are cases where the fact that the object size can exceed the
|
|
size of the type causes surprises.
|
|
|
|
To help get around this problem GNAT provides two implementation
|
|
defined attributes, @code{Value_Size} and @code{Object_Size}. When
|
|
applied to a type, these attributes yield the size of the type
|
|
(corresponding to the RM defined size attribute), and the size of
|
|
objects of the type respectively.
|
|
|
|
The @code{Object_Size} is used for determining the default size of
|
|
objects and components. This size value can be referred to using the
|
|
@code{Object_Size} attribute. The phrase ``is used'' here means that it is
|
|
the basis of the determination of the size. The backend is free to
|
|
pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
|
|
character might be stored in 32 bits on a machine with no efficient
|
|
byte access instructions such as the Alpha.
|
|
|
|
The default rules for the value of @code{Object_Size} for
|
|
discrete types are as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @code{Object_Size} for base subtypes reflect the natural hardware
|
|
size in bits (run the compiler with @option{-gnatS} to find those values
|
|
for numeric types). Enumeration types and fixed-point base subtypes have
|
|
8, 16, 32 or 64 bits for this size, depending on the range of values
|
|
to be stored.
|
|
|
|
@item
|
|
The @code{Object_Size} of a subtype is the same as the
|
|
@code{Object_Size} of
|
|
the type from which it is obtained.
|
|
|
|
@item
|
|
The @code{Object_Size} of a derived base type is copied from the parent
|
|
base type, and the @code{Object_Size} of a derived first subtype is copied
|
|
from the parent first subtype.
|
|
@end itemize
|
|
|
|
@noindent
|
|
The @code{Value_Size} attribute
|
|
is the (minimum) number of bits required to store a value
|
|
of the type.
|
|
This value is used to determine how tightly to pack
|
|
records or arrays with components of this type, and also affects
|
|
the semantics of unchecked conversion (unchecked conversions where
|
|
the @code{Value_Size} values differ generate a warning, and are potentially
|
|
target dependent).
|
|
|
|
The default rules for the value of @code{Value_Size} are as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @code{Value_Size} for a base subtype is the minimum number of bits
|
|
required to store all values of the type (including the sign bit
|
|
only if negative values are possible).
|
|
|
|
@item
|
|
If a subtype statically matches the first subtype of a given type, then it has
|
|
by default the same @code{Value_Size} as the first subtype. This is a
|
|
consequence of RM 13.1(14) (``if two subtypes statically match,
|
|
then their subtype-specific aspects are the same''.)
|
|
|
|
@item
|
|
All other subtypes have a @code{Value_Size} corresponding to the minimum
|
|
number of bits required to store all values of the subtype. For
|
|
dynamic bounds, it is assumed that the value can range down or up
|
|
to the corresponding bound of the ancestor
|
|
@end itemize
|
|
|
|
@noindent
|
|
The RM defined attribute @code{Size} corresponds to the
|
|
@code{Value_Size} attribute.
|
|
|
|
The @code{Size} attribute may be defined for a first-named subtype. This sets
|
|
the @code{Value_Size} of
|
|
the first-named subtype to the given value, and the
|
|
@code{Object_Size} of this first-named subtype to the given value padded up
|
|
to an appropriate boundary. It is a consequence of the default rules
|
|
above that this @code{Object_Size} will apply to all further subtypes. On the
|
|
other hand, @code{Value_Size} is affected only for the first subtype, any
|
|
dynamic subtypes obtained from it directly, and any statically matching
|
|
subtypes. The @code{Value_Size} of any other static subtypes is not affected.
|
|
|
|
@code{Value_Size} and
|
|
@code{Object_Size} may be explicitly set for any subtype using
|
|
an attribute definition clause. Note that the use of these attributes
|
|
can cause the RM 13.1(14) rule to be violated. If two access types
|
|
reference aliased objects whose subtypes have differing @code{Object_Size}
|
|
values as a result of explicit attribute definition clauses, then it
|
|
is erroneous to convert from one access subtype to the other.
|
|
|
|
At the implementation level, Esize stores the Object_Size and the
|
|
RM_Size field stores the @code{Value_Size} (and hence the value of the
|
|
@code{Size} attribute,
|
|
which, as noted above, is equivalent to @code{Value_Size}).
|
|
|
|
To get a feel for the difference, consider the following examples (note
|
|
that in each case the base is @code{Short_Short_Integer} with a size of 8):
|
|
|
|
@smallexample
|
|
Object_Size Value_Size
|
|
|
|
type x1 is range 0 .. 5; 8 3
|
|
|
|
type x2 is range 0 .. 5;
|
|
for x2'size use 12; 16 12
|
|
|
|
subtype x3 is x2 range 0 .. 3; 16 2
|
|
|
|
subtype x4 is x2'base range 0 .. 10; 8 4
|
|
|
|
subtype x5 is x2 range 0 .. dynamic; 16 3*
|
|
|
|
subtype x6 is x2'base range 0 .. dynamic; 8 3*
|
|
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note: the entries marked ``3*'' are not actually specified by the Ada
|
|
Reference Manual, but it seems in the spirit of the RM rules to allocate
|
|
the minimum number of bits (here 3, given the range for @code{x2})
|
|
known to be large enough to hold the given range of values.
|
|
|
|
So far, so good, but GNAT has to obey the RM rules, so the question is
|
|
under what conditions must the RM @code{Size} be used.
|
|
The following is a list
|
|
of the occasions on which the RM @code{Size} must be used:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Component size for packed arrays or records
|
|
|
|
@item
|
|
Value of the attribute @code{Size} for a type
|
|
|
|
@item
|
|
Warning about sizes not matching for unchecked conversion
|
|
@end itemize
|
|
|
|
@noindent
|
|
For record types, the @code{Object_Size} is always a multiple of the
|
|
alignment of the type (this is true for all types). In some cases the
|
|
@code{Value_Size} can be smaller. Consider:
|
|
|
|
@smallexample
|
|
type R is record
|
|
X : Integer;
|
|
Y : Character;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
On a typical 32-bit architecture, the X component will be four bytes, and
|
|
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 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).
|
|
|
|
@noindent
|
|
For all other types, the @code{Object_Size}
|
|
and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
|
|
Only @code{Size} may be specified for such types.
|
|
|
|
@node Component_Size Clauses
|
|
@section Component_Size Clauses
|
|
@cindex Component_Size Clause
|
|
|
|
@noindent
|
|
Normally, the value specified in a component size clause must be consistent
|
|
with the subtype of the array component with regard to size and alignment.
|
|
In other words, the value specified must be at least equal to the size
|
|
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. 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;
|
|
for r'Component_Size use 31;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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
|
|
clauses are given, the pragma Pack will be ignored.
|
|
|
|
@node Bit_Order Clauses
|
|
@section Bit_Order Clauses
|
|
@cindex Bit_Order Clause
|
|
@cindex bit ordering
|
|
@cindex ordering, of bits
|
|
|
|
@noindent
|
|
For record subtypes, GNAT permits the specification of the @code{Bit_Order}
|
|
attribute. The specification may either correspond to the default bit
|
|
order for the target, in which case the specification has no effect and
|
|
places no additional restrictions, or it may be for the non-standard
|
|
setting (that is the opposite of the default).
|
|
|
|
In the case where the non-standard value is specified, the effect is
|
|
to renumber bits within each byte, but the ordering of bytes is not
|
|
affected. There are certain
|
|
restrictions placed on component clauses as follows:
|
|
|
|
@itemize @bullet
|
|
|
|
@item Components fitting within a single storage unit.
|
|
@noindent
|
|
These are unrestricted, and the effect is merely to renumber bits. For
|
|
example if we are on a little-endian machine with @code{Low_Order_First}
|
|
being the default, then the following two declarations have exactly
|
|
the same effect:
|
|
|
|
@smallexample @c ada
|
|
type R1 is record
|
|
A : Boolean;
|
|
B : Integer range 1 .. 120;
|
|
end record;
|
|
|
|
for R1 use record
|
|
A at 0 range 0 .. 0;
|
|
B at 0 range 1 .. 7;
|
|
end record;
|
|
|
|
type R2 is record
|
|
A : Boolean;
|
|
B : Integer range 1 .. 120;
|
|
end record;
|
|
|
|
for R2'Bit_Order use High_Order_First;
|
|
|
|
for R2 use record
|
|
A at 0 range 7 .. 7;
|
|
B at 0 range 0 .. 6;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The useful application here is to write the second declaration with the
|
|
@code{Bit_Order} attribute definition clause, and know that it will be treated
|
|
the same, regardless of whether the target is little-endian or big-endian.
|
|
|
|
@item Components occupying an integral number of bytes.
|
|
@noindent
|
|
These are components that exactly fit in two or more bytes. Such component
|
|
declarations are allowed, but have no effect, since it is important to realize
|
|
that the @code{Bit_Order} specification does not affect the ordering of bytes.
|
|
In particular, the following attempt at getting an endian-independent integer
|
|
does not work:
|
|
|
|
@smallexample @c ada
|
|
type R2 is record
|
|
A : Integer;
|
|
end record;
|
|
|
|
for R2'Bit_Order use High_Order_First;
|
|
|
|
for R2 use record
|
|
A at 0 range 0 .. 31;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This declaration will result in a little-endian integer on a
|
|
little-endian machine, and a big-endian integer on a big-endian machine.
|
|
If byte flipping is required for interoperability between big- and
|
|
little-endian machines, this must be explicitly programmed. This capability
|
|
is not provided by @code{Bit_Order}.
|
|
|
|
@item Components that are positioned across byte boundaries
|
|
@noindent
|
|
but do not occupy an integral number of bytes. Given that bytes are not
|
|
reordered, such fields would occupy a non-contiguous sequence of bits
|
|
in memory, requiring non-trivial code to reassemble. They are for this
|
|
reason not permitted, and any component clause specifying such a layout
|
|
will be flagged as illegal by GNAT@.
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
Since the misconception that Bit_Order automatically deals with all
|
|
endian-related incompatibilities is a common one, the specification of
|
|
a component field that is an integral number of bytes will always
|
|
generate a warning. This warning may be suppressed using @code{pragma
|
|
Warnings (Off)} if desired. The following section contains additional
|
|
details regarding the issue of byte ordering.
|
|
|
|
@node Effect of Bit_Order on Byte Ordering
|
|
@section Effect of Bit_Order on Byte Ordering
|
|
@cindex byte ordering
|
|
@cindex ordering, of bytes
|
|
|
|
@noindent
|
|
In this section we will review the effect of the @code{Bit_Order} attribute
|
|
definition clause on byte ordering. Briefly, it has no effect at all, but
|
|
a detailed example will be helpful. Before giving this
|
|
example, let us review the precise
|
|
definition of the effect of defining @code{Bit_Order}. The effect of a
|
|
non-standard bit order is described in section 15.5.3 of the Ada
|
|
Reference Manual:
|
|
|
|
@quotation
|
|
2 A bit ordering is a method of interpreting the meaning of
|
|
the storage place attributes.
|
|
@end quotation
|
|
|
|
@noindent
|
|
To understand the precise definition of storage place attributes in
|
|
this context, we visit section 13.5.1 of the manual:
|
|
|
|
@quotation
|
|
13 A record_representation_clause (without the mod_clause)
|
|
specifies the layout. The storage place attributes (see 13.5.2)
|
|
are taken from the values of the position, first_bit, and last_bit
|
|
expressions after normalizing those values so that first_bit is
|
|
less than Storage_Unit.
|
|
@end quotation
|
|
|
|
@noindent
|
|
The critical point here is that storage places are taken from
|
|
the values after normalization, not before. So the @code{Bit_Order}
|
|
interpretation applies to normalized values. The interpretation
|
|
is described in the later part of the 15.5.3 paragraph:
|
|
|
|
@quotation
|
|
2 A bit ordering is a method of interpreting the meaning of
|
|
the storage place attributes. High_Order_First (known in the
|
|
vernacular as ``big endian'') means that the first bit of a
|
|
storage element (bit 0) is the most significant bit (interpreting
|
|
the sequence of bits that represent a component as an unsigned
|
|
integer value). Low_Order_First (known in the vernacular as
|
|
``little endian'') means the opposite: the first bit is the
|
|
least significant.
|
|
@end quotation
|
|
|
|
@noindent
|
|
Note that the numbering is with respect to the bits of a storage
|
|
unit. In other words, the specification affects only the numbering
|
|
of bits within a single storage unit.
|
|
|
|
We can make the effect clearer by giving an example.
|
|
|
|
Suppose that we have an external device which presents two bytes, the first
|
|
byte presented, which is the first (low addressed byte) of the two byte
|
|
record is called Master, and the second byte is called Slave.
|
|
|
|
The left most (most significant bit is called Control for each byte, and
|
|
the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
|
|
(least significant) bit.
|
|
|
|
On a big-endian machine, we can write the following representation clause
|
|
|
|
@smallexample @c ada
|
|
type Data is record
|
|
Master_Control : Bit;
|
|
Master_V1 : Bit;
|
|
Master_V2 : Bit;
|
|
Master_V3 : Bit;
|
|
Master_V4 : Bit;
|
|
Master_V5 : Bit;
|
|
Master_V6 : Bit;
|
|
Master_V7 : Bit;
|
|
Slave_Control : Bit;
|
|
Slave_V1 : Bit;
|
|
Slave_V2 : Bit;
|
|
Slave_V3 : Bit;
|
|
Slave_V4 : Bit;
|
|
Slave_V5 : Bit;
|
|
Slave_V6 : Bit;
|
|
Slave_V7 : Bit;
|
|
end record;
|
|
|
|
for Data use record
|
|
Master_Control at 0 range 0 .. 0;
|
|
Master_V1 at 0 range 1 .. 1;
|
|
Master_V2 at 0 range 2 .. 2;
|
|
Master_V3 at 0 range 3 .. 3;
|
|
Master_V4 at 0 range 4 .. 4;
|
|
Master_V5 at 0 range 5 .. 5;
|
|
Master_V6 at 0 range 6 .. 6;
|
|
Master_V7 at 0 range 7 .. 7;
|
|
Slave_Control at 1 range 0 .. 0;
|
|
Slave_V1 at 1 range 1 .. 1;
|
|
Slave_V2 at 1 range 2 .. 2;
|
|
Slave_V3 at 1 range 3 .. 3;
|
|
Slave_V4 at 1 range 4 .. 4;
|
|
Slave_V5 at 1 range 5 .. 5;
|
|
Slave_V6 at 1 range 6 .. 6;
|
|
Slave_V7 at 1 range 7 .. 7;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Now if we move this to a little endian machine, then the bit ordering within
|
|
the byte is backwards, so we have to rewrite the record rep clause as:
|
|
|
|
@smallexample @c ada
|
|
for Data use record
|
|
Master_Control at 0 range 7 .. 7;
|
|
Master_V1 at 0 range 6 .. 6;
|
|
Master_V2 at 0 range 5 .. 5;
|
|
Master_V3 at 0 range 4 .. 4;
|
|
Master_V4 at 0 range 3 .. 3;
|
|
Master_V5 at 0 range 2 .. 2;
|
|
Master_V6 at 0 range 1 .. 1;
|
|
Master_V7 at 0 range 0 .. 0;
|
|
Slave_Control at 1 range 7 .. 7;
|
|
Slave_V1 at 1 range 6 .. 6;
|
|
Slave_V2 at 1 range 5 .. 5;
|
|
Slave_V3 at 1 range 4 .. 4;
|
|
Slave_V4 at 1 range 3 .. 3;
|
|
Slave_V5 at 1 range 2 .. 2;
|
|
Slave_V6 at 1 range 1 .. 1;
|
|
Slave_V7 at 1 range 0 .. 0;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
It is a nuisance to have to rewrite the clause, especially if
|
|
the code has to be maintained on both machines. However,
|
|
this is a case that we can handle with the
|
|
@code{Bit_Order} attribute if it is implemented.
|
|
Note that the implementation is not required on byte addressed
|
|
machines, but it is indeed implemented in GNAT.
|
|
This means that we can simply use the
|
|
first record clause, together with the declaration
|
|
|
|
@smallexample @c ada
|
|
for Data'Bit_Order use High_Order_First;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and the effect is what is desired, namely the layout is exactly the same,
|
|
independent of whether the code is compiled on a big-endian or little-endian
|
|
machine.
|
|
|
|
The important point to understand is that byte ordering is not affected.
|
|
A @code{Bit_Order} attribute definition never affects which byte a field
|
|
ends up in, only where it ends up in that byte.
|
|
To make this clear, let us rewrite the record rep clause of the previous
|
|
example as:
|
|
|
|
@smallexample @c ada
|
|
for Data'Bit_Order use High_Order_First;
|
|
for Data use record
|
|
Master_Control at 0 range 0 .. 0;
|
|
Master_V1 at 0 range 1 .. 1;
|
|
Master_V2 at 0 range 2 .. 2;
|
|
Master_V3 at 0 range 3 .. 3;
|
|
Master_V4 at 0 range 4 .. 4;
|
|
Master_V5 at 0 range 5 .. 5;
|
|
Master_V6 at 0 range 6 .. 6;
|
|
Master_V7 at 0 range 7 .. 7;
|
|
Slave_Control at 0 range 8 .. 8;
|
|
Slave_V1 at 0 range 9 .. 9;
|
|
Slave_V2 at 0 range 10 .. 10;
|
|
Slave_V3 at 0 range 11 .. 11;
|
|
Slave_V4 at 0 range 12 .. 12;
|
|
Slave_V5 at 0 range 13 .. 13;
|
|
Slave_V6 at 0 range 14 .. 14;
|
|
Slave_V7 at 0 range 15 .. 15;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is exactly equivalent to saying (a repeat of the first example):
|
|
|
|
@smallexample @c ada
|
|
for Data'Bit_Order use High_Order_First;
|
|
for Data use record
|
|
Master_Control at 0 range 0 .. 0;
|
|
Master_V1 at 0 range 1 .. 1;
|
|
Master_V2 at 0 range 2 .. 2;
|
|
Master_V3 at 0 range 3 .. 3;
|
|
Master_V4 at 0 range 4 .. 4;
|
|
Master_V5 at 0 range 5 .. 5;
|
|
Master_V6 at 0 range 6 .. 6;
|
|
Master_V7 at 0 range 7 .. 7;
|
|
Slave_Control at 1 range 0 .. 0;
|
|
Slave_V1 at 1 range 1 .. 1;
|
|
Slave_V2 at 1 range 2 .. 2;
|
|
Slave_V3 at 1 range 3 .. 3;
|
|
Slave_V4 at 1 range 4 .. 4;
|
|
Slave_V5 at 1 range 5 .. 5;
|
|
Slave_V6 at 1 range 6 .. 6;
|
|
Slave_V7 at 1 range 7 .. 7;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Why are they equivalent? Well take a specific field, the @code{Slave_V2}
|
|
field. The storage place attributes are obtained by normalizing the
|
|
values given so that the @code{First_Bit} value is less than 8. After
|
|
normalizing the values (0,10,10) we get (1,2,2) which is exactly what
|
|
we specified in the other case.
|
|
|
|
Now one might expect that the @code{Bit_Order} attribute might affect
|
|
bit numbering within the entire record component (two bytes in this
|
|
case, thus affecting which byte fields end up in), but that is not
|
|
the way this feature is defined, it only affects numbering of bits,
|
|
not which byte they end up in.
|
|
|
|
Consequently it never makes sense to specify a starting bit number
|
|
greater than 7 (for a byte addressable field) if an attribute
|
|
definition for @code{Bit_Order} has been given, and indeed it
|
|
may be actively confusing to specify such a value, so the compiler
|
|
generates a warning for such usage.
|
|
|
|
If you do need to control byte ordering then appropriate conditional
|
|
values must be used. If in our example, the slave byte came first on
|
|
some machines we might write:
|
|
|
|
@smallexample @c ada
|
|
Master_Byte_First constant Boolean := @dots{};
|
|
|
|
Master_Byte : constant Natural :=
|
|
1 - Boolean'Pos (Master_Byte_First);
|
|
Slave_Byte : constant Natural :=
|
|
Boolean'Pos (Master_Byte_First);
|
|
|
|
for Data'Bit_Order use High_Order_First;
|
|
for Data use record
|
|
Master_Control at Master_Byte range 0 .. 0;
|
|
Master_V1 at Master_Byte range 1 .. 1;
|
|
Master_V2 at Master_Byte range 2 .. 2;
|
|
Master_V3 at Master_Byte range 3 .. 3;
|
|
Master_V4 at Master_Byte range 4 .. 4;
|
|
Master_V5 at Master_Byte range 5 .. 5;
|
|
Master_V6 at Master_Byte range 6 .. 6;
|
|
Master_V7 at Master_Byte range 7 .. 7;
|
|
Slave_Control at Slave_Byte range 0 .. 0;
|
|
Slave_V1 at Slave_Byte range 1 .. 1;
|
|
Slave_V2 at Slave_Byte range 2 .. 2;
|
|
Slave_V3 at Slave_Byte range 3 .. 3;
|
|
Slave_V4 at Slave_Byte range 4 .. 4;
|
|
Slave_V5 at Slave_Byte range 5 .. 5;
|
|
Slave_V6 at Slave_Byte range 6 .. 6;
|
|
Slave_V7 at Slave_Byte range 7 .. 7;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Now to switch between machines, all that is necessary is
|
|
to set the boolean constant @code{Master_Byte_First} in
|
|
an appropriate manner.
|
|
|
|
@node Pragma Pack for Arrays
|
|
@section Pragma Pack for Arrays
|
|
@cindex Pragma Pack (for arrays)
|
|
|
|
@noindent
|
|
Pragma @code{Pack} applied to an array has no effect unless the component type
|
|
is packable. For a component type to be packable, it must be one of the
|
|
following cases:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Any scalar type
|
|
@item
|
|
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
|
|
For all these cases, if the component subtype size is in the range
|
|
1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
|
|
component size were specified giving the component subtype size.
|
|
For example if we have:
|
|
|
|
@smallexample @c ada
|
|
type r is range 0 .. 17;
|
|
|
|
type ar is array (1 .. 8) of r;
|
|
pragma Pack (ar);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
|
|
and the size of the array @code{ar} will be exactly 40 bits.
|
|
|
|
Note that in some cases this rather fierce approach to packing can produce
|
|
unexpected effects. For example, in Ada 95 and Ada 2005,
|
|
subtype @code{Natural} typically has a size of 31, meaning that if you
|
|
pack an array of @code{Natural}, you get 31-bit
|
|
close packing, which saves a few bits, but results in far less efficient
|
|
access. Since many other Ada compilers will ignore such a packing request,
|
|
GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
|
|
might not be what is intended. You can easily remove this warning by
|
|
using an explicit @code{Component_Size} setting instead, which never generates
|
|
a warning, since the intention of the programmer is clear in this case.
|
|
|
|
GNAT treats packed arrays in one of two ways. If the size of the array is
|
|
known at compile time and is less than 64 bits, then internally the array
|
|
is represented as a single modular type, of exactly the appropriate number
|
|
of bits. If the length is greater than 63 bits, or is not known at compile
|
|
time, then the packed array is represented as an array of bytes, and the
|
|
length is always a multiple of 8 bits.
|
|
|
|
Note that to represent a packed array as a modular type, the alignment must
|
|
be suitable for the modular type involved. For example, on typical machines
|
|
a 32-bit packed array will be represented by a 32-bit modular integer with
|
|
an alignment of four bytes. If you explicitly override the default alignment
|
|
with an alignment clause that is too small, the modular representation
|
|
cannot be used. For example, consider the following set of declarations:
|
|
|
|
@smallexample @c ada
|
|
type R is range 1 .. 3;
|
|
type S is array (1 .. 31) of R;
|
|
for S'Component_Size use 2;
|
|
for S'Size use 62;
|
|
for S'Alignment use 1;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the alignment clause were not present, then a 62-bit modular
|
|
representation would be chosen (typically with an alignment of 4 or 8
|
|
bytes depending on the target). But the default alignment is overridden
|
|
with the explicit alignment clause. This means that the modular
|
|
representation cannot be used, and instead the array of bytes
|
|
representation must be used, meaning that the length must be a multiple
|
|
of 8. Thus the above set of declarations will result in a diagnostic
|
|
rejecting the size clause and noting that the minimum size allowed is 64.
|
|
|
|
@cindex Pragma Pack (for type Natural)
|
|
@cindex Pragma Pack warning
|
|
|
|
One special case that is worth noting occurs when the base type of the
|
|
component size is 8/16/32 and the subtype is one bit less. Notably this
|
|
occurs with subtype @code{Natural}. Consider:
|
|
|
|
@smallexample @c ada
|
|
type Arr is array (1 .. 32) of Natural;
|
|
pragma Pack (Arr);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
|
|
since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
|
|
Ada 83 compilers did not attempt 31 bit packing.
|
|
|
|
In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
|
|
GNAT really does pack 31-bit subtype to 31 bits. This may result in a
|
|
substantial unintended performance penalty when porting legacy Ada 83 code.
|
|
To help prevent this, GNAT generates a warning in such cases. If you really
|
|
want 31 bit packing in a case like this, you can set the component size
|
|
explicitly:
|
|
|
|
@smallexample @c ada
|
|
type Arr is array (1 .. 32) of Natural;
|
|
for Arr'Component_Size use 31;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here 31-bit packing is achieved as required, and no warning is generated,
|
|
since in this case the programmer intention is clear.
|
|
|
|
@node Pragma Pack for Records
|
|
@section Pragma Pack for Records
|
|
@cindex Pragma Pack (for records)
|
|
|
|
@noindent
|
|
Pragma @code{Pack} applied to a record will pack the components to reduce
|
|
wasted space from alignment gaps and by reducing the amount of space
|
|
taken by components. We distinguish between @emph{packable} components and
|
|
@emph{non-packable} components.
|
|
Components of the following types are considered packable:
|
|
@itemize @bullet
|
|
@item
|
|
All primitive types are packable.
|
|
|
|
@item
|
|
Small packed arrays, whose size does not exceed 64 bits, and where the
|
|
size is statically known at compile time, are represented internally
|
|
as modular integers, and so they are also packable.
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
All packable components occupy the exact number of bits corresponding to
|
|
their @code{Size} value, and are packed with no padding bits, i.e.@: they
|
|
can start on an arbitrary bit boundary.
|
|
|
|
All other types are non-packable, they occupy an integral number of
|
|
storage units, and
|
|
are placed at a boundary corresponding to their alignment requirements.
|
|
|
|
For example, consider the record
|
|
|
|
@smallexample @c ada
|
|
type Rb1 is array (1 .. 13) of Boolean;
|
|
pragma Pack (rb1);
|
|
|
|
type Rb2 is array (1 .. 65) of Boolean;
|
|
pragma Pack (rb2);
|
|
|
|
type x2 is record
|
|
l1 : Boolean;
|
|
l2 : Duration;
|
|
l3 : Float;
|
|
l4 : Boolean;
|
|
l5 : Rb1;
|
|
l6 : Rb2;
|
|
end record;
|
|
pragma Pack (x2);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The representation for the record x2 is as follows:
|
|
|
|
@smallexample @c ada
|
|
for x2'Size use 224;
|
|
for x2 use record
|
|
l1 at 0 range 0 .. 0;
|
|
l2 at 0 range 1 .. 64;
|
|
l3 at 12 range 0 .. 31;
|
|
l4 at 16 range 0 .. 0;
|
|
l5 at 16 range 1 .. 13;
|
|
l6 at 18 range 0 .. 71;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Studying this example, we see that the packable fields @code{l1}
|
|
and @code{l2} are
|
|
of length equal to their sizes, and placed at specific bit boundaries (and
|
|
not byte boundaries) to
|
|
eliminate padding. But @code{l3} is of a non-packable float type, so
|
|
it is on the next appropriate alignment boundary.
|
|
|
|
The next two fields are fully packable, so @code{l4} and @code{l5} are
|
|
minimally packed with no gaps. However, type @code{Rb2} is a packed
|
|
array that is longer than 64 bits, so it is itself non-packable. Thus
|
|
the @code{l6} field is aligned to the next byte boundary, and takes an
|
|
integral number of bytes, i.e.@: 72 bits.
|
|
|
|
@node Record Representation Clauses
|
|
@section Record Representation Clauses
|
|
@cindex Record Representation Clause
|
|
|
|
@noindent
|
|
Record representation clauses may be given for all record types, including
|
|
types obtained by record extension. Component clauses are allowed for any
|
|
static component. The restrictions on component clauses depend on the type
|
|
of the component.
|
|
|
|
@cindex Component Clause
|
|
For all components of an elementary type, the only restriction on component
|
|
clauses is that the size must be at least the 'Size value of the type
|
|
(actually the Value_Size). There are no restrictions due to alignment,
|
|
and such components may freely cross storage boundaries.
|
|
|
|
Packed arrays with a size up to and including 64 bits are represented
|
|
internally using a modular type with the appropriate number of bits, and
|
|
thus the same lack of restriction applies. For example, if you declare:
|
|
|
|
@smallexample @c ada
|
|
type R is array (1 .. 49) of Boolean;
|
|
pragma Pack (R);
|
|
for R'Size use 49;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then a component clause for a component of type R may start on any
|
|
specified bit boundary, and may specify a value of 49 bits or greater.
|
|
|
|
For packed bit arrays that are longer than 64 bits, there are two
|
|
cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
|
|
including the important case of single bits or boolean values, then
|
|
there are no limitations on placement of such components, and they
|
|
may start and end at arbitrary bit boundaries.
|
|
|
|
If the component size is not a power of 2 (e.g.@: 3 or 5), then
|
|
an array of this type longer than 64 bits must always be placed on
|
|
on a storage unit (byte) boundary and occupy an integral number
|
|
of storage units (bytes). Any component clause that does not
|
|
meet this requirement will be rejected.
|
|
|
|
Any aliased component, or component of an aliased type, must
|
|
have its normal alignment and size. A component clause that
|
|
does not meet this requirement will be rejected.
|
|
|
|
The tag field of a tagged type always occupies an address sized field at
|
|
the start of the record. No component clause may attempt to overlay this
|
|
tag. When a tagged type appears as a component, the tag field must have
|
|
proper alignment
|
|
|
|
In the case of a record extension T1, of a type T, no component clause applied
|
|
to the type T1 can specify a storage location that would overlap the first
|
|
T'Size bytes of the record.
|
|
|
|
For all other component types, including non-bit-packed arrays,
|
|
the component can be placed at an arbitrary bit boundary,
|
|
so for example, the following is permitted:
|
|
|
|
@smallexample @c ada
|
|
type R is array (1 .. 10) of Boolean;
|
|
for R'Size use 80;
|
|
|
|
type Q is record
|
|
G, H : Boolean;
|
|
L, M : R;
|
|
end record;
|
|
|
|
for Q use record
|
|
G at 0 range 0 .. 0;
|
|
H at 0 range 1 .. 1;
|
|
L at 0 range 2 .. 81;
|
|
R at 0 range 82 .. 161;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note: the above rules apply to recent releases of GNAT 5.
|
|
In GNAT 3, there are more severe restrictions on larger components.
|
|
For non-primitive types, including packed arrays with a size greater than
|
|
64 bits, component clauses must respect the alignment requirement of the
|
|
type, in particular, always starting on a byte boundary, and the length
|
|
must be a multiple of the storage unit.
|
|
|
|
@node Enumeration Clauses
|
|
@section Enumeration Clauses
|
|
|
|
The only restriction on enumeration clauses is that the range of values
|
|
must be representable. For the signed case, if one or more of the
|
|
representation values are negative, all values must be in the range:
|
|
|
|
@smallexample @c ada
|
|
System.Min_Int .. System.Max_Int
|
|
@end smallexample
|
|
|
|
@noindent
|
|
For the unsigned case, where all values are nonnegative, the values must
|
|
be in the range:
|
|
|
|
@smallexample @c ada
|
|
0 .. System.Max_Binary_Modulus;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A @emph{confirming} representation clause is one in which the values range
|
|
from 0 in sequence, i.e.@: a clause that confirms the default representation
|
|
for an enumeration type.
|
|
Such a confirming representation
|
|
is permitted by these rules, and is specially recognized by the compiler so
|
|
that no extra overhead results from the use of such a clause.
|
|
|
|
If an array has an index type which is an enumeration type to which an
|
|
enumeration clause has been applied, then the array is stored in a compact
|
|
manner. Consider the declarations:
|
|
|
|
@smallexample @c ada
|
|
type r is (A, B, C);
|
|
for r use (A => 1, B => 5, C => 10);
|
|
type t is array (r) of Character;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The array type t corresponds to a vector with exactly three elements and
|
|
has a default size equal to @code{3*Character'Size}. This ensures efficient
|
|
use of space, but means that accesses to elements of the array will incur
|
|
the overhead of converting representation values to the corresponding
|
|
positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
|
|
|
|
@node Address Clauses
|
|
@section Address Clauses
|
|
@cindex Address Clause
|
|
|
|
The reference manual allows a general restriction on representation clauses,
|
|
as found in RM 13.1(22):
|
|
|
|
@quotation
|
|
An implementation need not support representation
|
|
items containing nonstatic expressions, except that
|
|
an implementation should support a representation item
|
|
for a given entity if each nonstatic expression in the
|
|
representation item is a name that statically denotes
|
|
a constant declared before the entity.
|
|
@end quotation
|
|
|
|
@noindent
|
|
In practice this is applicable only to address clauses, since this is the
|
|
only case in which a non-static expression is permitted by the syntax. As
|
|
the AARM notes in sections 13.1 (22.a-22.h):
|
|
|
|
@display
|
|
22.a Reason: This is to avoid the following sort of thing:
|
|
|
|
22.b X : Integer := F(@dots{});
|
|
Y : Address := G(@dots{});
|
|
for X'Address use Y;
|
|
|
|
22.c In the above, we have to evaluate the
|
|
initialization expression for X before we
|
|
know where to put the result. This seems
|
|
like an unreasonable implementation burden.
|
|
|
|
22.d The above code should instead be written
|
|
like this:
|
|
|
|
22.e Y : constant Address := G(@dots{});
|
|
X : Integer := F(@dots{});
|
|
for X'Address use Y;
|
|
|
|
22.f This allows the expression ``Y'' to be safely
|
|
evaluated before X is created.
|
|
|
|
22.g The constant could be a formal parameter of mode in.
|
|
|
|
22.h An implementation can support other nonstatic
|
|
expressions if it wants to. Expressions of type
|
|
Address are hardly ever static, but their value
|
|
might be known at compile time anyway in many
|
|
cases.
|
|
@end display
|
|
|
|
@noindent
|
|
GNAT does indeed permit many additional cases of non-static expressions. In
|
|
particular, if the type involved is elementary there are no restrictions
|
|
(since in this case, holding a temporary copy of the initialization value,
|
|
if one is present, is inexpensive). In addition, if there is no implicit or
|
|
explicit initialization, then there are no restrictions. GNAT will reject
|
|
only the case where all three of these conditions hold:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
The type of the item is non-elementary (e.g.@: a record or array).
|
|
|
|
@item
|
|
There is explicit or implicit initialization required for the object.
|
|
Note that access values are always implicitly initialized.
|
|
|
|
@item
|
|
The address value is non-static. Here GNAT is more permissive than the
|
|
RM, and allows the address value to be the address of a previously declared
|
|
stand-alone variable, as long as it does not itself have an address clause.
|
|
|
|
@smallexample @c ada
|
|
Anchor : Some_Initialized_Type;
|
|
Overlay : Some_Initialized_Type;
|
|
for Overlay'Address use Anchor'Address;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
However, the prefix of the address clause cannot be an array component, or
|
|
a component of a discriminated record.
|
|
|
|
@end itemize
|
|
|
|
@noindent
|
|
As noted above in section 22.h, address values are typically non-static. In
|
|
particular the To_Address function, even if applied to a literal value, is
|
|
a non-static function call. To avoid this minor annoyance, GNAT provides
|
|
the implementation defined attribute 'To_Address. The following two
|
|
expressions have identical values:
|
|
|
|
@findex Attribute
|
|
@findex To_Address
|
|
@smallexample @c ada
|
|
To_Address (16#1234_0000#)
|
|
System'To_Address (16#1234_0000#);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
except that the second form is considered to be a static expression, and
|
|
thus when used as an address clause value is always permitted.
|
|
|
|
@noindent
|
|
Additionally, GNAT treats as static an address clause that is an
|
|
unchecked_conversion of a static integer value. This simplifies the porting
|
|
of legacy code, and provides a portable equivalent to the GNAT attribute
|
|
@code{To_Address}.
|
|
|
|
Another issue with address clauses is the interaction with alignment
|
|
requirements. When an address clause is given for an object, the address
|
|
value must be consistent with the alignment of the object (which is usually
|
|
the same as the alignment of the type of the object). If an address clause
|
|
is given that specifies an inappropriately aligned address value, then the
|
|
program execution is erroneous.
|
|
|
|
Since this source of erroneous behavior can have unfortunate effects, GNAT
|
|
checks (at compile time if possible, generating a warning, or at execution
|
|
time with a run-time check) that the alignment is appropriate. If the
|
|
run-time check fails, then @code{Program_Error} is raised. This run-time
|
|
check is suppressed if range checks are suppressed, or if the special GNAT
|
|
check Alignment_Check is suppressed, or if
|
|
@code{pragma Restrictions (No_Elaboration_Code)} is in effect.
|
|
|
|
Finally, GNAT does not permit overlaying of objects of controlled types or
|
|
composite types containing a controlled component. In most cases, the compiler
|
|
can detect an attempt at such overlays and will generate a warning at compile
|
|
time and a Program_Error exception at run time.
|
|
|
|
@findex Export
|
|
An address clause cannot be given for an exported object. More
|
|
understandably the real restriction is that objects with an address
|
|
clause cannot be exported. This is because such variables are not
|
|
defined by the Ada program, so there is no external object to export.
|
|
|
|
@findex Import
|
|
It is permissible to give an address clause and a pragma Import for the
|
|
same object. In this case, the variable is not really defined by the
|
|
Ada program, so there is no external symbol to be linked. The link name
|
|
and the external name are ignored in this case. The reason that we allow this
|
|
combination is that it provides a useful idiom to avoid unwanted
|
|
initializations on objects with address clauses.
|
|
|
|
When an address clause is given for an object that has implicit or
|
|
explicit initialization, then by default initialization takes place. This
|
|
means that the effect of the object declaration is to overwrite the
|
|
memory at the specified address. This is almost always not what the
|
|
programmer wants, so GNAT will output a warning:
|
|
|
|
@smallexample
|
|
with System;
|
|
package G is
|
|
type R is record
|
|
M : Integer := 0;
|
|
end record;
|
|
|
|
Ext : R;
|
|
for Ext'Address use System'To_Address (16#1234_1234#);
|
|
|
|
|
>>> warning: implicit initialization of "Ext" may
|
|
modify overlaid storage
|
|
>>> warning: use pragma Import for "Ext" to suppress
|
|
initialization (RM B(24))
|
|
|
|
end G;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
As indicated by the warning message, the solution is to use a (dummy) pragma
|
|
Import to suppress this initialization. The pragma tell the compiler that the
|
|
object is declared and initialized elsewhere. The following package compiles
|
|
without warnings (and the initialization is suppressed):
|
|
|
|
@smallexample @c ada
|
|
with System;
|
|
package G is
|
|
type R is record
|
|
M : Integer := 0;
|
|
end record;
|
|
|
|
Ext : R;
|
|
for Ext'Address use System'To_Address (16#1234_1234#);
|
|
pragma Import (Ada, Ext);
|
|
end G;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A final issue with address clauses involves their use for overlaying
|
|
variables, as in the following example:
|
|
@cindex Overlaying of objects
|
|
|
|
@smallexample @c ada
|
|
A : Integer;
|
|
B : Integer;
|
|
for B'Address use A'Address;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
or alternatively, using the form recommended by the RM:
|
|
|
|
@smallexample @c ada
|
|
A : Integer;
|
|
Addr : constant Address := A'Address;
|
|
B : Integer;
|
|
for B'Address use Addr;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In both of these cases, @code{A}
|
|
and @code{B} become aliased to one another via the
|
|
address clause. This use of address clauses to overlay
|
|
variables, achieving an effect similar to unchecked
|
|
conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
|
|
the effect is implementation defined. Furthermore, the
|
|
Ada RM specifically recommends that in a situation
|
|
like this, @code{B} should be subject to the following
|
|
implementation advice (RM 13.3(19)):
|
|
|
|
@quotation
|
|
19 If the Address of an object is specified, or it is imported
|
|
or exported, then the implementation should not perform
|
|
optimizations based on assumptions of no aliases.
|
|
@end quotation
|
|
|
|
@noindent
|
|
GNAT follows this recommendation, and goes further by also applying
|
|
this recommendation to the overlaid variable (@code{A}
|
|
in the above example) in this case. This means that the overlay
|
|
works "as expected", in that a modification to one of the variables
|
|
will affect the value of the other.
|
|
|
|
@node Effect of Convention on Representation
|
|
@section Effect of Convention on Representation
|
|
@cindex Convention, effect on representation
|
|
|
|
@noindent
|
|
Normally the specification of a foreign language convention for a type or
|
|
an object has no effect on the chosen representation. In particular, the
|
|
representation chosen for data in GNAT generally meets the standard system
|
|
conventions, and for example records are laid out in a manner that is
|
|
consistent with C@. This means that specifying convention C (for example)
|
|
has no effect.
|
|
|
|
There are four exceptions to this general rule:
|
|
|
|
@itemize @bullet
|
|
|
|
@item Convention Fortran and array subtypes
|
|
If pragma Convention Fortran is specified for an array subtype, then in
|
|
accordance with the implementation advice in section 3.6.2(11) of the
|
|
Ada Reference Manual, the array will be stored in a Fortran-compatible
|
|
column-major manner, instead of the normal default row-major order.
|
|
|
|
@item Convention C and enumeration types
|
|
GNAT normally stores enumeration types in 8, 16, or 32 bits as required
|
|
to accommodate all values of the type. For example, for the enumeration
|
|
type declared by:
|
|
|
|
@smallexample @c ada
|
|
type Color is (Red, Green, Blue);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
8 bits is sufficient to store all values of the type, so by default, objects
|
|
of type @code{Color} will be represented using 8 bits. However, normal C
|
|
convention is to use 32 bits for all enum values in C, since enum values
|
|
are essentially of type int. If pragma @code{Convention C} is specified for an
|
|
Ada enumeration type, then the size is modified as necessary (usually to
|
|
32 bits) to be consistent with the C convention for enum values.
|
|
|
|
Note that this treatment applies only to types. If Convention C is given for
|
|
an enumeration object, where the enumeration type is not Convention C, then
|
|
Object_Size bits are allocated. For example, for a normal enumeration type,
|
|
with less than 256 elements, only 8 bits will be allocated for the object.
|
|
Since this may be a surprise in terms of what C expects, GNAT will issue a
|
|
warning in this situation. The warning can be suppressed by giving an explicit
|
|
size clause specifying the desired size.
|
|
|
|
@item Convention C/Fortran and Boolean types
|
|
In C, the usual convention for boolean values, that is values used for
|
|
conditions, is that zero represents false, and nonzero values represent
|
|
true. In Ada, the normal convention is that two specific values, typically
|
|
0/1, are used to represent false/true respectively.
|
|
|
|
Fortran has a similar convention for @code{LOGICAL} values (any nonzero
|
|
value represents true).
|
|
|
|
To accommodate the Fortran and C conventions, if a pragma Convention specifies
|
|
C or Fortran convention for a derived Boolean, as in the following example:
|
|
|
|
@smallexample @c ada
|
|
type C_Switch is new Boolean;
|
|
pragma Convention (C, C_Switch);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then the GNAT generated code will treat any nonzero value as true. For truth
|
|
values generated by GNAT, the conventional value 1 will be used for True, but
|
|
when one of these values is read, any nonzero value is treated as True.
|
|
|
|
@item Access types on OpenVMS
|
|
For 64-bit OpenVMS systems, access types (other than those for unconstrained
|
|
arrays) are 64-bits long. An exception to this rule is for the case of
|
|
C-convention access types where there is no explicit size clause present (or
|
|
inherited for derived types). In this case, GNAT chooses to make these
|
|
pointers 32-bits, which provides an easier path for migration of 32-bit legacy
|
|
code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
|
|
|
|
@end itemize
|
|
|
|
@node Determining the Representations chosen by GNAT
|
|
@section Determining the Representations chosen by GNAT
|
|
@cindex Representation, determination of
|
|
@cindex @option{-gnatR} switch
|
|
|
|
@noindent
|
|
Although the descriptions in this section are intended to be complete, it is
|
|
often easier to simply experiment to see what GNAT accepts and what the
|
|
effect is on the layout of types and objects.
|
|
|
|
As required by the Ada RM, if a representation clause is not accepted, then
|
|
it must be rejected as illegal by the compiler. However, when a
|
|
representation clause or pragma is accepted, there can still be questions
|
|
of what the compiler actually does. For example, if a partial record
|
|
representation clause specifies the location of some components and not
|
|
others, then where are the non-specified components placed? Or if pragma
|
|
@code{Pack} is used on a record, then exactly where are the resulting
|
|
fields placed? The section on pragma @code{Pack} in this chapter can be
|
|
used to answer the second question, but it is often easier to just see
|
|
what the compiler does.
|
|
|
|
For this purpose, GNAT provides the option @option{-gnatR}. If you compile
|
|
with this option, then the compiler will output information on the actual
|
|
representations chosen, in a format similar to source representation
|
|
clauses. For example, if we compile the package:
|
|
|
|
@smallexample @c ada
|
|
package q is
|
|
type r (x : boolean) is tagged record
|
|
case x is
|
|
when True => S : String (1 .. 100);
|
|
when False => null;
|
|
end case;
|
|
end record;
|
|
|
|
type r2 is new r (false) with record
|
|
y2 : integer;
|
|
end record;
|
|
|
|
for r2 use record
|
|
y2 at 16 range 0 .. 31;
|
|
end record;
|
|
|
|
type x is record
|
|
y : character;
|
|
end record;
|
|
|
|
type x1 is array (1 .. 10) of x;
|
|
for x1'component_size use 11;
|
|
|
|
type ia is access integer;
|
|
|
|
type Rb1 is array (1 .. 13) of Boolean;
|
|
pragma Pack (rb1);
|
|
|
|
type Rb2 is array (1 .. 65) of Boolean;
|
|
pragma Pack (rb2);
|
|
|
|
type x2 is record
|
|
l1 : Boolean;
|
|
l2 : Duration;
|
|
l3 : Float;
|
|
l4 : Boolean;
|
|
l5 : Rb1;
|
|
l6 : Rb2;
|
|
end record;
|
|
pragma Pack (x2);
|
|
end q;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
using the switch @option{-gnatR} we obtain the following output:
|
|
|
|
@smallexample
|
|
Representation information for unit q
|
|
-------------------------------------
|
|
|
|
for r'Size use ??;
|
|
for r'Alignment use 4;
|
|
for r use record
|
|
x at 4 range 0 .. 7;
|
|
_tag at 0 range 0 .. 31;
|
|
s at 5 range 0 .. 799;
|
|
end record;
|
|
|
|
for r2'Size use 160;
|
|
for r2'Alignment use 4;
|
|
for r2 use record
|
|
x at 4 range 0 .. 7;
|
|
_tag at 0 range 0 .. 31;
|
|
_parent at 0 range 0 .. 63;
|
|
y2 at 16 range 0 .. 31;
|
|
end record;
|
|
|
|
for x'Size use 8;
|
|
for x'Alignment use 1;
|
|
for x use record
|
|
y at 0 range 0 .. 7;
|
|
end record;
|
|
|
|
for x1'Size use 112;
|
|
for x1'Alignment use 1;
|
|
for x1'Component_Size use 11;
|
|
|
|
for rb1'Size use 13;
|
|
for rb1'Alignment use 2;
|
|
for rb1'Component_Size use 1;
|
|
|
|
for rb2'Size use 72;
|
|
for rb2'Alignment use 1;
|
|
for rb2'Component_Size use 1;
|
|
|
|
for x2'Size use 224;
|
|
for x2'Alignment use 4;
|
|
for x2 use record
|
|
l1 at 0 range 0 .. 0;
|
|
l2 at 0 range 1 .. 64;
|
|
l3 at 12 range 0 .. 31;
|
|
l4 at 16 range 0 .. 0;
|
|
l5 at 16 range 1 .. 13;
|
|
l6 at 18 range 0 .. 71;
|
|
end record;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The Size values are actually the Object_Size, i.e.@: the default size that
|
|
will be allocated for objects of the type.
|
|
The ?? size for type r indicates that we have a variant record, and the
|
|
actual size of objects will depend on the discriminant value.
|
|
|
|
The Alignment values show the actual alignment chosen by the compiler
|
|
for each record or array type.
|
|
|
|
The record representation clause for type r shows where all fields
|
|
are placed, including the compiler generated tag field (whose location
|
|
cannot be controlled by the programmer).
|
|
|
|
The record representation clause for the type extension r2 shows all the
|
|
fields present, including the parent field, which is a copy of the fields
|
|
of the parent type of r2, i.e.@: r1.
|
|
|
|
The component size and size clauses for types rb1 and rb2 show
|
|
the exact effect of pragma @code{Pack} on these arrays, and the record
|
|
representation clause for type x2 shows how pragma @code{Pack} affects
|
|
this record type.
|
|
|
|
In some cases, it may be useful to cut and paste the representation clauses
|
|
generated by the compiler into the original source to fix and guarantee
|
|
the actual representation to be used.
|
|
|
|
@node Standard Library Routines
|
|
@chapter Standard Library Routines
|
|
|
|
@noindent
|
|
The Ada Reference Manual contains in Annex A a full description of an
|
|
extensive set of standard library routines that can be used in any Ada
|
|
program, and which must be provided by all Ada compilers. They are
|
|
analogous to the standard C library used by C programs.
|
|
|
|
GNAT implements all of the facilities described in annex A, and for most
|
|
purposes the description in the Ada Reference Manual, or appropriate Ada
|
|
text book, will be sufficient for making use of these facilities.
|
|
|
|
In the case of the input-output facilities,
|
|
@xref{The Implementation of Standard I/O},
|
|
gives details on exactly how GNAT interfaces to the
|
|
file system. For the remaining packages, the Ada Reference Manual
|
|
should be sufficient. The following is a list of the packages included,
|
|
together with a brief description of the functionality that is provided.
|
|
|
|
For completeness, references are included to other predefined library
|
|
routines defined in other sections of the Ada Reference Manual (these are
|
|
cross-indexed from Annex A).
|
|
|
|
@table @code
|
|
@item Ada (A.2)
|
|
This is a parent package for all the standard library packages. It is
|
|
usually included implicitly in your program, and itself contains no
|
|
useful data or routines.
|
|
|
|
@item Ada.Calendar (9.6)
|
|
@code{Calendar} provides time of day access, and routines for
|
|
manipulating times and durations.
|
|
|
|
@item Ada.Characters (A.3.1)
|
|
This is a dummy parent package that contains no useful entities
|
|
|
|
@item Ada.Characters.Handling (A.3.2)
|
|
This package provides some basic character handling capabilities,
|
|
including classification functions for classes of characters (e.g.@: test
|
|
for letters, or digits).
|
|
|
|
@item Ada.Characters.Latin_1 (A.3.3)
|
|
This package includes a complete set of definitions of the characters
|
|
that appear in type CHARACTER@. It is useful for writing programs that
|
|
will run in international environments. For example, if you want an
|
|
upper case E with an acute accent in a string, it is often better to use
|
|
the definition of @code{UC_E_Acute} in this package. Then your program
|
|
will print in an understandable manner even if your environment does not
|
|
support these extended characters.
|
|
|
|
@item Ada.Command_Line (A.15)
|
|
This package provides access to the command line parameters and the name
|
|
of the current program (analogous to the use of @code{argc} and @code{argv}
|
|
in C), and also allows the exit status for the program to be set in a
|
|
system-independent manner.
|
|
|
|
@item Ada.Decimal (F.2)
|
|
This package provides constants describing the range of decimal numbers
|
|
implemented, and also a decimal divide routine (analogous to the COBOL
|
|
verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{})
|
|
|
|
@item Ada.Direct_IO (A.8.4)
|
|
This package provides input-output using a model of a set of records of
|
|
fixed-length, containing an arbitrary definite Ada type, indexed by an
|
|
integer record number.
|
|
|
|
@item Ada.Dynamic_Priorities (D.5)
|
|
This package allows the priorities of a task to be adjusted dynamically
|
|
as the task is running.
|
|
|
|
@item Ada.Exceptions (11.4.1)
|
|
This package provides additional information on exceptions, and also
|
|
contains facilities for treating exceptions as data objects, and raising
|
|
exceptions with associated messages.
|
|
|
|
@item Ada.Finalization (7.6)
|
|
This package contains the declarations and subprograms to support the
|
|
use of controlled types, providing for automatic initialization and
|
|
finalization (analogous to the constructors and destructors of C++)
|
|
|
|
@item Ada.Interrupts (C.3.2)
|
|
This package provides facilities for interfacing to interrupts, which
|
|
includes the set of signals or conditions that can be raised and
|
|
recognized as interrupts.
|
|
|
|
@item Ada.Interrupts.Names (C.3.2)
|
|
This package provides the set of interrupt names (actually signal
|
|
or condition names) that can be handled by GNAT@.
|
|
|
|
@item Ada.IO_Exceptions (A.13)
|
|
This package defines the set of exceptions that can be raised by use of
|
|
the standard IO packages.
|
|
|
|
@item Ada.Numerics
|
|
This package contains some standard constants and exceptions used
|
|
throughout the numerics packages. Note that the constants pi and e are
|
|
defined here, and it is better to use these definitions than rolling
|
|
your own.
|
|
|
|
@item Ada.Numerics.Complex_Elementary_Functions
|
|
Provides the implementation of standard elementary functions (such as
|
|
log and trigonometric functions) operating on complex numbers using the
|
|
standard @code{Float} and the @code{Complex} and @code{Imaginary} types
|
|
created by the package @code{Numerics.Complex_Types}.
|
|
|
|
@item Ada.Numerics.Complex_Types
|
|
This is a predefined instantiation of
|
|
@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
|
|
build the type @code{Complex} and @code{Imaginary}.
|
|
|
|
@item Ada.Numerics.Discrete_Random
|
|
This generic package provides a random number generator suitable for generating
|
|
uniformly distributed values of a specified discrete subtype.
|
|
|
|
@item Ada.Numerics.Float_Random
|
|
This package provides a random number generator suitable for generating
|
|
uniformly distributed floating point values in the unit interval.
|
|
|
|
@item Ada.Numerics.Generic_Complex_Elementary_Functions
|
|
This is a generic version of the package that provides the
|
|
implementation of standard elementary functions (such as log and
|
|
trigonometric functions) for an arbitrary complex type.
|
|
|
|
The following predefined instantiations of this package are provided:
|
|
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Ada.Numerics.Short_Complex_Elementary_Functions}
|
|
@item Float
|
|
@code{Ada.Numerics.Complex_Elementary_Functions}
|
|
@item Long_Float
|
|
@code{Ada.Numerics.Long_Complex_Elementary_Functions}
|
|
@end table
|
|
|
|
@item Ada.Numerics.Generic_Complex_Types
|
|
This is a generic package that allows the creation of complex types,
|
|
with associated complex arithmetic operations.
|
|
|
|
The following predefined instantiations of this package exist
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Ada.Numerics.Short_Complex_Complex_Types}
|
|
@item Float
|
|
@code{Ada.Numerics.Complex_Complex_Types}
|
|
@item Long_Float
|
|
@code{Ada.Numerics.Long_Complex_Complex_Types}
|
|
@end table
|
|
|
|
@item Ada.Numerics.Generic_Elementary_Functions
|
|
This is a generic package that provides the implementation of standard
|
|
elementary functions (such as log an trigonometric functions) for an
|
|
arbitrary float type.
|
|
|
|
The following predefined instantiations of this package exist
|
|
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Ada.Numerics.Short_Elementary_Functions}
|
|
@item Float
|
|
@code{Ada.Numerics.Elementary_Functions}
|
|
@item Long_Float
|
|
@code{Ada.Numerics.Long_Elementary_Functions}
|
|
@end table
|
|
|
|
@item Ada.Real_Time (D.8)
|
|
This package provides facilities similar to those of @code{Calendar}, but
|
|
operating with a finer clock suitable for real time control. Note that
|
|
annex D requires that there be no backward clock jumps, and GNAT generally
|
|
guarantees this behavior, but of course if the external clock on which
|
|
the GNAT runtime depends is deliberately reset by some external event,
|
|
then such a backward jump may occur.
|
|
|
|
@item Ada.Sequential_IO (A.8.1)
|
|
This package provides input-output facilities for sequential files,
|
|
which can contain a sequence of values of a single type, which can be
|
|
any Ada type, including indefinite (unconstrained) types.
|
|
|
|
@item Ada.Storage_IO (A.9)
|
|
This package provides a facility for mapping arbitrary Ada types to and
|
|
from a storage buffer. It is primarily intended for the creation of new
|
|
IO packages.
|
|
|
|
@item Ada.Streams (13.13.1)
|
|
This is a generic package that provides the basic support for the
|
|
concept of streams as used by the stream attributes (@code{Input},
|
|
@code{Output}, @code{Read} and @code{Write}).
|
|
|
|
@item Ada.Streams.Stream_IO (A.12.1)
|
|
This package is a specialization of the type @code{Streams} defined in
|
|
package @code{Streams} together with a set of operations providing
|
|
Stream_IO capability. The Stream_IO model permits both random and
|
|
sequential access to a file which can contain an arbitrary set of values
|
|
of one or more Ada types.
|
|
|
|
@item Ada.Strings (A.4.1)
|
|
This package provides some basic constants used by the string handling
|
|
packages.
|
|
|
|
@item Ada.Strings.Bounded (A.4.4)
|
|
This package provides facilities for handling variable length
|
|
strings. The bounded model requires a maximum length. It is thus
|
|
somewhat more limited than the unbounded model, but avoids the use of
|
|
dynamic allocation or finalization.
|
|
|
|
@item Ada.Strings.Fixed (A.4.3)
|
|
This package provides facilities for handling fixed length strings.
|
|
|
|
@item Ada.Strings.Maps (A.4.2)
|
|
This package provides facilities for handling character mappings and
|
|
arbitrarily defined subsets of characters. For instance it is useful in
|
|
defining specialized translation tables.
|
|
|
|
@item Ada.Strings.Maps.Constants (A.4.6)
|
|
This package provides a standard set of predefined mappings and
|
|
predefined character sets. For example, the standard upper to lower case
|
|
conversion table is found in this package. Note that upper to lower case
|
|
conversion is non-trivial if you want to take the entire set of
|
|
characters, including extended characters like E with an acute accent,
|
|
into account. You should use the mappings in this package (rather than
|
|
adding 32 yourself) to do case mappings.
|
|
|
|
@item Ada.Strings.Unbounded (A.4.5)
|
|
This package provides facilities for handling variable length
|
|
strings. The unbounded model allows arbitrary length strings, but
|
|
requires the use of dynamic allocation and finalization.
|
|
|
|
@item Ada.Strings.Wide_Bounded (A.4.7)
|
|
@itemx Ada.Strings.Wide_Fixed (A.4.7)
|
|
@itemx Ada.Strings.Wide_Maps (A.4.7)
|
|
@itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
|
|
@itemx Ada.Strings.Wide_Unbounded (A.4.7)
|
|
These packages provide analogous capabilities to the corresponding
|
|
packages without @samp{Wide_} in the name, but operate with the types
|
|
@code{Wide_String} and @code{Wide_Character} instead of @code{String}
|
|
and @code{Character}.
|
|
|
|
@item Ada.Strings.Wide_Wide_Bounded (A.4.7)
|
|
@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
|
|
@itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
|
|
@itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
|
|
@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
|
|
These packages provide analogous capabilities to the corresponding
|
|
packages without @samp{Wide_} in the name, but operate with the types
|
|
@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
|
|
of @code{String} and @code{Character}.
|
|
|
|
@item Ada.Synchronous_Task_Control (D.10)
|
|
This package provides some standard facilities for controlling task
|
|
communication in a synchronous manner.
|
|
|
|
@item Ada.Tags
|
|
This package contains definitions for manipulation of the tags of tagged
|
|
values.
|
|
|
|
@item Ada.Task_Attributes
|
|
This package provides the capability of associating arbitrary
|
|
task-specific data with separate tasks.
|
|
|
|
@item Ada.Text_IO
|
|
This package provides basic text input-output capabilities for
|
|
character, string and numeric data. The subpackages of this
|
|
package are listed next.
|
|
|
|
@item Ada.Text_IO.Decimal_IO
|
|
Provides input-output facilities for decimal fixed-point types
|
|
|
|
@item Ada.Text_IO.Enumeration_IO
|
|
Provides input-output facilities for enumeration types.
|
|
|
|
@item Ada.Text_IO.Fixed_IO
|
|
Provides input-output facilities for ordinary fixed-point types.
|
|
|
|
@item Ada.Text_IO.Float_IO
|
|
Provides input-output facilities for float types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Short_Float_Text_IO}
|
|
@item Float
|
|
@code{Float_Text_IO}
|
|
@item Long_Float
|
|
@code{Long_Float_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Text_IO.Integer_IO
|
|
Provides input-output facilities for integer types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Short_Integer
|
|
@code{Ada.Short_Short_Integer_Text_IO}
|
|
@item Short_Integer
|
|
@code{Ada.Short_Integer_Text_IO}
|
|
@item Integer
|
|
@code{Ada.Integer_Text_IO}
|
|
@item Long_Integer
|
|
@code{Ada.Long_Integer_Text_IO}
|
|
@item Long_Long_Integer
|
|
@code{Ada.Long_Long_Integer_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Text_IO.Modular_IO
|
|
Provides input-output facilities for modular (unsigned) types
|
|
|
|
@item Ada.Text_IO.Complex_IO (G.1.3)
|
|
This package provides basic text input-output capabilities for complex
|
|
data.
|
|
|
|
@item Ada.Text_IO.Editing (F.3.3)
|
|
This package contains routines for edited output, analogous to the use
|
|
of pictures in COBOL@. The picture formats used by this package are a
|
|
close copy of the facility in COBOL@.
|
|
|
|
@item Ada.Text_IO.Text_Streams (A.12.2)
|
|
This package provides a facility that allows Text_IO files to be treated
|
|
as streams, so that the stream attributes can be used for writing
|
|
arbitrary data, including binary data, to Text_IO files.
|
|
|
|
@item Ada.Unchecked_Conversion (13.9)
|
|
This generic package allows arbitrary conversion from one type to
|
|
another of the same size, providing for breaking the type safety in
|
|
special circumstances.
|
|
|
|
If the types have the same Size (more accurately the same Value_Size),
|
|
then the effect is simply to transfer the bits from the source to the
|
|
target type without any modification. This usage is well defined, and
|
|
for simple types whose representation is typically the same across
|
|
all implementations, gives a portable method of performing such
|
|
conversions.
|
|
|
|
If the types do not have the same size, then the result is implementation
|
|
defined, and thus may be non-portable. The following describes how GNAT
|
|
handles such unchecked conversion cases.
|
|
|
|
If the types are of different sizes, and are both discrete types, then
|
|
the effect is of a normal type conversion without any constraint checking.
|
|
In particular if the result type has a larger size, the result will be
|
|
zero or sign extended. If the result type has a smaller size, the result
|
|
will be truncated by ignoring high order bits.
|
|
|
|
If the types are of different sizes, and are not both discrete types,
|
|
then the conversion works as though pointers were created to the source
|
|
and target, and the pointer value is converted. The effect is that bits
|
|
are copied from successive low order storage units and bits of the source
|
|
up to the length of the target type.
|
|
|
|
A warning is issued if the lengths differ, since the effect in this
|
|
case is implementation dependent, and the above behavior may not match
|
|
that of some other compiler.
|
|
|
|
A pointer to one type may be converted to a pointer to another type using
|
|
unchecked conversion. The only case in which the effect is undefined is
|
|
when one or both pointers are pointers to unconstrained array types. In
|
|
this case, the bounds information may get incorrectly transferred, and in
|
|
particular, GNAT uses double size pointers for such types, and it is
|
|
meaningless to convert between such pointer types. GNAT will issue a
|
|
warning if the alignment of the target designated type is more strict
|
|
than the alignment of the source designated type (since the result may
|
|
be unaligned in this case).
|
|
|
|
A pointer other than a pointer to an unconstrained array type may be
|
|
converted to and from System.Address. Such usage is common in Ada 83
|
|
programs, but note that Ada.Address_To_Access_Conversions is the
|
|
preferred method of performing such conversions in Ada 95 and Ada 2005.
|
|
Neither
|
|
unchecked conversion nor Ada.Address_To_Access_Conversions should be
|
|
used in conjunction with pointers to unconstrained objects, since
|
|
the bounds information cannot be handled correctly in this case.
|
|
|
|
@item Ada.Unchecked_Deallocation (13.11.2)
|
|
This generic package allows explicit freeing of storage previously
|
|
allocated by use of an allocator.
|
|
|
|
@item Ada.Wide_Text_IO (A.11)
|
|
This package is similar to @code{Ada.Text_IO}, except that the external
|
|
file supports wide character representations, and the internal types are
|
|
@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
|
|
and @code{String}. It contains generic subpackages listed next.
|
|
|
|
@item Ada.Wide_Text_IO.Decimal_IO
|
|
Provides input-output facilities for decimal fixed-point types
|
|
|
|
@item Ada.Wide_Text_IO.Enumeration_IO
|
|
Provides input-output facilities for enumeration types.
|
|
|
|
@item Ada.Wide_Text_IO.Fixed_IO
|
|
Provides input-output facilities for ordinary fixed-point types.
|
|
|
|
@item Ada.Wide_Text_IO.Float_IO
|
|
Provides input-output facilities for float types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Short_Float_Wide_Text_IO}
|
|
@item Float
|
|
@code{Float_Wide_Text_IO}
|
|
@item Long_Float
|
|
@code{Long_Float_Wide_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Wide_Text_IO.Integer_IO
|
|
Provides input-output facilities for integer types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Short_Integer
|
|
@code{Ada.Short_Short_Integer_Wide_Text_IO}
|
|
@item Short_Integer
|
|
@code{Ada.Short_Integer_Wide_Text_IO}
|
|
@item Integer
|
|
@code{Ada.Integer_Wide_Text_IO}
|
|
@item Long_Integer
|
|
@code{Ada.Long_Integer_Wide_Text_IO}
|
|
@item Long_Long_Integer
|
|
@code{Ada.Long_Long_Integer_Wide_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Wide_Text_IO.Modular_IO
|
|
Provides input-output facilities for modular (unsigned) types
|
|
|
|
@item Ada.Wide_Text_IO.Complex_IO (G.1.3)
|
|
This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
|
|
external file supports wide character representations.
|
|
|
|
@item Ada.Wide_Text_IO.Editing (F.3.4)
|
|
This package is similar to @code{Ada.Text_IO.Editing}, except that the
|
|
types are @code{Wide_Character} and @code{Wide_String} instead of
|
|
@code{Character} and @code{String}.
|
|
|
|
@item Ada.Wide_Text_IO.Streams (A.12.3)
|
|
This package is similar to @code{Ada.Text_IO.Streams}, except that the
|
|
types are @code{Wide_Character} and @code{Wide_String} instead of
|
|
@code{Character} and @code{String}.
|
|
|
|
@item Ada.Wide_Wide_Text_IO (A.11)
|
|
This package is similar to @code{Ada.Text_IO}, except that the external
|
|
file supports wide character representations, and the internal types are
|
|
@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
|
|
and @code{String}. It contains generic subpackages listed next.
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Decimal_IO
|
|
Provides input-output facilities for decimal fixed-point types
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Enumeration_IO
|
|
Provides input-output facilities for enumeration types.
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Fixed_IO
|
|
Provides input-output facilities for ordinary fixed-point types.
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Float_IO
|
|
Provides input-output facilities for float types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Float
|
|
@code{Short_Float_Wide_Wide_Text_IO}
|
|
@item Float
|
|
@code{Float_Wide_Wide_Text_IO}
|
|
@item Long_Float
|
|
@code{Long_Float_Wide_Wide_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Integer_IO
|
|
Provides input-output facilities for integer types. The following
|
|
predefined instantiations of this generic package are available:
|
|
|
|
@table @code
|
|
@item Short_Short_Integer
|
|
@code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
|
|
@item Short_Integer
|
|
@code{Ada.Short_Integer_Wide_Wide_Text_IO}
|
|
@item Integer
|
|
@code{Ada.Integer_Wide_Wide_Text_IO}
|
|
@item Long_Integer
|
|
@code{Ada.Long_Integer_Wide_Wide_Text_IO}
|
|
@item Long_Long_Integer
|
|
@code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
|
|
@end table
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Modular_IO
|
|
Provides input-output facilities for modular (unsigned) types
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
|
|
This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
|
|
external file supports wide character representations.
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
|
|
This package is similar to @code{Ada.Text_IO.Editing}, except that the
|
|
types are @code{Wide_Character} and @code{Wide_String} instead of
|
|
@code{Character} and @code{String}.
|
|
|
|
@item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
|
|
This package is similar to @code{Ada.Text_IO.Streams}, except that the
|
|
types are @code{Wide_Character} and @code{Wide_String} instead of
|
|
@code{Character} and @code{String}.
|
|
@end table
|
|
|
|
@node The Implementation of Standard I/O
|
|
@chapter The Implementation of Standard I/O
|
|
|
|
@noindent
|
|
GNAT implements all the required input-output facilities described in
|
|
A.6 through A.14. These sections of the Ada Reference Manual describe the
|
|
required behavior of these packages from the Ada point of view, and if
|
|
you are writing a portable Ada program that does not need to know the
|
|
exact manner in which Ada maps to the outside world when it comes to
|
|
reading or writing external files, then you do not need to read this
|
|
chapter. As long as your files are all regular files (not pipes or
|
|
devices), and as long as you write and read the files only from Ada, the
|
|
description in the Ada Reference Manual is sufficient.
|
|
|
|
However, if you want to do input-output to pipes or other devices, such
|
|
as the keyboard or screen, or if the files you are dealing with are
|
|
either generated by some other language, or to be read by some other
|
|
language, then you need to know more about the details of how the GNAT
|
|
implementation of these input-output facilities behaves.
|
|
|
|
In this chapter we give a detailed description of exactly how GNAT
|
|
interfaces to the file system. As always, the sources of the system are
|
|
available to you for answering questions at an even more detailed level,
|
|
but for most purposes the information in this chapter will suffice.
|
|
|
|
Another reason that you may need to know more about how input-output is
|
|
implemented arises when you have a program written in mixed languages
|
|
where, for example, files are shared between the C and Ada sections of
|
|
the same program. GNAT provides some additional facilities, in the form
|
|
of additional child library packages, that facilitate this sharing, and
|
|
these additional facilities are also described in this chapter.
|
|
|
|
@menu
|
|
* Standard I/O Packages::
|
|
* FORM Strings::
|
|
* Direct_IO::
|
|
* Sequential_IO::
|
|
* Text_IO::
|
|
* Wide_Text_IO::
|
|
* Wide_Wide_Text_IO::
|
|
* Stream_IO::
|
|
* Text Translation::
|
|
* Shared Files::
|
|
* Filenames encoding::
|
|
* Open Modes::
|
|
* Operations on C Streams::
|
|
* Interfacing to C Streams::
|
|
@end menu
|
|
|
|
@node Standard I/O Packages
|
|
@section Standard I/O Packages
|
|
|
|
@noindent
|
|
The Standard I/O packages described in Annex A for
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Ada.Text_IO
|
|
@item
|
|
Ada.Text_IO.Complex_IO
|
|
@item
|
|
Ada.Text_IO.Text_Streams
|
|
@item
|
|
Ada.Wide_Text_IO
|
|
@item
|
|
Ada.Wide_Text_IO.Complex_IO
|
|
@item
|
|
Ada.Wide_Text_IO.Text_Streams
|
|
@item
|
|
Ada.Wide_Wide_Text_IO
|
|
@item
|
|
Ada.Wide_Wide_Text_IO.Complex_IO
|
|
@item
|
|
Ada.Wide_Wide_Text_IO.Text_Streams
|
|
@item
|
|
Ada.Stream_IO
|
|
@item
|
|
Ada.Sequential_IO
|
|
@item
|
|
Ada.Direct_IO
|
|
@end itemize
|
|
|
|
@noindent
|
|
are implemented using the C
|
|
library streams facility; where
|
|
|
|
@itemize @bullet
|
|
@item
|
|
All files are opened using @code{fopen}.
|
|
@item
|
|
All input/output operations use @code{fread}/@code{fwrite}.
|
|
@end itemize
|
|
|
|
@noindent
|
|
There is no internal buffering of any kind at the Ada library level. The only
|
|
buffering is that provided at the system level in the implementation of the
|
|
library routines that support streams. This facilitates shared use of these
|
|
streams by mixed language programs. Note though that system level buffering is
|
|
explicitly enabled at elaboration of the standard I/O packages and that can
|
|
have an impact on mixed language programs, in particular those using I/O before
|
|
calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
|
|
the Ada elaboration routine before performing any I/O or when impractical,
|
|
flush the common I/O streams and in particular Standard_Output before
|
|
elaborating the Ada code.
|
|
|
|
@node FORM Strings
|
|
@section FORM Strings
|
|
|
|
@noindent
|
|
The format of a FORM string in GNAT is:
|
|
|
|
@smallexample
|
|
"keyword=value,keyword=value,@dots{},keyword=value"
|
|
@end smallexample
|
|
|
|
@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
|
|
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
|
|
The use of these parameters is described later in this section.
|
|
|
|
@node Direct_IO
|
|
@section Direct_IO
|
|
|
|
@noindent
|
|
Direct_IO can only be instantiated for definite types. This is a
|
|
restriction of the Ada language, which means that the records are fixed
|
|
length (the length being determined by @code{@var{type}'Size}, rounded
|
|
up to the next storage unit boundary if necessary).
|
|
|
|
The records of a Direct_IO file are simply written to the file in index
|
|
sequence, with the first record starting at offset zero, and subsequent
|
|
records following. There is no control information of any kind. For
|
|
example, if 32-bit integers are being written, each record takes
|
|
4-bytes, so the record at index @var{K} starts at offset
|
|
(@var{K}@minus{}1)*4.
|
|
|
|
There is no limit on the size of Direct_IO files, they are expanded as
|
|
necessary to accommodate whatever records are written to the file.
|
|
|
|
@node Sequential_IO
|
|
@section Sequential_IO
|
|
|
|
@noindent
|
|
Sequential_IO may be instantiated with either a definite (constrained)
|
|
or indefinite (unconstrained) type.
|
|
|
|
For the definite type case, the elements written to the file are simply
|
|
the memory images of the data values with no control information of any
|
|
kind. The resulting file should be read using the same type, no validity
|
|
checking is performed on input.
|
|
|
|
For the indefinite type case, the elements written consist of two
|
|
parts. First is the size of the data item, written as the memory image
|
|
of a @code{Interfaces.C.size_t} value, followed by the memory image of
|
|
the data value. The resulting file can only be read using the same
|
|
(unconstrained) type. Normal assignment checks are performed on these
|
|
read operations, and if these checks fail, @code{Data_Error} is
|
|
raised. In particular, in the array case, the lengths must match, and in
|
|
the variant record case, if the variable for a particular read operation
|
|
is constrained, the discriminants must match.
|
|
|
|
Note that it is not possible to use Sequential_IO to write variable
|
|
length array items, and then read the data back into different length
|
|
arrays. For example, the following will raise @code{Data_Error}:
|
|
|
|
@smallexample @c ada
|
|
package IO is new Sequential_IO (String);
|
|
F : IO.File_Type;
|
|
S : String (1..4);
|
|
@dots{}
|
|
IO.Create (F)
|
|
IO.Write (F, "hello!")
|
|
IO.Reset (F, Mode=>In_File);
|
|
IO.Read (F, S);
|
|
Put_Line (S);
|
|
|
|
@end smallexample
|
|
|
|
@noindent
|
|
On some Ada implementations, this will print @code{hell}, but the program is
|
|
clearly incorrect, since there is only one element in the file, and that
|
|
element is the string @code{hello!}.
|
|
|
|
In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
|
|
using Stream_IO, and this is the preferred mechanism. In particular, the
|
|
above program fragment rewritten to use Stream_IO will work correctly.
|
|
|
|
@node Text_IO
|
|
@section Text_IO
|
|
|
|
@noindent
|
|
Text_IO files consist of a stream of characters containing the following
|
|
special control characters:
|
|
|
|
@smallexample
|
|
LF (line feed, 16#0A#) Line Mark
|
|
FF (form feed, 16#0C#) Page Mark
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A canonical Text_IO file is defined as one in which the following
|
|
conditions are met:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The character @code{LF} is used only as a line mark, i.e.@: to mark the end
|
|
of the line.
|
|
|
|
@item
|
|
The character @code{FF} is used only as a page mark, i.e.@: to mark the
|
|
end of a page and consequently can appear only immediately following a
|
|
@code{LF} (line mark) character.
|
|
|
|
@item
|
|
The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
|
|
(line mark, page mark). In the former case, the page mark is implicitly
|
|
assumed to be present.
|
|
@end itemize
|
|
|
|
@noindent
|
|
A file written using Text_IO will be in canonical form provided that no
|
|
explicit @code{LF} or @code{FF} characters are written using @code{Put}
|
|
or @code{Put_Line}. There will be no @code{FF} character at the end of
|
|
the file unless an explicit @code{New_Page} operation was performed
|
|
before closing the file.
|
|
|
|
A canonical Text_IO file that is a regular file (i.e., not a device or a
|
|
pipe) can be read using any of the routines in Text_IO@. The
|
|
semantics in this case will be exactly as defined in the Ada Reference
|
|
Manual, and all the routines in Text_IO are fully implemented.
|
|
|
|
A text file that does not meet the requirements for a canonical Text_IO
|
|
file has one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The file contains @code{FF} characters not immediately following a
|
|
@code{LF} character.
|
|
|
|
@item
|
|
The file contains @code{LF} or @code{FF} characters written by
|
|
@code{Put} or @code{Put_Line}, which are not logically considered to be
|
|
line marks or page marks.
|
|
|
|
@item
|
|
The file ends in a character other than @code{LF} or @code{FF},
|
|
i.e.@: there is no explicit line mark or page mark at the end of the file.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Text_IO can be used to read such non-standard text files but subprograms
|
|
to do with line or page numbers do not have defined meanings. In
|
|
particular, a @code{FF} character that does not follow a @code{LF}
|
|
character may or may not be treated as a page mark from the point of
|
|
view of page and line numbering. Every @code{LF} character is considered
|
|
to end a line, and there is an implied @code{LF} character at the end of
|
|
the file.
|
|
|
|
@menu
|
|
* Text_IO Stream Pointer Positioning::
|
|
* Text_IO Reading and Writing Non-Regular Files::
|
|
* Get_Immediate::
|
|
* Treating Text_IO Files as Streams::
|
|
* Text_IO Extensions::
|
|
* Text_IO Facilities for Unbounded Strings::
|
|
@end menu
|
|
|
|
@node Text_IO Stream Pointer Positioning
|
|
@subsection Stream Pointer Positioning
|
|
|
|
@noindent
|
|
@code{Ada.Text_IO} has a definition of current position for a file that
|
|
is being read. No internal buffering occurs in Text_IO, and usually the
|
|
physical position in the stream used to implement the file corresponds
|
|
to this logical position defined by Text_IO@. There are two exceptions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
After a call to @code{End_Of_Page} that returns @code{True}, the stream
|
|
is positioned past the @code{LF} (line mark) that precedes the page
|
|
mark. Text_IO maintains an internal flag so that subsequent read
|
|
operations properly handle the logical position which is unchanged by
|
|
the @code{End_Of_Page} call.
|
|
|
|
@item
|
|
After a call to @code{End_Of_File} that returns @code{True}, if the
|
|
Text_IO file was positioned before the line mark at the end of file
|
|
before the call, then the logical position is unchanged, but the stream
|
|
is physically positioned right at the end of file (past the line mark,
|
|
and past a possible page mark following the line mark. Again Text_IO
|
|
maintains internal flags so that subsequent read operations properly
|
|
handle the logical position.
|
|
@end itemize
|
|
|
|
@noindent
|
|
These discrepancies have no effect on the observable behavior of
|
|
Text_IO, but if a single Ada stream is shared between a C program and
|
|
Ada program, or shared (using @samp{shared=yes} in the form string)
|
|
between two Ada files, then the difference may be observable in some
|
|
situations.
|
|
|
|
@node Text_IO Reading and Writing Non-Regular Files
|
|
@subsection Reading and Writing Non-Regular Files
|
|
|
|
@noindent
|
|
A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
|
|
can be used for reading and writing. Writing is not affected and the
|
|
sequence of characters output is identical to the normal file case, but
|
|
for reading, the behavior of Text_IO is modified to avoid undesirable
|
|
look-ahead as follows:
|
|
|
|
An input file that is not a regular file is considered to have no page
|
|
marks. Any @code{Ascii.FF} characters (the character normally used for a
|
|
page mark) appearing in the file are considered to be data
|
|
characters. In particular:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{Get_Line} and @code{Skip_Line} do not test for a page mark
|
|
following a line mark. If a page mark appears, it will be treated as a
|
|
data character.
|
|
|
|
@item
|
|
This avoids the need to wait for an extra character to be typed or
|
|
entered from the pipe to complete one of these operations.
|
|
|
|
@item
|
|
@code{End_Of_Page} always returns @code{False}
|
|
|
|
@item
|
|
@code{End_Of_File} will return @code{False} if there is a page mark at
|
|
the end of the file.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Output to non-regular files is the same as for regular files. Page marks
|
|
may be written to non-regular files using @code{New_Page}, but as noted
|
|
above they will not be treated as page marks on input if the output is
|
|
piped to another Ada program.
|
|
|
|
Another important discrepancy when reading non-regular files is that the end
|
|
of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
|
|
pressing the @key{EOT} key,
|
|
then end of file
|
|
is signaled once (i.e.@: the test @code{End_Of_File}
|
|
will yield @code{True}, or a read will
|
|
raise @code{End_Error}), but then reading can resume
|
|
to read data past that end of
|
|
file indication, until another end of file indication is entered.
|
|
|
|
@node Get_Immediate
|
|
@subsection Get_Immediate
|
|
@cindex Get_Immediate
|
|
|
|
@noindent
|
|
Get_Immediate returns the next character (including control characters)
|
|
from the input file. In particular, Get_Immediate will return LF or FF
|
|
characters used as line marks or page marks. Such operations leave the
|
|
file positioned past the control character, and it is thus not treated
|
|
as having its normal function. This means that page, line and column
|
|
counts after this kind of Get_Immediate call are set as though the mark
|
|
did not occur. In the case where a Get_Immediate leaves the file
|
|
positioned between the line mark and page mark (which is not normally
|
|
possible), it is undefined whether the FF character will be treated as a
|
|
page mark.
|
|
|
|
@node Treating Text_IO Files as Streams
|
|
@subsection Treating Text_IO Files as Streams
|
|
@cindex Stream files
|
|
|
|
@noindent
|
|
The package @code{Text_IO.Streams} allows a Text_IO file to be treated
|
|
as a stream. Data written to a Text_IO file in this stream mode is
|
|
binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
|
|
16#0C# (@code{FF}), the resulting file may have non-standard
|
|
format. Similarly if read operations are used to read from a Text_IO
|
|
file treated as a stream, then @code{LF} and @code{FF} characters may be
|
|
skipped and the effect is similar to that described above for
|
|
@code{Get_Immediate}.
|
|
|
|
@node Text_IO Extensions
|
|
@subsection Text_IO Extensions
|
|
@cindex Text_IO extensions
|
|
|
|
@noindent
|
|
A package GNAT.IO_Aux in the GNAT library provides some useful extensions
|
|
to the standard @code{Text_IO} package:
|
|
|
|
@itemize @bullet
|
|
@item function File_Exists (Name : String) return Boolean;
|
|
Determines if a file of the given name exists.
|
|
|
|
@item function Get_Line return String;
|
|
Reads a string from the standard input file. The value returned is exactly
|
|
the length of the line that was read.
|
|
|
|
@item function Get_Line (File : Ada.Text_IO.File_Type) return String;
|
|
Similar, except that the parameter File specifies the file from which
|
|
the string is to be read.
|
|
|
|
@end itemize
|
|
|
|
@node Text_IO Facilities for Unbounded Strings
|
|
@subsection Text_IO Facilities for Unbounded Strings
|
|
@cindex Text_IO for unbounded strings
|
|
@cindex Unbounded_String, Text_IO operations
|
|
|
|
@noindent
|
|
The package @code{Ada.Strings.Unbounded.Text_IO}
|
|
in library files @code{a-suteio.ads/adb} contains some GNAT-specific
|
|
subprograms useful for Text_IO operations on unbounded strings:
|
|
|
|
@itemize @bullet
|
|
|
|
@item function Get_Line (File : File_Type) return Unbounded_String;
|
|
Reads a line from the specified file
|
|
and returns the result as an unbounded string.
|
|
|
|
@item procedure Put (File : File_Type; U : Unbounded_String);
|
|
Writes the value of the given unbounded string to the specified file
|
|
Similar to the effect of
|
|
@code{Put (To_String (U))} except that an extra copy is avoided.
|
|
|
|
@item procedure Put_Line (File : File_Type; U : Unbounded_String);
|
|
Writes the value of the given unbounded string to the specified file,
|
|
followed by a @code{New_Line}.
|
|
Similar to the effect of @code{Put_Line (To_String (U))} except
|
|
that an extra copy is avoided.
|
|
@end itemize
|
|
|
|
@noindent
|
|
In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
|
|
and is optional. If the parameter is omitted, then the standard input or
|
|
output file is referenced as appropriate.
|
|
|
|
The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
|
|
files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
|
|
@code{Wide_Text_IO} functionality for unbounded wide strings.
|
|
|
|
The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
|
|
files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
|
|
@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
|
|
|
|
@node Wide_Text_IO
|
|
@section Wide_Text_IO
|
|
|
|
@noindent
|
|
@code{Wide_Text_IO} is similar in most respects to Text_IO, except that
|
|
both input and output files may contain special sequences that represent
|
|
wide character values. The encoding scheme for a given file may be
|
|
specified using a FORM parameter:
|
|
|
|
@smallexample
|
|
WCEM=@var{x}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
as part of the FORM string (WCEM = wide character encoding method),
|
|
where @var{x} is one of the following characters
|
|
|
|
@table @samp
|
|
@item h
|
|
Hex ESC encoding
|
|
@item u
|
|
Upper half encoding
|
|
@item s
|
|
Shift-JIS encoding
|
|
@item e
|
|
EUC Encoding
|
|
@item 8
|
|
UTF-8 encoding
|
|
@item b
|
|
Brackets encoding
|
|
@end table
|
|
|
|
@noindent
|
|
The encoding methods match those that
|
|
can be used in a source
|
|
program, but there is no requirement that the encoding method used for
|
|
the source program be the same as the encoding method used for files,
|
|
and different files may use different encoding methods.
|
|
|
|
The default encoding method for the standard files, and for opened files
|
|
for which no WCEM parameter is given in the FORM string matches the
|
|
wide character encoding specified for the main program (the default
|
|
being brackets encoding if no coding method was specified with -gnatW).
|
|
|
|
@table @asis
|
|
@item Hex Coding
|
|
In this encoding, a wide character is represented by a five character
|
|
sequence:
|
|
|
|
@smallexample
|
|
ESC a b c d
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
|
|
characters (using upper case letters) of the wide character code. For
|
|
example, ESC A345 is used to represent the wide character with code
|
|
16#A345#. This scheme is compatible with use of the full
|
|
@code{Wide_Character} set.
|
|
|
|
@item Upper Half Coding
|
|
The wide character with encoding 16#abcd#, where the upper bit is on
|
|
(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
|
|
16#cd#. The second byte may never be a format control character, but is
|
|
not required to be in the upper half. This method can be also used for
|
|
shift-JIS or EUC where the internal coding matches the external coding.
|
|
|
|
@item Shift JIS Coding
|
|
A wide character is represented by a two character sequence 16#ab# and
|
|
16#cd#, with the restrictions described for upper half encoding as
|
|
described above. The internal character code is the corresponding JIS
|
|
character according to the standard algorithm for Shift-JIS
|
|
conversion. Only characters defined in the JIS code set table can be
|
|
used with this encoding method.
|
|
|
|
@item EUC Coding
|
|
A wide character is represented by a two character sequence 16#ab# and
|
|
16#cd#, with both characters being in the upper half. The internal
|
|
character code is the corresponding JIS character according to the EUC
|
|
encoding algorithm. Only characters defined in the JIS code set table
|
|
can be used with this encoding method.
|
|
|
|
@item UTF-8 Coding
|
|
A wide character is represented using
|
|
UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
|
|
10646-1/Am.2. Depending on the character value, the representation
|
|
is a one, two, or three byte sequence:
|
|
|
|
@smallexample
|
|
16#0000#-16#007f#: 2#0xxxxxxx#
|
|
16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
|
|
16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where the @var{xxx} bits correspond to the left-padded bits of the
|
|
16-bit character value. Note that all lower half ASCII characters
|
|
are represented as ASCII bytes and all upper half characters and
|
|
other wide characters are represented as sequences of upper-half
|
|
(The full UTF-8 scheme allows for encoding 31-bit characters as
|
|
6-byte sequences, but in this implementation, all UTF-8 sequences
|
|
of four or more bytes length will raise a Constraint_Error, as
|
|
will all invalid UTF-8 sequences.)
|
|
|
|
@item Brackets Coding
|
|
In this encoding, a wide character is represented by the following eight
|
|
character sequence:
|
|
|
|
@smallexample
|
|
[ " a b c d " ]
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
|
|
characters (using uppercase letters) of the wide character code. For
|
|
example, @code{["A345"]} is used to represent the wide character with code
|
|
@code{16#A345#}.
|
|
This scheme is compatible with use of the full Wide_Character set.
|
|
On input, brackets coding can also be used for upper half characters,
|
|
e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
|
|
is only used for wide characters with a code greater than @code{16#FF#}.
|
|
|
|
Note that brackets coding is not normally used in the context of
|
|
Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
|
|
a portable way of encoding source files. In the context of Wide_Text_IO
|
|
or Wide_Wide_Text_IO, it can only be used if the file does not contain
|
|
any instance of the left bracket character other than to encode wide
|
|
character values using the brackets encoding method. In practice it is
|
|
expected that some standard wide character encoding method such
|
|
as UTF-8 will be used for text input output.
|
|
|
|
If brackets notation is used, then any occurrence of a left bracket
|
|
in the input file which is not the start of a valid wide character
|
|
sequence will cause Constraint_Error to be raised. It is possible to
|
|
encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
|
|
input will interpret this as a left bracket.
|
|
|
|
However, when a left bracket is output, it will be output as a left bracket
|
|
and not as ["5B"]. We make this decision because for normal use of
|
|
Wide_Text_IO for outputting messages, it is unpleasant to clobber left
|
|
brackets. For example, if we write:
|
|
|
|
@smallexample
|
|
Put_Line ("Start of output [first run]");
|
|
@end smallexample
|
|
|
|
@noindent
|
|
we really do not want to have the left bracket in this message clobbered so
|
|
that the output reads:
|
|
|
|
@smallexample
|
|
Start of output ["5B"]first run]
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In practice brackets encoding is reasonably useful for normal Put_Line use
|
|
since we won't get confused between left brackets and wide character
|
|
sequences in the output. But for input, or when files are written out
|
|
and read back in, it really makes better sense to use one of the standard
|
|
encoding methods such as UTF-8.
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
For the coding schemes other than UTF-8, Hex, or Brackets encoding,
|
|
not all wide character
|
|
values can be represented. An attempt to output a character that cannot
|
|
be represented using the encoding scheme for the file causes
|
|
Constraint_Error to be raised. An invalid wide character sequence on
|
|
input also causes Constraint_Error to be raised.
|
|
|
|
@menu
|
|
* Wide_Text_IO Stream Pointer Positioning::
|
|
* Wide_Text_IO Reading and Writing Non-Regular Files::
|
|
@end menu
|
|
|
|
@node Wide_Text_IO Stream Pointer Positioning
|
|
@subsection Stream Pointer Positioning
|
|
|
|
@noindent
|
|
@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
|
|
of stream pointer positioning (@pxref{Text_IO}). There is one additional
|
|
case:
|
|
|
|
If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
|
|
normal lower ASCII set (i.e.@: a character in the range:
|
|
|
|
@smallexample @c ada
|
|
Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then although the logical position of the file pointer is unchanged by
|
|
the @code{Look_Ahead} call, the stream is physically positioned past the
|
|
wide character sequence. Again this is to avoid the need for buffering
|
|
or backup, and all @code{Wide_Text_IO} routines check the internal
|
|
indication that this situation has occurred so that this is not visible
|
|
to a normal program using @code{Wide_Text_IO}. However, this discrepancy
|
|
can be observed if the wide text file shares a stream with another file.
|
|
|
|
@node Wide_Text_IO Reading and Writing Non-Regular Files
|
|
@subsection Reading and Writing Non-Regular Files
|
|
|
|
@noindent
|
|
As in the case of Text_IO, when a non-regular file is read, it is
|
|
assumed that the file contains no page marks (any form characters are
|
|
treated as data characters), and @code{End_Of_Page} always returns
|
|
@code{False}. Similarly, the end of file indication is not sticky, so
|
|
it is possible to read beyond an end of file.
|
|
|
|
@node Wide_Wide_Text_IO
|
|
@section Wide_Wide_Text_IO
|
|
|
|
@noindent
|
|
@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
|
|
both input and output files may contain special sequences that represent
|
|
wide wide character values. The encoding scheme for a given file may be
|
|
specified using a FORM parameter:
|
|
|
|
@smallexample
|
|
WCEM=@var{x}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
as part of the FORM string (WCEM = wide character encoding method),
|
|
where @var{x} is one of the following characters
|
|
|
|
@table @samp
|
|
@item h
|
|
Hex ESC encoding
|
|
@item u
|
|
Upper half encoding
|
|
@item s
|
|
Shift-JIS encoding
|
|
@item e
|
|
EUC Encoding
|
|
@item 8
|
|
UTF-8 encoding
|
|
@item b
|
|
Brackets encoding
|
|
@end table
|
|
|
|
@noindent
|
|
The encoding methods match those that
|
|
can be used in a source
|
|
program, but there is no requirement that the encoding method used for
|
|
the source program be the same as the encoding method used for files,
|
|
and different files may use different encoding methods.
|
|
|
|
The default encoding method for the standard files, and for opened files
|
|
for which no WCEM parameter is given in the FORM string matches the
|
|
wide character encoding specified for the main program (the default
|
|
being brackets encoding if no coding method was specified with -gnatW).
|
|
|
|
@table @asis
|
|
|
|
@item UTF-8 Coding
|
|
A wide character is represented using
|
|
UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
|
|
10646-1/Am.2. Depending on the character value, the representation
|
|
is a one, two, three, or four byte sequence:
|
|
|
|
@smallexample
|
|
16#000000#-16#00007f#: 2#0xxxxxxx#
|
|
16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
|
|
16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
|
|
16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where the @var{xxx} bits correspond to the left-padded bits of the
|
|
21-bit character value. Note that all lower half ASCII characters
|
|
are represented as ASCII bytes and all upper half characters and
|
|
other wide characters are represented as sequences of upper-half
|
|
characters.
|
|
|
|
@item Brackets Coding
|
|
In this encoding, a wide wide character is represented by the following eight
|
|
character sequence if is in wide character range
|
|
|
|
@smallexample
|
|
[ " a b c d " ]
|
|
@end smallexample
|
|
|
|
and by the following ten character sequence if not
|
|
|
|
@smallexample
|
|
[ " a b c d e f " ]
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
|
|
are the four or six hexadecimal
|
|
characters (using uppercase letters) of the wide wide character code. For
|
|
example, @code{["01A345"]} is used to represent the wide wide character
|
|
with code @code{16#01A345#}.
|
|
|
|
This scheme is compatible with use of the full Wide_Wide_Character set.
|
|
On input, brackets coding can also be used for upper half characters,
|
|
e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
|
|
is only used for wide characters with a code greater than @code{16#FF#}.
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
If is also possible to use the other Wide_Character encoding methods,
|
|
such as Shift-JIS, but the other schemes cannot support the full range
|
|
of wide wide characters.
|
|
An attempt to output a character that cannot
|
|
be represented using the encoding scheme for the file causes
|
|
Constraint_Error to be raised. An invalid wide character sequence on
|
|
input also causes Constraint_Error to be raised.
|
|
|
|
@menu
|
|
* Wide_Wide_Text_IO Stream Pointer Positioning::
|
|
* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
|
|
@end menu
|
|
|
|
@node Wide_Wide_Text_IO Stream Pointer Positioning
|
|
@subsection Stream Pointer Positioning
|
|
|
|
@noindent
|
|
@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
|
|
of stream pointer positioning (@pxref{Text_IO}). There is one additional
|
|
case:
|
|
|
|
If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
|
|
normal lower ASCII set (i.e.@: a character in the range:
|
|
|
|
@smallexample @c ada
|
|
Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
then although the logical position of the file pointer is unchanged by
|
|
the @code{Look_Ahead} call, the stream is physically positioned past the
|
|
wide character sequence. Again this is to avoid the need for buffering
|
|
or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
|
|
indication that this situation has occurred so that this is not visible
|
|
to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
|
|
can be observed if the wide text file shares a stream with another file.
|
|
|
|
@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
|
|
@subsection Reading and Writing Non-Regular Files
|
|
|
|
@noindent
|
|
As in the case of Text_IO, when a non-regular file is read, it is
|
|
assumed that the file contains no page marks (any form characters are
|
|
treated as data characters), and @code{End_Of_Page} always returns
|
|
@code{False}. Similarly, the end of file indication is not sticky, so
|
|
it is possible to read beyond an end of file.
|
|
|
|
@node Stream_IO
|
|
@section Stream_IO
|
|
|
|
@noindent
|
|
A stream file is a sequence of bytes, where individual elements are
|
|
written to the file as described in the Ada Reference Manual. The type
|
|
@code{Stream_Element} is simply a byte. There are two ways to read or
|
|
write a stream file.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The operations @code{Read} and @code{Write} directly read or write a
|
|
sequence of stream elements with no control information.
|
|
|
|
@item
|
|
The stream attributes applied to a stream file transfer data in the
|
|
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
|
|
|
|
@noindent
|
|
Section A.14 of the Ada Reference Manual allows implementations to
|
|
provide a wide variety of behavior if an attempt is made to access the
|
|
same external file with two or more internal files.
|
|
|
|
To provide a full range of functionality, while at the same time
|
|
minimizing the problems of portability caused by this implementation
|
|
dependence, GNAT handles file sharing as follows:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
|
|
to open two or more files with the same full name is considered an error
|
|
and is not supported. The exception @code{Use_Error} will be
|
|
raised. Note that a file that is not explicitly closed by the program
|
|
remains open until the program terminates.
|
|
|
|
@item
|
|
If the form parameter @samp{shared=no} appears in the form string, the
|
|
file can be opened or created with its own separate stream identifier,
|
|
regardless of whether other files sharing the same external file are
|
|
opened. The exact effect depends on how the C stream routines handle
|
|
multiple accesses to the same external files using separate streams.
|
|
|
|
@item
|
|
If the form parameter @samp{shared=yes} appears in the form string for
|
|
each of two or more files opened using the same full name, the same
|
|
stream is shared between these files, and the semantics are as described
|
|
in Ada Reference Manual, Section A.14.
|
|
@end itemize
|
|
|
|
@noindent
|
|
When a program that opens multiple files with the same name is ported
|
|
from another Ada compiler to GNAT, the effect will be that
|
|
@code{Use_Error} is raised.
|
|
|
|
The documentation of the original compiler and the documentation of the
|
|
program should then be examined to determine if file sharing was
|
|
expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
|
|
and @code{Create} calls as required.
|
|
|
|
When a program is ported from GNAT to some other Ada compiler, no
|
|
special attention is required unless the @samp{shared=@var{xxx}} form
|
|
parameter is used in the program. In this case, you must examine the
|
|
documentation of the new compiler to see if it supports the required
|
|
file sharing semantics, and form strings modified appropriately. Of
|
|
course it may be the case that the program cannot be ported if the
|
|
target compiler does not support the required functionality. The best
|
|
approach in writing portable code is to avoid file sharing (and hence
|
|
the use of the @samp{shared=@var{xxx}} parameter in the form string)
|
|
completely.
|
|
|
|
One common use of file sharing in Ada 83 is the use of instantiations of
|
|
Sequential_IO on the same file with different types, to achieve
|
|
heterogeneous input-output. Although this approach will work in GNAT if
|
|
@samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO
|
|
for this purpose (using the stream attributes)
|
|
|
|
@node Filenames encoding
|
|
@section Filenames encoding
|
|
|
|
@noindent
|
|
An encoding form parameter can be used to specify the filename
|
|
encoding @samp{encoding=@var{xxx}}.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the form parameter @samp{encoding=utf8} appears in the form string, the
|
|
filename must be encoded in UTF-8.
|
|
|
|
@item
|
|
If the form parameter @samp{encoding=8bits} appears in the form
|
|
string, the filename must be a standard 8bits string.
|
|
@end itemize
|
|
|
|
In the absence of a @samp{encoding=@var{xxx}} form parameter, the
|
|
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
|
|
|
|
@noindent
|
|
@code{Open} and @code{Create} calls result in a call to @code{fopen}
|
|
using the mode shown in the following table:
|
|
|
|
@sp 2
|
|
@center @code{Open} and @code{Create} Call Modes
|
|
@smallexample
|
|
@b{OPEN } @b{CREATE}
|
|
Append_File "r+" "w+"
|
|
In_File "r" "w+"
|
|
Out_File (Direct_IO) "r+" "w"
|
|
Out_File (all other cases) "w" "w"
|
|
Inout_File "r+" "w+"
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If text file translation is required, then either @samp{b} or @samp{t}
|
|
is added to the mode, depending on the setting of Text. Text file
|
|
translation refers to the mapping of CR/LF sequences in an external file
|
|
to LF characters internally. This mapping only occurs in DOS and
|
|
DOS-like systems, and is not relevant to other systems.
|
|
|
|
A special case occurs with Stream_IO@. As shown in the above table, the
|
|
file is initially opened in @samp{r} or @samp{w} mode for the
|
|
@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
|
|
subsequently requires switching from reading to writing or vice-versa,
|
|
then the file is reopened in @samp{r+} mode to permit the required operation.
|
|
|
|
@node Operations on C Streams
|
|
@section Operations on C Streams
|
|
The package @code{Interfaces.C_Streams} provides an Ada program with direct
|
|
access to the C library functions for operations on C streams:
|
|
|
|
@smallexample @c adanocomment
|
|
package Interfaces.C_Streams is
|
|
-- Note: the reason we do not use the types that are in
|
|
-- Interfaces.C is that we want to avoid dragging in the
|
|
-- code in this unit if possible.
|
|
subtype chars is System.Address;
|
|
-- Pointer to null-terminated array of characters
|
|
subtype FILEs is System.Address;
|
|
-- Corresponds to the C type FILE*
|
|
subtype voids is System.Address;
|
|
-- Corresponds to the C type void*
|
|
subtype int is Integer;
|
|
subtype long is Long_Integer;
|
|
-- Note: the above types are subtypes deliberately, and it
|
|
-- is part of this spec that the above correspondences are
|
|
-- guaranteed. This means that it is legitimate to, for
|
|
-- example, use Integer instead of int. We provide these
|
|
-- synonyms for clarity, but in some cases it may be
|
|
-- convenient to use the underlying types (for example to
|
|
-- avoid an unnecessary dependency of a spec on the spec
|
|
-- of this unit).
|
|
type size_t is mod 2 ** Standard'Address_Size;
|
|
NULL_Stream : constant FILEs;
|
|
-- Value returned (NULL in C) to indicate an
|
|
-- fdopen/fopen/tmpfile error
|
|
----------------------------------
|
|
-- Constants Defined in stdio.h --
|
|
----------------------------------
|
|
EOF : constant int;
|
|
-- Used by a number of routines to indicate error or
|
|
-- end of file
|
|
IOFBF : constant int;
|
|
IOLBF : constant int;
|
|
IONBF : constant int;
|
|
-- Used to indicate buffering mode for setvbuf call
|
|
SEEK_CUR : constant int;
|
|
SEEK_END : constant int;
|
|
SEEK_SET : constant int;
|
|
-- Used to indicate origin for fseek call
|
|
function stdin return FILEs;
|
|
function stdout return FILEs;
|
|
function stderr return FILEs;
|
|
-- Streams associated with standard files
|
|
--------------------------
|
|
-- Standard C functions --
|
|
--------------------------
|
|
-- The functions selected below are ones that are
|
|
-- available in UNIX (but not necessarily in ANSI C).
|
|
-- These are very thin interfaces
|
|
-- which copy exactly the C headers. For more
|
|
-- documentation on these functions, see the Microsoft C
|
|
-- "Run-Time Library Reference" (Microsoft Press, 1990,
|
|
-- ISBN 1-55615-225-6), which includes useful information
|
|
-- on system compatibility.
|
|
procedure clearerr (stream : FILEs);
|
|
function fclose (stream : FILEs) return int;
|
|
function fdopen (handle : int; mode : chars) return FILEs;
|
|
function feof (stream : FILEs) return int;
|
|
function ferror (stream : FILEs) return int;
|
|
function fflush (stream : FILEs) return int;
|
|
function fgetc (stream : FILEs) return int;
|
|
function fgets (strng : chars; n : int; stream : FILEs)
|
|
return chars;
|
|
function fileno (stream : FILEs) return int;
|
|
function fopen (filename : chars; Mode : chars)
|
|
return FILEs;
|
|
-- Note: to maintain target independence, use
|
|
-- text_translation_required, a boolean variable defined in
|
|
-- a-sysdep.c to deal with the target dependent text
|
|
-- translation requirement. If this variable is set,
|
|
-- then b/t should be appended to the standard mode
|
|
-- argument to set the text translation mode off or on
|
|
-- as required.
|
|
function fputc (C : int; stream : FILEs) return int;
|
|
function fputs (Strng : chars; Stream : FILEs) return int;
|
|
function fread
|
|
(buffer : voids;
|
|
size : size_t;
|
|
count : size_t;
|
|
stream : FILEs)
|
|
return size_t;
|
|
function freopen
|
|
(filename : chars;
|
|
mode : chars;
|
|
stream : FILEs)
|
|
return FILEs;
|
|
function fseek
|
|
(stream : FILEs;
|
|
offset : long;
|
|
origin : int)
|
|
return int;
|
|
function ftell (stream : FILEs) return long;
|
|
function fwrite
|
|
(buffer : voids;
|
|
size : size_t;
|
|
count : size_t;
|
|
stream : FILEs)
|
|
return size_t;
|
|
function isatty (handle : int) return int;
|
|
procedure mktemp (template : chars);
|
|
-- The return value (which is just a pointer to template)
|
|
-- is discarded
|
|
procedure rewind (stream : FILEs);
|
|
function rmtmp return int;
|
|
function setvbuf
|
|
(stream : FILEs;
|
|
buffer : chars;
|
|
mode : int;
|
|
size : size_t)
|
|
return int;
|
|
|
|
function tmpfile return FILEs;
|
|
function ungetc (c : int; stream : FILEs) return int;
|
|
function unlink (filename : chars) return int;
|
|
---------------------
|
|
-- Extra functions --
|
|
---------------------
|
|
-- These functions supply slightly thicker bindings than
|
|
-- those above. They are derived from functions in the
|
|
-- C Run-Time Library, but may do a bit more work than
|
|
-- just directly calling one of the Library functions.
|
|
function is_regular_file (handle : int) return int;
|
|
-- Tests if given handle is for a regular file (result 1)
|
|
-- or for a non-regular file (pipe or device, result 0).
|
|
---------------------------------
|
|
-- Control of Text/Binary Mode --
|
|
---------------------------------
|
|
-- If text_translation_required is true, then the following
|
|
-- functions may be used to dynamically switch a file from
|
|
-- binary to text mode or vice versa. These functions have
|
|
-- no effect if text_translation_required is false (i.e.@: in
|
|
-- normal UNIX mode). Use fileno to get a stream handle.
|
|
procedure set_binary_mode (handle : int);
|
|
procedure set_text_mode (handle : int);
|
|
----------------------------
|
|
-- Full Path Name support --
|
|
----------------------------
|
|
procedure full_name (nam : chars; buffer : chars);
|
|
-- Given a NUL terminated string representing a file
|
|
-- name, returns in buffer a NUL terminated string
|
|
-- representing the full path name for the file name.
|
|
-- On systems where it is relevant the drive is also
|
|
-- part of the full path name. It is the responsibility
|
|
-- of the caller to pass an actual parameter for buffer
|
|
-- that is big enough for any full path name. Use
|
|
-- max_path_len given below as the size of buffer.
|
|
max_path_len : integer;
|
|
-- Maximum length of an allowable full path name on the
|
|
-- system, including a terminating NUL character.
|
|
end Interfaces.C_Streams;
|
|
@end smallexample
|
|
|
|
@node Interfacing to C Streams
|
|
@section Interfacing to C Streams
|
|
|
|
@noindent
|
|
The packages in this section permit interfacing Ada files to C Stream
|
|
operations.
|
|
|
|
@smallexample @c ada
|
|
with Interfaces.C_Streams;
|
|
package Ada.Sequential_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Sequential_IO.C_Streams;
|
|
|
|
with Interfaces.C_Streams;
|
|
package Ada.Direct_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Direct_IO.C_Streams;
|
|
|
|
with Interfaces.C_Streams;
|
|
package Ada.Text_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Text_IO.C_Streams;
|
|
|
|
with Interfaces.C_Streams;
|
|
package Ada.Wide_Text_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Wide_Text_IO.C_Streams;
|
|
|
|
with Interfaces.C_Streams;
|
|
package Ada.Wide_Wide_Text_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Wide_Wide_Text_IO.C_Streams;
|
|
|
|
with Interfaces.C_Streams;
|
|
package Ada.Stream_IO.C_Streams is
|
|
function C_Stream (F : File_Type)
|
|
return Interfaces.C_Streams.FILEs;
|
|
procedure Open
|
|
(File : in out File_Type;
|
|
Mode : in File_Mode;
|
|
C_Stream : in Interfaces.C_Streams.FILEs;
|
|
Form : in String := "");
|
|
end Ada.Stream_IO.C_Streams;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In each of these six packages, the @code{C_Stream} function obtains the
|
|
@code{FILE} pointer from a currently opened Ada file. It is then
|
|
possible to use the @code{Interfaces.C_Streams} package to operate on
|
|
this stream, or the stream can be passed to a C program which can
|
|
operate on it directly. Of course the program is responsible for
|
|
ensuring that only appropriate sequences of operations are executed.
|
|
|
|
One particular use of relevance to an Ada program is that the
|
|
@code{setvbuf} function can be used to control the buffering of the
|
|
stream used by an Ada file. In the absence of such a call the standard
|
|
default buffering is used.
|
|
|
|
The @code{Open} procedures in these packages open a file giving an
|
|
existing C Stream instead of a file name. Typically this stream is
|
|
imported from a C program, allowing an Ada file to operate on an
|
|
existing C file.
|
|
|
|
@node The GNAT Library
|
|
@chapter The GNAT Library
|
|
|
|
@noindent
|
|
The GNAT library contains a number of general and special purpose packages.
|
|
It represents functionality that the GNAT developers have found useful, and
|
|
which is made available to GNAT users. The packages described here are fully
|
|
supported, and upwards compatibility will be maintained in future releases,
|
|
so you can use these facilities with the confidence that the same functionality
|
|
will be available in future releases.
|
|
|
|
The chapter here simply gives a brief summary of the facilities available.
|
|
The full documentation is found in the spec file for the package. The full
|
|
sources of these library packages, including both spec and body, are provided
|
|
with all GNAT releases. For example, to find out the full specifications of
|
|
the SPITBOL pattern matching capability, including a full tutorial and
|
|
extensive examples, look in the @file{g-spipat.ads} file in the library.
|
|
|
|
For each entry here, the package name (as it would appear in a @code{with}
|
|
clause) is given, followed by the name of the corresponding spec file in
|
|
parentheses. The packages are children in four hierarchies, @code{Ada},
|
|
@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
|
|
GNAT-specific hierarchy.
|
|
|
|
Note that an application program should only use packages in one of these
|
|
four hierarchies if the package is defined in the Ada Reference Manual,
|
|
or is listed in this section of the GNAT Programmers Reference Manual.
|
|
All other units should be considered internal implementation units and
|
|
should not be directly @code{with}'ed by application code. The use of
|
|
a @code{with} statement that references one of these internal implementation
|
|
units makes an application potentially dependent on changes in versions
|
|
of GNAT, and will generate a warning message.
|
|
|
|
@menu
|
|
* 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-chzla1.ads)::
|
|
* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
|
|
* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
|
|
* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
|
|
* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
|
|
* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
|
|
* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
|
|
* Ada.Containers.Formal_Vectors (a-cofove.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.Unbounded.Text_IO (a-suteio.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.Altivec.Vector_Types (g-alvety.ads)::
|
|
* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
|
|
* GNAT.Array_Split (g-arrspl.ads)::
|
|
* GNAT.AWK (g-awk.ads)::
|
|
* GNAT.Bounded_Buffers (g-boubuf.ads)::
|
|
* GNAT.Bounded_Mailboxes (g-boumai.ads)::
|
|
* GNAT.Bubble_Sort (g-bubsor.ads)::
|
|
* GNAT.Bubble_Sort_A (g-busora.ads)::
|
|
* GNAT.Bubble_Sort_G (g-busorg.ads)::
|
|
* GNAT.Byte_Order_Mark (g-byorma.ads)::
|
|
* GNAT.Byte_Swapping (g-bytswa.ads)::
|
|
* GNAT.Calendar (g-calend.ads)::
|
|
* GNAT.Calendar.Time_IO (g-catiio.ads)::
|
|
* GNAT.Case_Util (g-casuti.ads)::
|
|
* GNAT.CGI (g-cgi.ads)::
|
|
* GNAT.CGI.Cookie (g-cgicoo.ads)::
|
|
* GNAT.CGI.Debug (g-cgideb.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.Decode_String (g-decstr.ads)::
|
|
* GNAT.Decode_UTF8_String (g-deutst.ads)::
|
|
* GNAT.Directory_Operations (g-dirope.ads)::
|
|
* GNAT.Directory_Operations.Iteration (g-diopit.ads)::
|
|
* GNAT.Dynamic_HTables (g-dynhta.ads)::
|
|
* GNAT.Dynamic_Tables (g-dyntab.ads)::
|
|
* GNAT.Encode_String (g-encstr.ads)::
|
|
* GNAT.Encode_UTF8_String (g-enutst.ads)::
|
|
* GNAT.Exception_Actions (g-excact.ads)::
|
|
* GNAT.Exception_Traces (g-exctra.ads)::
|
|
* GNAT.Exceptions (g-except.ads)::
|
|
* GNAT.Expect (g-expect.ads)::
|
|
* GNAT.Expect.TTY (g-exptty.ads)::
|
|
* GNAT.Float_Control (g-flocon.ads)::
|
|
* GNAT.Heap_Sort (g-heasor.ads)::
|
|
* GNAT.Heap_Sort_A (g-hesora.ads)::
|
|
* GNAT.Heap_Sort_G (g-hesorg.ads)::
|
|
* GNAT.HTable (g-htable.ads)::
|
|
* GNAT.IO (g-io.ads)::
|
|
* GNAT.IO_Aux (g-io_aux.ads)::
|
|
* GNAT.Lock_Files (g-locfil.ads)::
|
|
* GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
|
|
* GNAT.MBBS_Float_Random (g-mbflra.ads)::
|
|
* GNAT.MD5 (g-md5.ads)::
|
|
* GNAT.Memory_Dump (g-memdum.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.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.Spelling_Checker (g-speche.ads)::
|
|
* GNAT.Spelling_Checker_Generic (g-spchge.ads)::
|
|
* GNAT.Spitbol.Patterns (g-spipat.ads)::
|
|
* GNAT.Spitbol (g-spitbo.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)::
|
|
* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
|
|
* GNAT.Wide_Spelling_Checker (g-wispch.ads)::
|
|
* GNAT.Wide_String_Split (g-wistsp.ads)::
|
|
* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
|
|
* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
|
|
* Interfaces.C.Extensions (i-cexten.ads)::
|
|
* Interfaces.C.Streams (i-cstrea.ads)::
|
|
* Interfaces.CPP (i-cpp.ads)::
|
|
* Interfaces.Packed_Decimal (i-pacdec.ads)::
|
|
* Interfaces.VxWorks (i-vxwork.ads)::
|
|
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
|
|
* System.Address_Image (s-addima.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)::
|
|
@end menu
|
|
|
|
@node Ada.Characters.Latin_9 (a-chlat9.ads)
|
|
@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
|
|
@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
|
|
@cindex Latin_9 constants for Character
|
|
|
|
@noindent
|
|
This child of @code{Ada.Characters}
|
|
provides a set of definitions corresponding to those in the
|
|
RM-defined package @code{Ada.Characters.Latin_1} but with the
|
|
few modifications required for @code{Latin-9}
|
|
The provision of such a package
|
|
is specifically authorized by the Ada Reference Manual
|
|
(RM A.3.3(27)).
|
|
|
|
@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
|
|
@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
|
|
@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
|
|
@cindex Latin_1 constants for Wide_Character
|
|
|
|
@noindent
|
|
This child of @code{Ada.Characters}
|
|
provides a set of definitions corresponding to those in the
|
|
RM-defined package @code{Ada.Characters.Latin_1} but with the
|
|
types of the constants being @code{Wide_Character}
|
|
instead of @code{Character}. The provision of such a package
|
|
is specifically authorized by the Ada Reference Manual
|
|
(RM A.3.3(27)).
|
|
|
|
@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
|
|
@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
|
|
@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
|
|
@cindex Latin_9 constants for Wide_Character
|
|
|
|
@noindent
|
|
This child of @code{Ada.Characters}
|
|
provides a set of definitions corresponding to those in the
|
|
GNAT defined package @code{Ada.Characters.Latin_9} but with the
|
|
types of the constants being @code{Wide_Character}
|
|
instead of @code{Character}. The provision of such a package
|
|
is specifically authorized by the Ada Reference Manual
|
|
(RM A.3.3(27)).
|
|
|
|
@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
|
|
This child of @code{Ada.Characters}
|
|
provides a set of definitions corresponding to those in the
|
|
RM-defined package @code{Ada.Characters.Latin_1} but with the
|
|
types of the constants being @code{Wide_Wide_Character}
|
|
instead of @code{Character}. The provision of such a package
|
|
is specifically authorized by the Ada Reference Manual
|
|
(RM A.3.3(27)).
|
|
|
|
@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
|
|
This child of @code{Ada.Characters}
|
|
provides a set of definitions corresponding to those in the
|
|
GNAT defined package @code{Ada.Characters.Latin_9} but with the
|
|
types of the constants being @code{Wide_Wide_Character}
|
|
instead of @code{Character}. The provision of such a package
|
|
is specifically authorized by the Ada Reference Manual
|
|
(RM A.3.3(27)).
|
|
|
|
@node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
|
|
@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
|
|
@cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
|
|
@cindex Formal container for doubly linked lists
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for doubly linked lists, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
|
|
@section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
|
|
@cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
|
|
@cindex Formal container for hashed maps
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for hashed maps, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
|
|
@section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
|
|
@cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
|
|
@cindex Formal container for hashed sets
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for hashed sets, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
|
|
@section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
|
|
@cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
|
|
@cindex Formal container for ordered maps
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for ordered maps, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
|
|
@section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
|
|
@cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
|
|
@cindex Formal container for ordered sets
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for ordered sets, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@node Ada.Containers.Formal_Vectors (a-cofove.ads)
|
|
@section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
|
|
@cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
|
|
@cindex Formal container for vectors
|
|
|
|
@noindent
|
|
This child of @code{Ada.Containers} defines a modified version of the Ada 2005
|
|
container for vectors, meant to facilitate formal verification of
|
|
code using such containers.
|
|
|
|
@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})
|
|
@cindex Removing command line arguments
|
|
@cindex Command line, argument removal
|
|
|
|
@noindent
|
|
This child of @code{Ada.Command_Line}
|
|
provides a mechanism for logically removing
|
|
arguments from the argument list. Once removed, an argument is not visible
|
|
to further calls on the subprograms in @code{Ada.Command_Line} will not
|
|
see the removed argument.
|
|
|
|
@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 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})
|
|
@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
|
|
@cindex C Streams, Interfacing with Direct_IO
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Direct_IO}. The stream identifier can be
|
|
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.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
|
|
@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
|
|
@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
|
|
@cindex Null_Occurrence, testing for
|
|
|
|
@noindent
|
|
This child subprogram provides a way of testing for the null
|
|
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})
|
|
@cindex Traceback for Exception Occurrence
|
|
|
|
@noindent
|
|
This child package provides the subprogram (@code{Tracebacks}) to
|
|
give a traceback array of addresses based on an exception
|
|
occurrence.
|
|
|
|
@node Ada.Sequential_IO.C_Streams (a-siocst.ads)
|
|
@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
|
|
@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
|
|
@cindex C Streams, Interfacing with Sequential_IO
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Sequential_IO}. The stream identifier can be
|
|
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.Streams.Stream_IO.C_Streams (a-ssicst.ads)
|
|
@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
|
|
@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
|
|
@cindex C Streams, Interfacing with Stream_IO
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Stream_IO}. The stream identifier can be
|
|
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.Strings.Unbounded.Text_IO (a-suteio.ads)
|
|
@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
|
|
@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
|
|
@cindex @code{Unbounded_String}, IO support
|
|
@cindex @code{Text_IO}, extensions for unbounded strings
|
|
|
|
@noindent
|
|
This package provides subprograms for Text_IO for unbounded
|
|
strings, avoiding the necessity for an intermediate operation
|
|
with ordinary strings.
|
|
|
|
@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
|
|
@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
|
|
@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
|
|
@cindex @code{Unbounded_Wide_String}, IO support
|
|
@cindex @code{Text_IO}, extensions for unbounded wide strings
|
|
|
|
@noindent
|
|
This package provides subprograms for Text_IO for unbounded
|
|
wide strings, avoiding the necessity for an intermediate operation
|
|
with ordinary wide strings.
|
|
|
|
@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
|
|
@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
|
|
@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
|
|
@cindex @code{Unbounded_Wide_Wide_String}, IO support
|
|
@cindex @code{Text_IO}, extensions for unbounded wide wide strings
|
|
|
|
@noindent
|
|
This package provides subprograms for Text_IO for unbounded
|
|
wide wide strings, avoiding the necessity for an intermediate operation
|
|
with ordinary wide wide strings.
|
|
|
|
@node Ada.Text_IO.C_Streams (a-tiocst.ads)
|
|
@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
|
|
@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
|
|
@cindex C Streams, Interfacing with @code{Text_IO}
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Text_IO}. The stream identifier can be
|
|
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})
|
|
@cindex C Streams, Interfacing with @code{Wide_Text_IO}
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Wide_Text_IO}. The stream identifier can be
|
|
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})
|
|
@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
|
|
|
|
@noindent
|
|
This package provides subprograms that allow interfacing between
|
|
C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
|
|
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})
|
|
@cindex AltiVec
|
|
|
|
@noindent
|
|
This is the root package of the GNAT AltiVec binding. It provides
|
|
definitions of constants and types common to all the versions of the
|
|
binding.
|
|
|
|
@node GNAT.Altivec.Conversions (g-altcon.ads)
|
|
@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
|
|
@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
|
|
@cindex AltiVec
|
|
|
|
@noindent
|
|
This package provides the Vector/View conversion routines.
|
|
|
|
@node GNAT.Altivec.Vector_Operations (g-alveop.ads)
|
|
@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
|
|
@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
|
|
@cindex AltiVec
|
|
|
|
@noindent
|
|
This package exposes the Ada interface to the AltiVec operations on
|
|
vector objects. A soft emulation is included by default in the GNAT
|
|
library. The hard binding is provided as a separate package. This unit
|
|
is common to both bindings.
|
|
|
|
@node GNAT.Altivec.Vector_Types (g-alvety.ads)
|
|
@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
|
|
@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
|
|
@cindex AltiVec
|
|
|
|
@noindent
|
|
This package exposes the various vector types part of the Ada binding
|
|
to AltiVec facilities.
|
|
|
|
@node GNAT.Altivec.Vector_Views (g-alvevi.ads)
|
|
@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
|
|
@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
|
|
@cindex AltiVec
|
|
|
|
@noindent
|
|
This package provides public 'View' data types from/to which private
|
|
vector representations can be converted via
|
|
GNAT.Altivec.Conversions. This allows convenient access to individual
|
|
vector elements and provides a simple way to initialize vector
|
|
objects.
|
|
|
|
@node GNAT.Array_Split (g-arrspl.ads)
|
|
@section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
|
|
@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
|
|
@cindex Array splitter
|
|
|
|
@noindent
|
|
Useful array-manipulation routines: given a set of separators, split
|
|
an array wherever the separators appear, and provide direct access
|
|
to the resulting slices.
|
|
|
|
@node GNAT.AWK (g-awk.ads)
|
|
@section @code{GNAT.AWK} (@file{g-awk.ads})
|
|
@cindex @code{GNAT.AWK} (@file{g-awk.ads})
|
|
@cindex Parsing
|
|
@cindex AWK
|
|
|
|
@noindent
|
|
Provides AWK-like parsing functions, with an easy interface for parsing one
|
|
or more files containing formatted data. The file is viewed as a database
|
|
where each record is a line and a field is a data element in this line.
|
|
|
|
@node GNAT.Bounded_Buffers (g-boubuf.ads)
|
|
@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
|
|
@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
|
|
@cindex Parsing
|
|
@cindex Bounded Buffers
|
|
|
|
@noindent
|
|
Provides a concurrent generic bounded buffer abstraction. Instances are
|
|
useful directly or as parts of the implementations of other abstractions,
|
|
such as mailboxes.
|
|
|
|
@node GNAT.Bounded_Mailboxes (g-boumai.ads)
|
|
@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
|
|
@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
|
|
@cindex Parsing
|
|
@cindex Mailboxes
|
|
|
|
@noindent
|
|
Provides a thread-safe asynchronous intertask mailbox communication facility.
|
|
|
|
@node GNAT.Bubble_Sort (g-bubsor.ads)
|
|
@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
|
|
@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
|
|
@cindex Sorting
|
|
@cindex Bubble sort
|
|
|
|
@noindent
|
|
Provides a general implementation of bubble sort usable for sorting arbitrary
|
|
data items. Exchange and comparison procedures are provided by passing
|
|
access-to-procedure values.
|
|
|
|
@node GNAT.Bubble_Sort_A (g-busora.ads)
|
|
@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
|
|
@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
|
|
@cindex Sorting
|
|
@cindex Bubble sort
|
|
|
|
@noindent
|
|
Provides a general implementation of bubble sort usable for sorting arbitrary
|
|
data items. Move and comparison procedures are provided by passing
|
|
access-to-procedure values. This is an older version, retained for
|
|
compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
|
|
|
|
@node GNAT.Bubble_Sort_G (g-busorg.ads)
|
|
@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
|
|
@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
|
|
@cindex Sorting
|
|
@cindex Bubble sort
|
|
|
|
@noindent
|
|
Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
|
|
are provided as generic parameters, this improves efficiency, especially
|
|
if the procedures can be inlined, at the expense of duplicating code for
|
|
multiple instantiations.
|
|
|
|
@node GNAT.Byte_Order_Mark (g-byorma.ads)
|
|
@section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
|
|
@cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
|
|
@cindex UTF-8 representation
|
|
@cindex Wide characte representations
|
|
|
|
@noindent
|
|
Provides a routine which given a string, reads the start of the string to
|
|
see whether it is one of the standard byte order marks (BOM's) which signal
|
|
the encoding of the string. The routine includes detection of special XML
|
|
sequences for various UCS input formats.
|
|
|
|
@node GNAT.Byte_Swapping (g-bytswa.ads)
|
|
@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
|
|
@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
|
|
@cindex Byte swapping
|
|
@cindex Endian
|
|
|
|
@noindent
|
|
General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
|
|
Machine-specific implementations are available in some cases.
|
|
|
|
@node GNAT.Calendar (g-calend.ads)
|
|
@section @code{GNAT.Calendar} (@file{g-calend.ads})
|
|
@cindex @code{GNAT.Calendar} (@file{g-calend.ads})
|
|
@cindex @code{Calendar}
|
|
|
|
@noindent
|
|
Extends the facilities provided by @code{Ada.Calendar} to include handling
|
|
of days of the week, an extended @code{Split} and @code{Time_Of} capability.
|
|
Also provides conversion of @code{Ada.Calendar.Time} values to and from the
|
|
C @code{timeval} format.
|
|
|
|
@node GNAT.Calendar.Time_IO (g-catiio.ads)
|
|
@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
|
|
@cindex @code{Calendar}
|
|
@cindex Time
|
|
@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
|
|
|
|
@node GNAT.CRC32 (g-crc32.ads)
|
|
@section @code{GNAT.CRC32} (@file{g-crc32.ads})
|
|
@cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
|
|
@cindex CRC32
|
|
@cindex Cyclic Redundancy Check
|
|
|
|
@noindent
|
|
This package implements the CRC-32 algorithm. For a full description
|
|
of this algorithm see
|
|
``Computation of Cyclic Redundancy Checks via Table Look-Up'',
|
|
@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
|
|
Aug.@: 1988. Sarwate, D.V@.
|
|
|
|
@node GNAT.Case_Util (g-casuti.ads)
|
|
@section @code{GNAT.Case_Util} (@file{g-casuti.ads})
|
|
@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
|
|
@cindex Casing utilities
|
|
@cindex Character handling (@code{GNAT.Case_Util})
|
|
|
|
@noindent
|
|
A set of simple routines for handling upper and lower casing of strings
|
|
without the overhead of the full casing tables
|
|
in @code{Ada.Characters.Handling}.
|
|
|
|
@node GNAT.CGI (g-cgi.ads)
|
|
@section @code{GNAT.CGI} (@file{g-cgi.ads})
|
|
@cindex @code{GNAT.CGI} (@file{g-cgi.ads})
|
|
@cindex CGI (Common Gateway Interface)
|
|
|
|
@noindent
|
|
This is a package for interfacing a GNAT program with a Web server via the
|
|
Common Gateway Interface (CGI)@. Basically this package parses the CGI
|
|
parameters, which are a set of key/value pairs sent by the Web server. It
|
|
builds a table whose index is the key and provides some services to deal
|
|
with this table.
|
|
|
|
@node GNAT.CGI.Cookie (g-cgicoo.ads)
|
|
@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
|
|
@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
|
|
@cindex CGI (Common Gateway Interface) cookie support
|
|
@cindex Cookie support in CGI
|
|
|
|
@noindent
|
|
This is a package to interface a GNAT program with a Web server via the
|
|
Common Gateway Interface (CGI). It exports services to deal with Web
|
|
cookies (piece of information kept in the Web client software).
|
|
|
|
@node GNAT.CGI.Debug (g-cgideb.ads)
|
|
@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
|
|
@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
|
|
@cindex CGI (Common Gateway Interface) debugging
|
|
|
|
@noindent
|
|
This is a package to help debugging CGI (Common Gateway Interface)
|
|
programs written in Ada.
|
|
|
|
@node GNAT.Command_Line (g-comlin.ads)
|
|
@section @code{GNAT.Command_Line} (@file{g-comlin.ads})
|
|
@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
|
|
@cindex Command line
|
|
|
|
@noindent
|
|
Provides a high level interface to @code{Ada.Command_Line} facilities,
|
|
including the ability to scan for named switches with optional parameters
|
|
and expand file names using wild card notations.
|
|
|
|
@node GNAT.Compiler_Version (g-comver.ads)
|
|
@section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
|
|
@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
|
|
@cindex Compiler Version
|
|
@cindex Version, of compiler
|
|
|
|
@noindent
|
|
Provides a routine for obtaining the version of the compiler used to
|
|
compile the program. More accurately this is the version of the binder
|
|
used to bind the program (this will normally be the same as the version
|
|
of the compiler if a consistent tool set is used to compile all units
|
|
of a partition).
|
|
|
|
@node GNAT.Ctrl_C (g-ctrl_c.ads)
|
|
@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
|
|
@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
|
|
@cindex Interrupt
|
|
|
|
@noindent
|
|
Provides a simple interface to handle Ctrl-C keyboard events.
|
|
|
|
@node GNAT.Current_Exception (g-curexc.ads)
|
|
@section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
|
|
@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
|
|
@cindex Current exception
|
|
@cindex Exception retrieval
|
|
|
|
@noindent
|
|
Provides access to information on the current exception that has been raised
|
|
without the need for using the Ada 95 / Ada 2005 exception choice parameter
|
|
specification syntax.
|
|
This is particularly useful in simulating typical facilities for
|
|
obtaining information about exceptions provided by Ada 83 compilers.
|
|
|
|
@node GNAT.Debug_Pools (g-debpoo.ads)
|
|
@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
|
|
@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
|
|
@cindex Debugging
|
|
@cindex Debug pools
|
|
@cindex Memory corruption debugging
|
|
|
|
@noindent
|
|
Provide a debugging storage pools that helps tracking memory corruption
|
|
problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
|
|
@value{EDITION} User's Guide}.
|
|
|
|
@node GNAT.Debug_Utilities (g-debuti.ads)
|
|
@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
|
|
@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
|
|
@cindex Debugging
|
|
|
|
@noindent
|
|
Provides a few useful utilities for debugging purposes, including conversion
|
|
to and from string images of address values. Supports both C and Ada formats
|
|
for hexadecimal literals.
|
|
|
|
@node GNAT.Decode_String (g-decstr.ads)
|
|
@section @code{GNAT.Decode_String} (@file{g-decstr.ads})
|
|
@cindex @code{GNAT.Decode_String} (@file{g-decstr.ads})
|
|
@cindex Decoding strings
|
|
@cindex String decoding
|
|
@cindex Wide character encoding
|
|
@cindex UTF-8
|
|
@cindex Unicode
|
|
|
|
@noindent
|
|
A generic package providing routines for decoding wide character and wide wide
|
|
character strings encoded as sequences of 8-bit characters using a specified
|
|
encoding method. Includes validation routines, and also routines for stepping
|
|
to next or previous encoded character in an encoded string.
|
|
Useful in conjunction with Unicode character coding. Note there is a
|
|
preinstantiation for UTF-8. See next entry.
|
|
|
|
@node GNAT.Decode_UTF8_String (g-deutst.ads)
|
|
@section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
|
|
@cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
|
|
@cindex Decoding strings
|
|
@cindex Decoding UTF-8 strings
|
|
@cindex UTF-8 string decoding
|
|
@cindex Wide character decoding
|
|
@cindex UTF-8
|
|
@cindex Unicode
|
|
|
|
@noindent
|
|
A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
|
|
|
|
@node GNAT.Directory_Operations (g-dirope.ads)
|
|
@section @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
|
|
@cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
|
|
@cindex Directory operations
|
|
|
|
@noindent
|
|
Provides a set of routines for manipulating directories, including changing
|
|
the current directory, making new directories, and scanning the files in a
|
|
directory.
|
|
|
|
@node GNAT.Directory_Operations.Iteration (g-diopit.ads)
|
|
@section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
|
|
@cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
|
|
@cindex Directory operations iteration
|
|
|
|
@noindent
|
|
A child unit of GNAT.Directory_Operations providing additional operations
|
|
for iterating through directories.
|
|
|
|
@node GNAT.Dynamic_HTables (g-dynhta.ads)
|
|
@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
|
|
@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
|
|
@cindex Hash tables
|
|
|
|
@noindent
|
|
A generic implementation of hash tables that can be used to hash arbitrary
|
|
data. Provided in two forms, a simple form with built in hash functions,
|
|
and a more complex form in which the hash function is supplied.
|
|
|
|
@noindent
|
|
This package provides a facility similar to that of @code{GNAT.HTable},
|
|
except that this package declares a type that can be used to define
|
|
dynamic instances of the hash table, while an instantiation of
|
|
@code{GNAT.HTable} creates a single instance of the hash table.
|
|
|
|
@node GNAT.Dynamic_Tables (g-dyntab.ads)
|
|
@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
|
|
@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
|
|
@cindex Table implementation
|
|
@cindex Arrays, extendable
|
|
|
|
@noindent
|
|
A generic package providing a single dimension array abstraction where the
|
|
length of the array can be dynamically modified.
|
|
|
|
@noindent
|
|
This package provides a facility similar to that of @code{GNAT.Table},
|
|
except that this package declares a type that can be used to define
|
|
dynamic instances of the table, while an instantiation of
|
|
@code{GNAT.Table} creates a single instance of the table type.
|
|
|
|
@node GNAT.Encode_String (g-encstr.ads)
|
|
@section @code{GNAT.Encode_String} (@file{g-encstr.ads})
|
|
@cindex @code{GNAT.Encode_String} (@file{g-encstr.ads})
|
|
@cindex Encoding strings
|
|
@cindex String encoding
|
|
@cindex Wide character encoding
|
|
@cindex UTF-8
|
|
@cindex Unicode
|
|
|
|
@noindent
|
|
A generic package providing routines for encoding wide character and wide
|
|
wide character strings as sequences of 8-bit characters using a specified
|
|
encoding method. Useful in conjunction with Unicode character coding.
|
|
Note there is a preinstantiation for UTF-8. See next entry.
|
|
|
|
@node GNAT.Encode_UTF8_String (g-enutst.ads)
|
|
@section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
|
|
@cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
|
|
@cindex Encoding strings
|
|
@cindex Encoding UTF-8 strings
|
|
@cindex UTF-8 string encoding
|
|
@cindex Wide character encoding
|
|
@cindex UTF-8
|
|
@cindex Unicode
|
|
|
|
@noindent
|
|
A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
|
|
|
|
@node GNAT.Exception_Actions (g-excact.ads)
|
|
@section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
|
|
@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
|
|
@cindex Exception actions
|
|
|
|
@noindent
|
|
Provides callbacks when an exception is raised. Callbacks can be registered
|
|
for specific exceptions, or when any exception is raised. This
|
|
can be used for instance to force a core dump to ease debugging.
|
|
|
|
@node GNAT.Exception_Traces (g-exctra.ads)
|
|
@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
|
|
@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
|
|
@cindex Exception traces
|
|
@cindex Debugging
|
|
|
|
@noindent
|
|
Provides an interface allowing to control automatic output upon exception
|
|
occurrences.
|
|
|
|
@node GNAT.Exceptions (g-except.ads)
|
|
@section @code{GNAT.Exceptions} (@file{g-expect.ads})
|
|
@cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
|
|
@cindex Exceptions, Pure
|
|
@cindex Pure packages, exceptions
|
|
|
|
@noindent
|
|
Normally it is not possible to raise an exception with
|
|
a message from a subprogram in a pure package, since the
|
|
necessary types and subprograms are in @code{Ada.Exceptions}
|
|
which is not a pure unit. @code{GNAT.Exceptions} provides a
|
|
facility for getting around this limitation for a few
|
|
predefined exceptions, and for example allow raising
|
|
@code{Constraint_Error} with a message from a pure subprogram.
|
|
|
|
@node GNAT.Expect (g-expect.ads)
|
|
@section @code{GNAT.Expect} (@file{g-expect.ads})
|
|
@cindex @code{GNAT.Expect} (@file{g-expect.ads})
|
|
|
|
@noindent
|
|
Provides a set of subprograms similar to what is available
|
|
with the standard Tcl Expect tool.
|
|
It allows you to easily spawn and communicate with an external process.
|
|
You can send commands or inputs to the process, and compare the output
|
|
with some expected regular expression. Currently @code{GNAT.Expect}
|
|
is implemented on all native GNAT ports except for OpenVMS@.
|
|
It is not implemented for cross ports, and in particular is not
|
|
implemented for VxWorks or LynxOS@.
|
|
|
|
@node GNAT.Expect.TTY (g-exptty.ads)
|
|
@section @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
|
|
@cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
|
|
|
|
@noindent
|
|
As GNAT.Expect but using pseudo-terminal.
|
|
Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
|
|
ports except for OpenVMS@. It is not implemented for cross ports, and
|
|
in particular is not implemented for VxWorks or LynxOS@.
|
|
|
|
@node GNAT.Float_Control (g-flocon.ads)
|
|
@section @code{GNAT.Float_Control} (@file{g-flocon.ads})
|
|
@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
|
|
@cindex Floating-Point Processor
|
|
|
|
@noindent
|
|
Provides an interface for resetting the floating-point processor into the
|
|
mode required for correct semantic operation in Ada. Some third party
|
|
library calls may cause this mode to be modified, and the Reset procedure
|
|
in this package can be used to reestablish the required mode.
|
|
|
|
@node GNAT.Heap_Sort (g-heasor.ads)
|
|
@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
|
|
@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
|
|
@cindex Sorting
|
|
|
|
@noindent
|
|
Provides a general implementation of heap sort usable for sorting arbitrary
|
|
data items. Exchange and comparison procedures are provided by passing
|
|
access-to-procedure values. The algorithm used is a modified heap sort
|
|
that performs approximately N*log(N) comparisons in the worst case.
|
|
|
|
@node GNAT.Heap_Sort_A (g-hesora.ads)
|
|
@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
|
|
@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
|
|
@cindex Sorting
|
|
|
|
@noindent
|
|
Provides a general implementation of heap sort usable for sorting arbitrary
|
|
data items. Move and comparison procedures are provided by passing
|
|
access-to-procedure values. The algorithm used is a modified heap sort
|
|
that performs approximately N*log(N) comparisons in the worst case.
|
|
This differs from @code{GNAT.Heap_Sort} in having a less convenient
|
|
interface, but may be slightly more efficient.
|
|
|
|
@node GNAT.Heap_Sort_G (g-hesorg.ads)
|
|
@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
|
|
@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
|
|
@cindex Sorting
|
|
|
|
@noindent
|
|
Similar to @code{Heap_Sort_A} except that the move and sorting procedures
|
|
are provided as generic parameters, this improves efficiency, especially
|
|
if the procedures can be inlined, at the expense of duplicating code for
|
|
multiple instantiations.
|
|
|
|
@node GNAT.HTable (g-htable.ads)
|
|
@section @code{GNAT.HTable} (@file{g-htable.ads})
|
|
@cindex @code{GNAT.HTable} (@file{g-htable.ads})
|
|
@cindex Hash tables
|
|
|
|
@noindent
|
|
A generic implementation of hash tables that can be used to hash arbitrary
|
|
data. Provides two approaches, one a simple static approach, and the other
|
|
allowing arbitrary dynamic hash tables.
|
|
|
|
@node GNAT.IO (g-io.ads)
|
|
@section @code{GNAT.IO} (@file{g-io.ads})
|
|
@cindex @code{GNAT.IO} (@file{g-io.ads})
|
|
@cindex Simple I/O
|
|
@cindex Input/Output facilities
|
|
|
|
@noindent
|
|
A simple preelaborable input-output package that provides a subset of
|
|
simple Text_IO functions for reading characters and strings from
|
|
Standard_Input, and writing characters, strings and integers to either
|
|
Standard_Output or Standard_Error.
|
|
|
|
@node GNAT.IO_Aux (g-io_aux.ads)
|
|
@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
|
|
@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
|
|
@cindex Text_IO
|
|
@cindex Input/Output facilities
|
|
|
|
Provides some auxiliary functions for use with Text_IO, including a test
|
|
for whether a file exists, and functions for reading a line of text.
|
|
|
|
@node GNAT.Lock_Files (g-locfil.ads)
|
|
@section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
|
|
@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
|
|
@cindex File locking
|
|
@cindex Locking using files
|
|
|
|
@noindent
|
|
Provides a general interface for using files as locks. Can be used for
|
|
providing program level synchronization.
|
|
|
|
@node GNAT.MBBS_Discrete_Random (g-mbdira.ads)
|
|
@section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
|
|
@cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
|
|
@cindex Random number generation
|
|
|
|
@noindent
|
|
The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
|
|
a modified version of the Blum-Blum-Shub generator.
|
|
|
|
@node GNAT.MBBS_Float_Random (g-mbflra.ads)
|
|
@section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
|
|
@cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
|
|
@cindex Random number generation
|
|
|
|
@noindent
|
|
The original implementation of @code{Ada.Numerics.Float_Random}. Uses
|
|
a modified version of the Blum-Blum-Shub generator.
|
|
|
|
@node GNAT.MD5 (g-md5.ads)
|
|
@section @code{GNAT.MD5} (@file{g-md5.ads})
|
|
@cindex @code{GNAT.MD5} (@file{g-md5.ads})
|
|
@cindex Message Digest MD5
|
|
|
|
@noindent
|
|
Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
|
|
|
|
@node GNAT.Memory_Dump (g-memdum.ads)
|
|
@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
|
|
@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
|
|
@cindex Dump Memory
|
|
|
|
@noindent
|
|
Provides a convenient routine for dumping raw memory to either the
|
|
standard output or standard error files. Uses GNAT.IO for actual
|
|
output.
|
|
|
|
@node GNAT.Most_Recent_Exception (g-moreex.ads)
|
|
@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
|
|
@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
|
|
@cindex Exception, obtaining most recent
|
|
|
|
@noindent
|
|
Provides access to the most recently raised exception. Can be used for
|
|
various logging purposes, including duplicating functionality of some
|
|
Ada 83 implementation dependent extensions.
|
|
|
|
@node GNAT.OS_Lib (g-os_lib.ads)
|
|
@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
|
|
@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
|
|
@cindex Operating System interface
|
|
@cindex Spawn capability
|
|
|
|
@noindent
|
|
Provides a range of target independent operating system interface functions,
|
|
including time/date management, file operations, subprocess management,
|
|
including a portable spawn procedure, and access to environment variables
|
|
and error return codes.
|
|
|
|
@node GNAT.Perfect_Hash_Generators (g-pehage.ads)
|
|
@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
|
|
@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
|
|
@cindex Hash functions
|
|
|
|
@noindent
|
|
Provides a generator of static minimal perfect hash functions. No
|
|
collisions occur and each item can be retrieved from the table in one
|
|
probe (perfect property). The hash table size corresponds to the exact
|
|
size of the key set and no larger (minimal property). The key set has to
|
|
be know in advance (static property). The hash functions are also order
|
|
preserving. If w2 is inserted after w1 in the generator, their
|
|
hashcode are in the same order. These hashing functions are very
|
|
convenient for use with realtime applications.
|
|
|
|
@node GNAT.Random_Numbers (g-rannum.ads)
|
|
@section @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
|
|
@cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
|
|
@cindex Random number generation
|
|
|
|
@noindent
|
|
Provides random number capabilities which extend those available in the
|
|
standard Ada library and are more convenient to use.
|
|
|
|
@node GNAT.Regexp (g-regexp.ads)
|
|
@section @code{GNAT.Regexp} (@file{g-regexp.ads})
|
|
@cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
|
|
@cindex Regular expressions
|
|
@cindex Pattern matching
|
|
|
|
@noindent
|
|
A simple implementation of regular expressions, using a subset of regular
|
|
expression syntax copied from familiar Unix style utilities. This is the
|
|
simples of the three pattern matching packages provided, and is particularly
|
|
suitable for ``file globbing'' applications.
|
|
|
|
@node GNAT.Registry (g-regist.ads)
|
|
@section @code{GNAT.Registry} (@file{g-regist.ads})
|
|
@cindex @code{GNAT.Registry} (@file{g-regist.ads})
|
|
@cindex Windows Registry
|
|
|
|
@noindent
|
|
This is a high level binding to the Windows registry. It is possible to
|
|
do simple things like reading a key value, creating a new key. For full
|
|
registry API, but at a lower level of abstraction, refer to the Win32.Winreg
|
|
package provided with the Win32Ada binding
|
|
|
|
@node GNAT.Regpat (g-regpat.ads)
|
|
@section @code{GNAT.Regpat} (@file{g-regpat.ads})
|
|
@cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
|
|
@cindex Regular expressions
|
|
@cindex Pattern matching
|
|
|
|
@noindent
|
|
A complete implementation of Unix-style regular expression matching, copied
|
|
from the original V7 style regular expression library written in C by
|
|
Henry Spencer (and binary compatible with this C library).
|
|
|
|
@node GNAT.Secondary_Stack_Info (g-sestin.ads)
|
|
@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
|
|
@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
|
|
@cindex Secondary Stack Info
|
|
|
|
@noindent
|
|
Provide the capability to query the high water mark of the current task's
|
|
secondary stack.
|
|
|
|
@node GNAT.Semaphores (g-semaph.ads)
|
|
@section @code{GNAT.Semaphores} (@file{g-semaph.ads})
|
|
@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
|
|
@cindex Semaphores
|
|
|
|
@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 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})
|
|
@cindex @code{GNAT.Signals} (@file{g-signal.ads})
|
|
@cindex Signals
|
|
|
|
@noindent
|
|
Provides the ability to manipulate the blocked status of signals on supported
|
|
targets.
|
|
|
|
@node GNAT.Sockets (g-socket.ads)
|
|
@section @code{GNAT.Sockets} (@file{g-socket.ads})
|
|
@cindex @code{GNAT.Sockets} (@file{g-socket.ads})
|
|
@cindex Sockets
|
|
|
|
@noindent
|
|
A high level and portable interface to develop sockets based applications.
|
|
This package is based on the sockets thin binding found in
|
|
@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
|
|
on all native GNAT ports except for OpenVMS@. It is not implemented
|
|
for the LynxOS@ cross port.
|
|
|
|
@node GNAT.Source_Info (g-souinf.ads)
|
|
@section @code{GNAT.Source_Info} (@file{g-souinf.ads})
|
|
@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
|
|
@cindex Source Information
|
|
|
|
@noindent
|
|
Provides subprograms that give access to source code information known at
|
|
compile time, such as the current file name and line number.
|
|
|
|
@node GNAT.Spelling_Checker (g-speche.ads)
|
|
@section @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
|
|
@cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
|
|
@cindex Spell checking
|
|
|
|
@noindent
|
|
Provides a function for determining whether one string is a plausible
|
|
near misspelling of another string.
|
|
|
|
@node GNAT.Spelling_Checker_Generic (g-spchge.ads)
|
|
@section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
|
|
@cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
|
|
@cindex Spell checking
|
|
|
|
@noindent
|
|
Provides a generic function that can be instantiated with a string type for
|
|
determining whether one string is a plausible near misspelling of another
|
|
string.
|
|
|
|
@node GNAT.Spitbol.Patterns (g-spipat.ads)
|
|
@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
|
|
@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
|
|
@cindex SPITBOL pattern matching
|
|
@cindex Pattern matching
|
|
|
|
@noindent
|
|
A complete implementation of SNOBOL4 style pattern matching. This is the
|
|
most elaborate of the pattern matching packages provided. It fully duplicates
|
|
the SNOBOL4 dynamic pattern construction and matching capabilities, using the
|
|
efficient algorithm developed by Robert Dewar for the SPITBOL system.
|
|
|
|
@node GNAT.Spitbol (g-spitbo.ads)
|
|
@section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
|
|
@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
|
|
@cindex SPITBOL interface
|
|
|
|
@noindent
|
|
The top level package of the collection of SPITBOL-style functionality, this
|
|
package provides basic SNOBOL4 string manipulation functions, such as
|
|
Pad, Reverse, Trim, Substr capability, as well as a generic table function
|
|
useful for constructing arbitrary mappings from strings in the style of
|
|
the SNOBOL4 TABLE function.
|
|
|
|
@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
|
|
@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
|
|
@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
|
|
@cindex Sets of strings
|
|
@cindex SPITBOL Tables
|
|
|
|
@noindent
|
|
A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
|
|
for type @code{Standard.Boolean}, giving an implementation of sets of
|
|
string values.
|
|
|
|
@node GNAT.Spitbol.Table_Integer (g-sptain.ads)
|
|
@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
|
|
@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
|
|
@cindex Integer maps
|
|
@cindex Maps
|
|
@cindex SPITBOL Tables
|
|
|
|
@noindent
|
|
A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
|
|
for type @code{Standard.Integer}, giving an implementation of maps
|
|
from string to integer values.
|
|
|
|
@node GNAT.Spitbol.Table_VString (g-sptavs.ads)
|
|
@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
|
|
@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
|
|
@cindex String maps
|
|
@cindex Maps
|
|
@cindex SPITBOL Tables
|
|
|
|
@noindent
|
|
A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
|
|
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})
|
|
|
|
@noindent
|
|
Common String access types and related subprograms. Basically it
|
|
defines a string access and an array of string access types.
|
|
|
|
@node GNAT.String_Split (g-strspl.ads)
|
|
@section @code{GNAT.String_Split} (@file{g-strspl.ads})
|
|
@cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
|
|
@cindex String splitter
|
|
|
|
@noindent
|
|
Useful string manipulation routines: given a set of separators, split
|
|
a string wherever the separators appear, and provide direct access
|
|
to the resulting slices. This package is instantiated from
|
|
@code{GNAT.Array_Split}.
|
|
|
|
@node GNAT.Table (g-table.ads)
|
|
@section @code{GNAT.Table} (@file{g-table.ads})
|
|
@cindex @code{GNAT.Table} (@file{g-table.ads})
|
|
@cindex Table implementation
|
|
@cindex Arrays, extendable
|
|
|
|
@noindent
|
|
A generic package providing a single dimension array abstraction where the
|
|
length of the array can be dynamically modified.
|
|
|
|
@noindent
|
|
This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
|
|
except that this package declares a single instance of the table type,
|
|
while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
|
|
used to define dynamic instances of the table.
|
|
|
|
@node GNAT.Task_Lock (g-tasloc.ads)
|
|
@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
|
|
@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
|
|
@cindex Task synchronization
|
|
@cindex Task locking
|
|
@cindex Locking
|
|
|
|
@noindent
|
|
A very simple facility for locking and unlocking sections of code using a
|
|
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})
|
|
@cindex Foreign threads
|
|
@cindex Threads, foreign
|
|
|
|
@noindent
|
|
Provides facilities for dealing with foreign threads which need to be known
|
|
by the GNAT run-time system. Consult the documentation of this package for
|
|
further details if your program has threads that are created by a non-Ada
|
|
environment which then accesses Ada code.
|
|
|
|
@node GNAT.Traceback (g-traceb.ads)
|
|
@section @code{GNAT.Traceback} (@file{g-traceb.ads})
|
|
@cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
|
|
@cindex Trace back facilities
|
|
|
|
@noindent
|
|
Provides a facility for obtaining non-symbolic traceback information, useful
|
|
in various debugging situations.
|
|
|
|
@node GNAT.Traceback.Symbolic (g-trasym.ads)
|
|
@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
|
|
@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
|
|
@cindex Trace back facilities
|
|
|
|
@node GNAT.UTF_32 (g-utf_32.ads)
|
|
@section @code{GNAT.UTF_32} (@file{g-table.ads})
|
|
@cindex @code{GNAT.UTF_32} (@file{g-table.ads})
|
|
@cindex Wide character codes
|
|
|
|
@noindent
|
|
This is a package intended to be used in conjunction with the
|
|
@code{Wide_Character} type in Ada 95 and the
|
|
@code{Wide_Wide_Character} type in Ada 2005 (available
|
|
in @code{GNAT} in Ada 2005 mode). This package contains
|
|
Unicode categorization routines, as well as lexical
|
|
categorization routines corresponding to the Ada 2005
|
|
lexical rules for identifiers and strings, and also a
|
|
lower case to upper case fold routine corresponding to
|
|
the Ada 2005 rules for identifier equivalence.
|
|
|
|
@node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)
|
|
@section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
|
|
@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
|
|
@cindex Spell checking
|
|
|
|
@noindent
|
|
Provides a function for determining whether one wide wide string is a plausible
|
|
near misspelling of another wide wide string, where the strings are represented
|
|
using the UTF_32_String type defined in System.Wch_Cnv.
|
|
|
|
@node GNAT.Wide_Spelling_Checker (g-wispch.ads)
|
|
@section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
|
|
@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
|
|
@cindex Spell checking
|
|
|
|
@noindent
|
|
Provides a function for determining whether one wide string is a plausible
|
|
near misspelling of another wide string.
|
|
|
|
@node GNAT.Wide_String_Split (g-wistsp.ads)
|
|
@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
|
|
@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
|
|
@cindex Wide_String splitter
|
|
|
|
@noindent
|
|
Useful wide string manipulation routines: given a set of separators, split
|
|
a wide string wherever the separators appear, and provide direct access
|
|
to the resulting slices. This package is instantiated from
|
|
@code{GNAT.Array_Split}.
|
|
|
|
@node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
|
|
@section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
|
|
@cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
|
|
@cindex Spell checking
|
|
|
|
@noindent
|
|
Provides a function for determining whether one wide wide string is a plausible
|
|
near misspelling of another wide wide string.
|
|
|
|
@node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
|
|
@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
|
|
@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
|
|
@cindex Wide_Wide_String splitter
|
|
|
|
@noindent
|
|
Useful wide wide string manipulation routines: given a set of separators, split
|
|
a wide wide string wherever the separators appear, and provide direct access
|
|
to the resulting slices. This package is instantiated from
|
|
@code{GNAT.Array_Split}.
|
|
|
|
@node Interfaces.C.Extensions (i-cexten.ads)
|
|
@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
|
|
@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
|
|
|
|
@noindent
|
|
This package contains additional C-related definitions, intended
|
|
for use with either manually or automatically generated bindings
|
|
to C libraries.
|
|
|
|
@node Interfaces.C.Streams (i-cstrea.ads)
|
|
@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
|
|
@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
|
|
@cindex C streams, interfacing
|
|
|
|
@noindent
|
|
This package is a binding for the most commonly used operations
|
|
on C streams.
|
|
|
|
@node Interfaces.CPP (i-cpp.ads)
|
|
@section @code{Interfaces.CPP} (@file{i-cpp.ads})
|
|
@cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
|
|
@cindex C++ interfacing
|
|
@cindex Interfacing, to C++
|
|
|
|
@noindent
|
|
This package provides facilities for use in interfacing to C++. It
|
|
is primarily intended to be used in connection with automated tools
|
|
for the generation of C++ interfaces.
|
|
|
|
@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})
|
|
@cindex IBM Packed Format
|
|
@cindex Packed Decimal
|
|
|
|
@noindent
|
|
This package provides a set of routines for conversions to and
|
|
from a packed decimal format compatible with that used on IBM
|
|
mainframes.
|
|
|
|
@node Interfaces.VxWorks (i-vxwork.ads)
|
|
@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
|
|
@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
|
|
@cindex Interfacing to VxWorks
|
|
@cindex VxWorks, interfacing
|
|
|
|
@noindent
|
|
This package provides a limited binding to the VxWorks API.
|
|
In particular, it interfaces with the
|
|
VxWorks hardware interrupt facilities.
|
|
|
|
@node Interfaces.VxWorks.IO (i-vxwoio.ads)
|
|
@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
|
|
@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
|
|
@cindex Interfacing to VxWorks' I/O
|
|
@cindex VxWorks, I/O interfacing
|
|
@cindex VxWorks, Get_Immediate
|
|
@cindex Get_Immediate, VxWorks
|
|
|
|
@noindent
|
|
This package provides a binding to the ioctl (IO/Control)
|
|
function of VxWorks, defining a set of option values and
|
|
function codes. A particular use of this package is
|
|
to enable the use of Get_Immediate under VxWorks.
|
|
|
|
@node System.Address_Image (s-addima.ads)
|
|
@section @code{System.Address_Image} (@file{s-addima.ads})
|
|
@cindex @code{System.Address_Image} (@file{s-addima.ads})
|
|
@cindex Address image
|
|
@cindex Image, of an address
|
|
|
|
@noindent
|
|
This function provides a useful debugging
|
|
function that gives an (implementation dependent)
|
|
string which identifies an address.
|
|
|
|
@node System.Assertions (s-assert.ads)
|
|
@section @code{System.Assertions} (@file{s-assert.ads})
|
|
@cindex @code{System.Assertions} (@file{s-assert.ads})
|
|
@cindex Assertions
|
|
@cindex Assert_Failure, exception
|
|
|
|
@noindent
|
|
This package provides the declaration of the exception raised
|
|
by an run-time assertion failure, as well as the routine that
|
|
is used internally to raise this assertion.
|
|
|
|
@node System.Memory (s-memory.ads)
|
|
@section @code{System.Memory} (@file{s-memory.ads})
|
|
@cindex @code{System.Memory} (@file{s-memory.ads})
|
|
@cindex Memory allocation
|
|
|
|
@noindent
|
|
This package provides the interface to the low level routines used
|
|
by the generated code for allocation and freeing storage for the
|
|
default storage pool (analogous to the C routines malloc and free.
|
|
It also provides a reallocation interface analogous to the C routine
|
|
realloc. The body of this unit may be modified to provide alternative
|
|
allocation mechanisms for the default pool, and in addition, direct
|
|
calls to this unit may be made for low level allocation uses (for
|
|
example see the body of @code{GNAT.Tables}).
|
|
|
|
@node System.Partition_Interface (s-parint.ads)
|
|
@section @code{System.Partition_Interface} (@file{s-parint.ads})
|
|
@cindex @code{System.Partition_Interface} (@file{s-parint.ads})
|
|
@cindex Partition interfacing functions
|
|
|
|
@noindent
|
|
This package provides facilities for partition interfacing. It
|
|
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})
|
|
@cindex Run-time restrictions access
|
|
|
|
@noindent
|
|
This package provides facilities for accessing at run time
|
|
the status of restrictions specified at compile time for
|
|
the partition. Information is available both with regard
|
|
to actual restrictions specified, and with regard to
|
|
compiler determined information on which restrictions
|
|
are violated by one or more packages in the partition.
|
|
|
|
@node System.Rident (s-rident.ads)
|
|
@section @code{System.Rident} (@file{s-rident.ads})
|
|
@cindex @code{System.Rident} (@file{s-rident.ads})
|
|
@cindex Restrictions definitions
|
|
|
|
@noindent
|
|
This package provides definitions of the restrictions
|
|
identifiers supported by GNAT, and also the format of
|
|
the restrictions provided in package System.Restrictions.
|
|
It is not normally necessary to @code{with} this generic package
|
|
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})
|
|
@cindex Task_Info pragma
|
|
|
|
@noindent
|
|
This package provides target dependent functionality that is used
|
|
to support the @code{Task_Info} pragma
|
|
|
|
@node System.Wch_Cnv (s-wchcnv.ads)
|
|
@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
|
|
@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
|
|
@cindex Wide Character, Representation
|
|
@cindex Wide String, Conversion
|
|
@cindex Representation of wide characters
|
|
|
|
@noindent
|
|
This package provides routines for converting between
|
|
wide and wide wide characters and a representation as a value of type
|
|
@code{Standard.String}, using a specified wide character
|
|
encoding method. It uses definitions in
|
|
package @code{System.Wch_Con}.
|
|
|
|
@node System.Wch_Con (s-wchcon.ads)
|
|
@section @code{System.Wch_Con} (@file{s-wchcon.ads})
|
|
@cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
|
|
|
|
@noindent
|
|
This package provides definitions and descriptions of
|
|
the various methods used for encoding wide characters
|
|
in ordinary strings. These definitions are used by
|
|
the package @code{System.Wch_Cnv}.
|
|
|
|
@node Interfacing to Other Languages
|
|
@chapter Interfacing to Other Languages
|
|
@noindent
|
|
The facilities in annex B of the Ada Reference Manual are fully
|
|
implemented in GNAT, and in addition, a full interface to C++ is
|
|
provided.
|
|
|
|
@menu
|
|
* Interfacing to C::
|
|
* Interfacing to C++::
|
|
* Interfacing to COBOL::
|
|
* Interfacing to Fortran::
|
|
* Interfacing to non-GNAT Ada code::
|
|
@end menu
|
|
|
|
@node Interfacing to C
|
|
@section Interfacing to C
|
|
|
|
@noindent
|
|
Interfacing to C with GNAT can use one of two approaches:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The types in the package @code{Interfaces.C} may be used.
|
|
@item
|
|
Standard Ada types may be used directly. This may be less portable to
|
|
other compilers, but will work on all GNAT compilers, which guarantee
|
|
correspondence between the C and Ada types.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Pragma @code{Convention C} may be applied to Ada types, but mostly has no
|
|
effect, since this is the default. The following table shows the
|
|
correspondence between Ada scalar types and the corresponding C types.
|
|
|
|
@table @code
|
|
@item Integer
|
|
@code{int}
|
|
@item Short_Integer
|
|
@code{short}
|
|
@item Short_Short_Integer
|
|
@code{signed char}
|
|
@item Long_Integer
|
|
@code{long}
|
|
@item Long_Long_Integer
|
|
@code{long long}
|
|
@item Short_Float
|
|
@code{float}
|
|
@item Float
|
|
@code{float}
|
|
@item Long_Float
|
|
@code{double}
|
|
@item Long_Long_Float
|
|
This is the longest floating-point type supported by the hardware.
|
|
@end table
|
|
|
|
@noindent
|
|
Additionally, there are the following general correspondences between Ada
|
|
and C types:
|
|
@itemize @bullet
|
|
@item
|
|
Ada enumeration types map to C enumeration types directly if pragma
|
|
@code{Convention C} is specified, which causes them to have int
|
|
length. Without pragma @code{Convention C}, Ada enumeration types map to
|
|
8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
|
|
@code{int}, respectively) depending on the number of values passed.
|
|
This is the only case in which pragma @code{Convention C} affects the
|
|
representation of an Ada type.
|
|
|
|
@item
|
|
Ada access types map to C pointers, except for the case of pointers to
|
|
unconstrained types in Ada, which have no direct C equivalent.
|
|
|
|
@item
|
|
Ada arrays map directly to C arrays.
|
|
|
|
@item
|
|
Ada records map directly to C structures.
|
|
|
|
@item
|
|
Packed Ada records map to C structures where all members are bit fields
|
|
of the length corresponding to the @code{@var{type}'Size} value in Ada.
|
|
@end itemize
|
|
|
|
@node Interfacing to C++
|
|
@section Interfacing to C++
|
|
|
|
@noindent
|
|
The interface to C++ makes use of the following pragmas, which are
|
|
primarily intended to be constructed automatically using a binding generator
|
|
tool, although it is possible to construct them by hand. No suitable binding
|
|
generator tool is supplied with GNAT though.
|
|
|
|
Using these pragmas it is possible to achieve complete
|
|
inter-operability between Ada tagged types and C++ class definitions.
|
|
See @ref{Implementation Defined Pragmas}, for more details.
|
|
|
|
@table @code
|
|
@item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})
|
|
The argument denotes an entity in the current declarative region that is
|
|
declared as a tagged or untagged 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.
|
|
|
|
Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
|
|
for backward compatibility but its functionality is available
|
|
using pragma @code{Import} with @code{Convention} = @code{CPP}.
|
|
|
|
@item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})
|
|
This pragma identifies an imported function (imported in the usual way
|
|
with pragma @code{Import}) as corresponding to a C++ constructor.
|
|
@end table
|
|
|
|
@node Interfacing to COBOL
|
|
@section Interfacing to COBOL
|
|
|
|
@noindent
|
|
Interfacing to COBOL is achieved as described in section B.4 of
|
|
the Ada Reference Manual.
|
|
|
|
@node Interfacing to Fortran
|
|
@section Interfacing to Fortran
|
|
|
|
@noindent
|
|
Interfacing to Fortran is achieved as described in section B.5 of the
|
|
Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
|
|
multi-dimensional array causes the array to be stored in column-major
|
|
order as required for convenient interface to Fortran.
|
|
|
|
@node Interfacing to non-GNAT Ada code
|
|
@section Interfacing to non-GNAT Ada code
|
|
|
|
It is possible to specify the convention @code{Ada} in a pragma
|
|
@code{Import} or pragma @code{Export}. However this refers to
|
|
the calling conventions used by GNAT, which may or may not be
|
|
similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
|
|
compiler to allow interoperation.
|
|
|
|
If arguments types are kept simple, and if the foreign compiler generally
|
|
follows system calling conventions, then it may be possible to integrate
|
|
files compiled by other Ada compilers, provided that the elaboration
|
|
issues are adequately addressed (for example by eliminating the
|
|
need for any load time elaboration).
|
|
|
|
In particular, GNAT running on VMS is designed to
|
|
be highly compatible with the DEC Ada 83 compiler, so this is one
|
|
case in which it is possible to import foreign units of this type,
|
|
provided that the data items passed are restricted to simple scalar
|
|
values or simple record types without variants, or simple array
|
|
types with fixed bounds.
|
|
|
|
@node Specialized Needs Annexes
|
|
@chapter Specialized Needs Annexes
|
|
|
|
@noindent
|
|
Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not
|
|
required in all implementations. However, as described in this chapter,
|
|
GNAT implements all of these annexes:
|
|
|
|
@table @asis
|
|
@item Systems Programming (Annex C)
|
|
The Systems Programming Annex is fully implemented.
|
|
|
|
@item Real-Time Systems (Annex D)
|
|
The Real-Time Systems Annex is fully implemented.
|
|
|
|
@item Distributed Systems (Annex E)
|
|
Stub generation is fully implemented in the GNAT compiler. In addition,
|
|
a complete compatible PCS is available as part of the GLADE system,
|
|
a separate product. When the two
|
|
products are used in conjunction, this annex is fully implemented.
|
|
|
|
@item Information Systems (Annex F)
|
|
The Information Systems annex is fully implemented.
|
|
|
|
@item Numerics (Annex G)
|
|
The Numerics Annex is fully implemented.
|
|
|
|
@item Safety and Security / High-Integrity Systems (Annex H)
|
|
The Safety and Security Annex (termed the High-Integrity Systems Annex
|
|
in Ada 2005) is fully implemented.
|
|
@end table
|
|
|
|
@node Implementation of Specific Ada Features
|
|
@chapter Implementation of Specific Ada Features
|
|
|
|
@noindent
|
|
This chapter describes the GNAT implementation of several Ada language
|
|
facilities.
|
|
|
|
@menu
|
|
* Machine Code Insertions::
|
|
* GNAT Implementation of Tasking::
|
|
* GNAT Implementation of Shared Passive Packages::
|
|
* Code Generation for Array Aggregates::
|
|
* The Size of Discriminated Records with Default Discriminants::
|
|
* Strict Conformance to the Ada Reference Manual::
|
|
@end menu
|
|
|
|
@node Machine Code Insertions
|
|
@section Machine Code Insertions
|
|
@cindex Machine Code insertions
|
|
|
|
@noindent
|
|
Package @code{Machine_Code} provides machine code support as described
|
|
in the Ada Reference Manual in two separate forms:
|
|
@itemize @bullet
|
|
@item
|
|
Machine code statements, consisting of qualified expressions that
|
|
fit the requirements of RM section 13.8.
|
|
@item
|
|
An intrinsic callable procedure, providing an alternative mechanism of
|
|
including machine instructions in a subprogram.
|
|
@end itemize
|
|
|
|
@noindent
|
|
The two features are similar, and both are closely related to the mechanism
|
|
provided by the asm instruction in the GNU C compiler. Full understanding
|
|
and use of the facilities in this package requires understanding the asm
|
|
instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
|
|
Operands, gcc, Using the GNU Compiler Collection (GCC)}.
|
|
|
|
Calls to the function @code{Asm} and the procedure @code{Asm} have identical
|
|
semantic restrictions and effects as described below. Both are provided so
|
|
that the procedure call can be used as a statement, and the function call
|
|
can be used to form a code_statement.
|
|
|
|
The first example given in the GCC documentation is the C @code{asm}
|
|
instruction:
|
|
@smallexample
|
|
asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The equivalent can be written for GNAT as:
|
|
|
|
@smallexample @c ada
|
|
Asm ("fsinx %1 %0",
|
|
My_Float'Asm_Output ("=f", result),
|
|
My_Float'Asm_Input ("f", angle));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The first argument to @code{Asm} is the assembler template, and is
|
|
identical to what is used in GNU C@. This string must be a static
|
|
expression. The second argument is the output operand list. It is
|
|
either a single @code{Asm_Output} attribute reference, or a list of such
|
|
references enclosed in parentheses (technically an array aggregate of
|
|
such references).
|
|
|
|
The @code{Asm_Output} attribute denotes a function that takes two
|
|
parameters. The first is a string, the second is the name of a variable
|
|
of the type designated by the attribute prefix. The first (string)
|
|
argument is required to be a static expression and designates the
|
|
constraint for the parameter (e.g.@: what kind of register is
|
|
required). The second argument is the variable to be updated with the
|
|
result. The possible values for constraint are the same as those used in
|
|
the RTL, and are dependent on the configuration file used to build the
|
|
GCC back end. If there are no output operands, then this argument may
|
|
either be omitted, or explicitly given as @code{No_Output_Operands}.
|
|
|
|
The second argument of @code{@var{my_float}'Asm_Output} functions as
|
|
though it were an @code{out} parameter, which is a little curious, but
|
|
all names have the form of expressions, so there is no syntactic
|
|
irregularity, even though normally functions would not be permitted
|
|
@code{out} parameters. The third argument is the list of input
|
|
operands. It is either a single @code{Asm_Input} attribute reference, or
|
|
a list of such references enclosed in parentheses (technically an array
|
|
aggregate of such references).
|
|
|
|
The @code{Asm_Input} attribute denotes a function that takes two
|
|
parameters. The first is a string, the second is an expression of the
|
|
type designated by the prefix. The first (string) argument is required
|
|
to be a static expression, and is the constraint for the parameter,
|
|
(e.g.@: what kind of register is required). The second argument is the
|
|
value to be used as the input argument. The possible values for the
|
|
constant are the same as those used in the RTL, and are dependent on
|
|
the configuration file used to built the GCC back end.
|
|
|
|
If there are no input operands, this argument may either be omitted, or
|
|
explicitly given as @code{No_Input_Operands}. The fourth argument, not
|
|
present in the above example, is a list of register names, called the
|
|
@dfn{clobber} argument. This argument, if given, must be a static string
|
|
expression, and is a space or comma separated list of names of registers
|
|
that must be considered destroyed as a result of the @code{Asm} call. If
|
|
this argument is the null string (the default value), then the code
|
|
generator assumes that no additional registers are destroyed.
|
|
|
|
The fifth argument, not present in the above example, called the
|
|
@dfn{volatile} argument, is by default @code{False}. It can be set to
|
|
the literal value @code{True} to indicate to the code generator that all
|
|
optimizations with respect to the instruction specified should be
|
|
suppressed, and that in particular, for an instruction that has outputs,
|
|
the instruction will still be generated, even if none of the outputs are
|
|
used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
|
|
gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
|
|
Generally it is strongly advisable to use Volatile for any ASM statement
|
|
that is missing either input or output operands, or when two or more ASM
|
|
statements appear in sequence, to avoid unwanted optimizations. A warning
|
|
is generated if this advice is not followed.
|
|
|
|
The @code{Asm} subprograms may be used in two ways. First the procedure
|
|
forms can be used anywhere a procedure call would be valid, and
|
|
correspond to what the RM calls ``intrinsic'' routines. Such calls can
|
|
be used to intersperse machine instructions with other Ada statements.
|
|
Second, the function forms, which return a dummy value of the limited
|
|
private type @code{Asm_Insn}, can be used in code statements, and indeed
|
|
this is the only context where such calls are allowed. Code statements
|
|
appear as aggregates of the form:
|
|
|
|
@smallexample @c ada
|
|
Asm_Insn'(Asm (@dots{}));
|
|
Asm_Insn'(Asm_Volatile (@dots{}));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In accordance with RM rules, such code statements are allowed only
|
|
within subprograms whose entire body consists of such statements. It is
|
|
not permissible to intermix such statements with other Ada statements.
|
|
|
|
Typically the form using intrinsic procedure calls is more convenient
|
|
and more flexible. The code statement form is provided to meet the RM
|
|
suggestion that such a facility should be made available. The following
|
|
is the exact syntax of the call to @code{Asm}. As usual, if named notation
|
|
is used, the arguments may be given in arbitrary order, following the
|
|
normal rules for use of positional and named arguments)
|
|
|
|
@smallexample
|
|
ASM_CALL ::= Asm (
|
|
[Template =>] static_string_EXPRESSION
|
|
[,[Outputs =>] OUTPUT_OPERAND_LIST ]
|
|
[,[Inputs =>] INPUT_OPERAND_LIST ]
|
|
[,[Clobber =>] static_string_EXPRESSION ]
|
|
[,[Volatile =>] static_boolean_EXPRESSION] )
|
|
|
|
OUTPUT_OPERAND_LIST ::=
|
|
[PREFIX.]No_Output_Operands
|
|
| OUTPUT_OPERAND_ATTRIBUTE
|
|
| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
|
|
|
|
OUTPUT_OPERAND_ATTRIBUTE ::=
|
|
SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
|
|
|
|
INPUT_OPERAND_LIST ::=
|
|
[PREFIX.]No_Input_Operands
|
|
| INPUT_OPERAND_ATTRIBUTE
|
|
| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
|
|
|
|
INPUT_OPERAND_ATTRIBUTE ::=
|
|
SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
|
|
are declared in the package @code{Machine_Code} and must be referenced
|
|
according to normal visibility rules. In particular if there is no
|
|
@code{use} clause for this package, then appropriate package name
|
|
qualification is required.
|
|
|
|
@node GNAT Implementation of Tasking
|
|
@section GNAT Implementation of Tasking
|
|
|
|
@noindent
|
|
This chapter outlines the basic GNAT approach to tasking (in particular,
|
|
a multi-layered library for portability) and discusses issues related
|
|
to compliance with the Real-Time Systems Annex.
|
|
|
|
@menu
|
|
* Mapping Ada Tasks onto the Underlying Kernel Threads::
|
|
* Ensuring Compliance with the Real-Time Annex::
|
|
@end menu
|
|
|
|
@node Mapping Ada Tasks onto the Underlying Kernel Threads
|
|
@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
|
|
|
|
@noindent
|
|
GNAT's run-time support comprises two layers:
|
|
|
|
@itemize @bullet
|
|
@item GNARL (GNAT Run-time Layer)
|
|
@item GNULL (GNAT Low-level Library)
|
|
@end itemize
|
|
|
|
@noindent
|
|
In GNAT, Ada's tasking services rely on a platform and OS independent
|
|
layer known as GNARL@. This code is responsible for implementing the
|
|
correct semantics of Ada's task creation, rendezvous, protected
|
|
operations etc.
|
|
|
|
GNARL decomposes Ada's tasking semantics into simpler lower level
|
|
operations such as create a thread, set the priority of a thread,
|
|
yield, create a lock, lock/unlock, etc. The spec for these low-level
|
|
operations constitutes GNULLI, the GNULL Interface. This interface is
|
|
directly inspired from the POSIX real-time API@.
|
|
|
|
If the underlying executive or OS implements the POSIX standard
|
|
faithfully, the GNULL Interface maps as is to the services offered by
|
|
the underlying kernel. Otherwise, some target dependent glue code maps
|
|
the services offered by the underlying kernel to the semantics expected
|
|
by GNARL@.
|
|
|
|
Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
|
|
key point is that each Ada task is mapped on a thread in the underlying
|
|
kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
|
|
|
|
In addition Ada task priorities map onto the underlying thread priorities.
|
|
Mapping Ada tasks onto the underlying kernel threads has several advantages:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The underlying scheduler is used to schedule the Ada tasks. This
|
|
makes Ada tasks as efficient as kernel threads from a scheduling
|
|
standpoint.
|
|
|
|
@item
|
|
Interaction with code written in C containing threads is eased
|
|
since at the lowest level Ada tasks and C threads map onto the same
|
|
underlying kernel concept.
|
|
|
|
@item
|
|
When an Ada task is blocked during I/O the remaining Ada tasks are
|
|
able to proceed.
|
|
|
|
@item
|
|
On multiprocessor systems Ada tasks can execute in parallel.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Some threads libraries offer a mechanism to fork a new process, with the
|
|
child process duplicating the threads from the parent.
|
|
GNAT does not
|
|
support this functionality when the parent contains more than one task.
|
|
@cindex Forking a new process
|
|
|
|
@node Ensuring Compliance with the Real-Time Annex
|
|
@subsection Ensuring Compliance with the Real-Time Annex
|
|
@cindex Real-Time Systems Annex compliance
|
|
|
|
@noindent
|
|
Although mapping Ada tasks onto
|
|
the underlying threads has significant advantages, it does create some
|
|
complications when it comes to respecting the scheduling semantics
|
|
specified in the real-time annex (Annex D).
|
|
|
|
For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
|
|
scheduling policy states:
|
|
|
|
@quotation
|
|
@emph{When the active priority of a ready task that is not running
|
|
changes, or the setting of its base priority takes effect, the
|
|
task is removed from the ready queue for its old active priority
|
|
and is added at the tail of the ready queue for its new active
|
|
priority, except in the case where the active priority is lowered
|
|
due to the loss of inherited priority, in which case the task is
|
|
added at the head of the ready queue for its new active priority.}
|
|
@end quotation
|
|
|
|
@noindent
|
|
While most kernels do put tasks at the end of the priority queue when
|
|
a task changes its priority, (which respects the main
|
|
FIFO_Within_Priorities requirement), almost none keep a thread at the
|
|
beginning of its priority queue when its priority drops from the loss
|
|
of inherited priority.
|
|
|
|
As a result most vendors have provided incomplete Annex D implementations.
|
|
|
|
The GNAT run-time, has a nice cooperative solution to this problem
|
|
which ensures that accurate FIFO_Within_Priorities semantics are
|
|
respected.
|
|
|
|
The principle is as follows. When an Ada task T is about to start
|
|
running, it checks whether some other Ada task R with the same
|
|
priority as T has been suspended due to the loss of priority
|
|
inheritance. If this is the case, T yields and is placed at the end of
|
|
its priority queue. When R arrives at the front of the queue it
|
|
executes.
|
|
|
|
Note that this simple scheme preserves the relative order of the tasks
|
|
that were ready to execute in the priority queue where R has been
|
|
placed at the end.
|
|
|
|
@node GNAT Implementation of Shared Passive Packages
|
|
@section GNAT Implementation of Shared Passive Packages
|
|
@cindex Shared passive packages
|
|
|
|
@noindent
|
|
GNAT fully implements the pragma @code{Shared_Passive} for
|
|
@cindex pragma @code{Shared_Passive}
|
|
the purpose of designating shared passive packages.
|
|
This allows the use of passive partitions in the
|
|
context described in the Ada Reference Manual; i.e., for communication
|
|
between separate partitions of a distributed application using the
|
|
features in Annex E.
|
|
@cindex Annex E
|
|
@cindex Distribution Systems Annex
|
|
|
|
However, the implementation approach used by GNAT provides for more
|
|
extensive usage as follows:
|
|
|
|
@table @emph
|
|
@item Communication between separate programs
|
|
|
|
This allows separate programs to access the data in passive
|
|
partitions, using protected objects for synchronization where
|
|
needed. The only requirement is that the two programs have a
|
|
common shared file system. It is even possible for programs
|
|
running on different machines with different architectures
|
|
(e.g.@: different endianness) to communicate via the data in
|
|
a passive partition.
|
|
|
|
@item Persistence between program runs
|
|
|
|
The data in a passive package can persist from one run of a
|
|
program to another, so that a later program sees the final
|
|
values stored by a previous run of the same program.
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
The implementation approach used is to store the data in files. A
|
|
separate stream file is created for each object in the package, and
|
|
an access to an object causes the corresponding file to be read or
|
|
written.
|
|
|
|
The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
|
|
@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
|
|
set to the directory to be used for these files.
|
|
The files in this directory
|
|
have names that correspond to their fully qualified names. For
|
|
example, if we have the package
|
|
|
|
@smallexample @c ada
|
|
package X is
|
|
pragma Shared_Passive (X);
|
|
Y : Integer;
|
|
Z : Float;
|
|
end X;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and the environment variable is set to @code{/stemp/}, then the files created
|
|
will have the names:
|
|
|
|
@smallexample
|
|
/stemp/x.y
|
|
/stemp/x.z
|
|
@end smallexample
|
|
|
|
@noindent
|
|
These files are created when a value is initially written to the object, and
|
|
the files are retained until manually deleted. This provides the persistence
|
|
semantics. If no file exists, it means that no partition has assigned a value
|
|
to the variable; in this case the initial value declared in the package
|
|
will be used. This model ensures that there are no issues in synchronizing
|
|
the elaboration process, since elaboration of passive packages elaborates the
|
|
initial values, but does not create the files.
|
|
|
|
The files are written using normal @code{Stream_IO} access.
|
|
If you want to be able
|
|
to communicate between programs or partitions running on different
|
|
architectures, then you should use the XDR versions of the stream attribute
|
|
routines, since these are architecture independent.
|
|
|
|
If active synchronization is required for access to the variables in the
|
|
shared passive package, then as described in the Ada Reference Manual, the
|
|
package may contain protected objects used for this purpose. In this case
|
|
a lock file (whose name is @file{___lock} (three underscores)
|
|
is created in the shared memory directory.
|
|
@cindex @file{___lock} file (for shared passive packages)
|
|
This is used to provide the required locking
|
|
semantics for proper protected object synchronization.
|
|
|
|
As of January 2003, GNAT supports shared passive packages on all platforms
|
|
except for OpenVMS.
|
|
|
|
@node Code Generation for Array Aggregates
|
|
@section Code Generation for Array Aggregates
|
|
|
|
@menu
|
|
* Static constant aggregates with static bounds::
|
|
* Constant aggregates with unconstrained nominal types::
|
|
* Aggregates with static bounds::
|
|
* Aggregates with non-static bounds::
|
|
* Aggregates in assignment statements::
|
|
@end menu
|
|
|
|
@noindent
|
|
Aggregates have a rich syntax and allow the user to specify the values of
|
|
complex data structures by means of a single construct. As a result, the
|
|
code generated for aggregates can be quite complex and involve loops, case
|
|
statements and multiple assignments. In the simplest cases, however, the
|
|
compiler will recognize aggregates whose components and constraints are
|
|
fully static, and in those cases the compiler will generate little or no
|
|
executable code. The following is an outline of the code that GNAT generates
|
|
for various aggregate constructs. For further details, you will find it
|
|
useful to examine the output produced by the -gnatG flag to see the expanded
|
|
source that is input to the code generator. You may also want to examine
|
|
the assembly code generated at various levels of optimization.
|
|
|
|
The code generated for aggregates depends on the context, the component values,
|
|
and the type. In the context of an object declaration the code generated is
|
|
generally simpler than in the case of an assignment. As a general rule, static
|
|
component values and static subtypes also lead to simpler code.
|
|
|
|
@node Static constant aggregates with static bounds
|
|
@subsection Static constant aggregates with static bounds
|
|
|
|
@noindent
|
|
For the declarations:
|
|
@smallexample @c ada
|
|
type One_Dim is array (1..10) of integer;
|
|
ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
GNAT generates no executable code: the constant ar0 is placed in static memory.
|
|
The same is true for constant aggregates with named associations:
|
|
|
|
@smallexample @c ada
|
|
Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
|
|
Cr3 : constant One_Dim := (others => 7777);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The same is true for multidimensional constant arrays such as:
|
|
|
|
@smallexample @c ada
|
|
type two_dim is array (1..3, 1..3) of integer;
|
|
Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The same is true for arrays of one-dimensional arrays: the following are
|
|
static:
|
|
|
|
@smallexample @c ada
|
|
type ar1b is array (1..3) of boolean;
|
|
type ar_ar is array (1..3) of ar1b;
|
|
None : constant ar1b := (others => false); -- fully static
|
|
None2 : constant ar_ar := (1..3 => None); -- fully static
|
|
@end smallexample
|
|
|
|
@noindent
|
|
However, for multidimensional aggregates with named associations, GNAT will
|
|
generate assignments and loops, even if all associations are static. The
|
|
following two declarations generate a loop for the first dimension, and
|
|
individual component assignments for the second dimension:
|
|
|
|
@smallexample @c ada
|
|
Zero1: constant two_dim := (1..3 => (1..3 => 0));
|
|
Zero2: constant two_dim := (others => (others => 0));
|
|
@end smallexample
|
|
|
|
@node Constant aggregates with unconstrained nominal types
|
|
@subsection Constant aggregates with unconstrained nominal types
|
|
|
|
@noindent
|
|
In such cases the aggregate itself establishes the subtype, so that
|
|
associations with @code{others} cannot be used. GNAT determines the
|
|
bounds for the actual subtype of the aggregate, and allocates the
|
|
aggregate statically as well. No code is generated for the following:
|
|
|
|
@smallexample @c ada
|
|
type One_Unc is array (natural range <>) of integer;
|
|
Cr_Unc : constant One_Unc := (12,24,36);
|
|
@end smallexample
|
|
|
|
@node Aggregates with static bounds
|
|
@subsection Aggregates with static bounds
|
|
|
|
@noindent
|
|
In all previous examples the aggregate was the initial (and immutable) value
|
|
of a constant. If the aggregate initializes a variable, then code is generated
|
|
for it as a combination of individual assignments and loops over the target
|
|
object. The declarations
|
|
|
|
@smallexample @c ada
|
|
Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
|
|
Cr_Var2 : One_Dim := (others > -1);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
generate the equivalent of
|
|
|
|
@smallexample @c ada
|
|
Cr_Var1 (1) := 2;
|
|
Cr_Var1 (2) := 3;
|
|
Cr_Var1 (3) := 5;
|
|
Cr_Var1 (4) := 11;
|
|
|
|
for I in Cr_Var2'range loop
|
|
Cr_Var2 (I) := -1;
|
|
end loop;
|
|
@end smallexample
|
|
|
|
@node Aggregates with non-static bounds
|
|
@subsection Aggregates with non-static bounds
|
|
|
|
@noindent
|
|
If the bounds of the aggregate are not statically compatible with the bounds
|
|
of the nominal subtype of the target, then constraint checks have to be
|
|
generated on the bounds. For a multidimensional array, constraint checks may
|
|
have to be applied to sub-arrays individually, if they do not have statically
|
|
compatible subtypes.
|
|
|
|
@node Aggregates in assignment statements
|
|
@subsection Aggregates in assignment statements
|
|
|
|
@noindent
|
|
In general, aggregate assignment requires the construction of a temporary,
|
|
and a copy from the temporary to the target of the assignment. This is because
|
|
it is not always possible to convert the assignment into a series of individual
|
|
component assignments. For example, consider the simple case:
|
|
|
|
@smallexample @c ada
|
|
A := (A(2), A(1));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This cannot be converted into:
|
|
|
|
@smallexample @c ada
|
|
A(1) := A(2);
|
|
A(2) := A(1);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
So the aggregate has to be built first in a separate location, and then
|
|
copied into the target. GNAT recognizes simple cases where this intermediate
|
|
step is not required, and the assignments can be performed in place, directly
|
|
into the target. The following sufficient criteria are applied:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The bounds of the aggregate are static, and the associations are static.
|
|
@item
|
|
The components of the aggregate are static constants, names of
|
|
simple variables that are not renamings, or expressions not involving
|
|
indexed components whose operands obey these rules.
|
|
@end itemize
|
|
|
|
@noindent
|
|
If any of these conditions are violated, the aggregate will be built in
|
|
a temporary (created either by the front-end or the code generator) and then
|
|
that temporary will be copied onto the target.
|
|
|
|
@node The Size of Discriminated Records with Default Discriminants
|
|
@section The Size of Discriminated Records with Default Discriminants
|
|
|
|
@noindent
|
|
If a discriminated type @code{T} has discriminants with default values, it is
|
|
possible to declare an object of this type without providing an explicit
|
|
constraint:
|
|
|
|
@smallexample @c ada
|
|
@group
|
|
type Size is range 1..100;
|
|
|
|
type Rec (D : Size := 15) is record
|
|
Name : String (1..D);
|
|
end T;
|
|
|
|
Word : Rec;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Such an object is said to be @emph{unconstrained}.
|
|
The discriminant of the object
|
|
can be modified by a full assignment to the object, as long as it preserves the
|
|
relation between the value of the discriminant, and the value of the components
|
|
that depend on it:
|
|
|
|
@smallexample @c ada
|
|
@group
|
|
Word := (3, "yes");
|
|
|
|
Word := (5, "maybe");
|
|
|
|
Word := (5, "no"); -- raises Constraint_Error
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
In order to support this behavior efficiently, an unconstrained object is
|
|
given the maximum size that any value of the type requires. In the case
|
|
above, @code{Word} has storage for the discriminant and for
|
|
a @code{String} of length 100.
|
|
It is important to note that unconstrained objects do not require dynamic
|
|
allocation. It would be an improper implementation to place on the heap those
|
|
components whose size depends on discriminants. (This improper implementation
|
|
was used by some Ada83 compilers, where the @code{Name} component above
|
|
would have
|
|
been stored as a pointer to a dynamic string). Following the principle that
|
|
dynamic storage management should never be introduced implicitly,
|
|
an Ada compiler should reserve the full size for an unconstrained declared
|
|
object, and place it on the stack.
|
|
|
|
This maximum size approach
|
|
has been a source of surprise to some users, who expect the default
|
|
values of the discriminants to determine the size reserved for an
|
|
unconstrained object: ``If the default is 15, why should the object occupy
|
|
a larger size?''
|
|
The answer, of course, is that the discriminant may be later modified,
|
|
and its full range of values must be taken into account. This is why the
|
|
declaration:
|
|
|
|
@smallexample
|
|
@group
|
|
type Rec (D : Positive := 15) is record
|
|
Name : String (1..D);
|
|
end record;
|
|
|
|
Too_Large : Rec;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
is flagged by the compiler with a warning:
|
|
an attempt to create @code{Too_Large} will raise @code{Storage_Error},
|
|
because the required size includes @code{Positive'Last}
|
|
bytes. As the first example indicates, the proper approach is to declare an
|
|
index type of ``reasonable'' range so that unconstrained objects are not too
|
|
large.
|
|
|
|
One final wrinkle: if the object is declared to be @code{aliased}, or if it is
|
|
created in the heap by means of an allocator, then it is @emph{not}
|
|
unconstrained:
|
|
it is constrained by the default values of the discriminants, and those values
|
|
cannot be modified by full assignment. This is because in the presence of
|
|
aliasing all views of the object (which may be manipulated by different tasks,
|
|
say) must be consistent, so it is imperative that the object, once created,
|
|
remain invariant.
|
|
|
|
@node Strict Conformance to the Ada Reference Manual
|
|
@section Strict Conformance to the Ada Reference Manual
|
|
|
|
@noindent
|
|
The dynamic semantics defined by the Ada Reference Manual impose a set of
|
|
run-time checks to be generated. By default, the GNAT compiler will insert many
|
|
run-time checks into the compiled code, including most of those required by the
|
|
Ada Reference Manual. However, there are three checks that are not enabled
|
|
in the default mode for efficiency reasons: arithmetic overflow checking for
|
|
integer operations (including division by zero), checks for access before
|
|
elaboration on subprogram calls, and stack overflow checking (most operating
|
|
systems do not perform this check by default).
|
|
|
|
Strict conformance to the Ada Reference Manual can be achieved by adding
|
|
three compiler options for overflow checking for integer operations
|
|
(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
|
|
calls and generic instantiations (@option{-gnatE}), and stack overflow
|
|
checking (@option{-fstack-check}).
|
|
|
|
Note that the result of a floating point arithmetic operation in overflow and
|
|
invalid situations, when the @code{Machine_Overflows} attribute of the result
|
|
type is @code{False}, is to generate IEEE NaN and infinite values. This is the
|
|
case for machines compliant with the IEEE floating-point standard, but on
|
|
machines that are not fully compliant with this standard, such as Alpha, the
|
|
@option{-mieee} compiler flag must be used for achieving IEEE confirming
|
|
behavior (although at the cost of a significant performance penalty), so
|
|
infinite and NaN values are properly generated.
|
|
|
|
|
|
@node Implementation of Ada 2012 Features
|
|
@chapter Implementation of Ada 2012 Features
|
|
@cindex Ada 2012 implementation status
|
|
|
|
This chapter contains a complete list of Ada 2012 features that have been
|
|
implemented as of GNAT version 6.4. Generally, these features are only
|
|
available if the @option{-gnat12} (Ada 2012 features enabled) flag is set
|
|
@cindex @option{-gnat12} option
|
|
or if the configuration pragma @code{Ada_2012} is used.
|
|
@cindex pragma @code{Ada_2012}
|
|
@cindex configuration pragma @code{Ada_2012}
|
|
@cindex @code{Ada_2012} configuration pragma
|
|
However, new pragmas, attributes, and restrictions are
|
|
unconditionally available, since the Ada 95 standard allows the addition of
|
|
new pragmas, attributes, and restrictions (there are exceptions, which are
|
|
documented in the individual descriptions), and also certain packages
|
|
were made available in earlier versions of Ada.
|
|
|
|
An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
|
|
This date shows the implementation date of the feature. Any wavefront
|
|
subsequent to this date will contain the indicated feature, as will any
|
|
subsequent releases. A date of 0000-00-00 means that GNAT has always
|
|
implemented the feature, or implemented it as soon as it appeared as a
|
|
binding interpretation.
|
|
|
|
Each feature corresponds to an Ada Issue (``AI'') approved by the Ada
|
|
standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
|
|
The features are ordered based on the relevant sections of the Ada
|
|
Reference Manual (``RM''). When a given AI relates to multiple points
|
|
in the RM, the earliest is used.
|
|
|
|
A complete description of the AIs may be found in
|
|
@url{www.ada-auth.org/ai05-summary.html}.
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@emph{AI-0176 Quantified expressions (2010-09-29)}
|
|
@cindex AI-0176 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Both universally and existentially quantified expressions are implemented.
|
|
They use the new syntax for iterators proposed in AI05-139-2, as well as
|
|
the standard Ada loop syntax.
|
|
|
|
@noindent
|
|
RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0)
|
|
|
|
@item
|
|
@emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)}
|
|
@cindex AI-0079 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Wide characters in the unicode category @i{other_format} are now allowed in
|
|
source programs between tokens, but not within a token such as an identifier.
|
|
|
|
@noindent
|
|
RM References: 2.01 (4/2) 2.02 (7)
|
|
|
|
@item
|
|
@emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)}
|
|
@cindex AI-0091 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Wide characters in the unicode category @i{other_format} are not permitted
|
|
within an identifier, since this can be a security problem. The error
|
|
message for this case has been improved to be more specific, but GNAT has
|
|
never allowed such characters to appear in identifiers.
|
|
|
|
@noindent
|
|
RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2)
|
|
|
|
@item
|
|
@emph{AI-0100 Placement of pragmas (2010-07-01)}
|
|
@cindex AI-0100 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI is an earlier version of AI-163. It simplifies the rules
|
|
for legal placement of pragmas. In the case of lists that allow pragmas, if
|
|
the list may have no elements, then the list may consist solely of pragmas.
|
|
|
|
@noindent
|
|
RM References: 2.08 (7)
|
|
|
|
@item
|
|
@emph{AI-0163 Pragmas in place of null (2010-07-01)}
|
|
@cindex AI-0163 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A statement sequence may be composed entirely of pragmas. It is no longer
|
|
necessary to add a dummy @code{null} statement to make the sequence legal.
|
|
|
|
@noindent
|
|
RM References: 2.08 (7) 2.08 (16)
|
|
|
|
|
|
@item
|
|
@emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)}
|
|
@cindex AI-0080 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an editorial change only, described as non-testable in the AI.
|
|
|
|
@noindent
|
|
RM References: 3.01 (7)
|
|
|
|
|
|
@item
|
|
@emph{AI-0183 Aspect specifications (2010-08-16)}
|
|
@cindex AI-0183 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Aspect specifications have been fully implemented except for pre and post-
|
|
conditions, and type invariants, which have their own separate AI's. All
|
|
forms of declarations listed in the AI are supported. The following is a
|
|
list of the aspects supported (with GNAT implementation aspects marked)
|
|
|
|
@multitable {@code{Preelaborable_Initialization}} {--GNAT}
|
|
@item @code{Ada_2005} @tab -- GNAT
|
|
@item @code{Ada_2012} @tab -- GNAT
|
|
@item @code{Address} @tab
|
|
@item @code{Alignment} @tab
|
|
@item @code{Atomic} @tab
|
|
@item @code{Atomic_Components} @tab
|
|
@item @code{Bit_Order} @tab
|
|
@item @code{Component_Size} @tab
|
|
@item @code{Discard_Names} @tab
|
|
@item @code{External_Tag} @tab
|
|
@item @code{Favor_Top_Level} @tab -- GNAT
|
|
@item @code{Inline} @tab
|
|
@item @code{Inline_Always} @tab -- GNAT
|
|
@item @code{Invariant} @tab
|
|
@item @code{Machine_Radix} @tab
|
|
@item @code{No_Return} @tab
|
|
@item @code{Object_Size} @tab -- GNAT
|
|
@item @code{Pack} @tab
|
|
@item @code{Persistent_BSS} @tab -- GNAT
|
|
@item @code{Post} @tab
|
|
@item @code{Pre} @tab
|
|
@item @code{Predicate} @tab
|
|
@item @code{Preelaborable_Initialization} @tab
|
|
@item @code{Pure_Function} @tab -- GNAT
|
|
@item @code{Remote_Access_Type} @tab -- GNAT
|
|
@item @code{Shared} @tab -- GNAT
|
|
@item @code{Size} @tab
|
|
@item @code{Storage_Pool} @tab
|
|
@item @code{Storage_Size} @tab
|
|
@item @code{Stream_Size} @tab
|
|
@item @code{Suppress} @tab
|
|
@item @code{Suppress_Debug_Info} @tab -- GNAT
|
|
@item @code{Test_Case} @tab -- GNAT
|
|
@item @code{Unchecked_Union} @tab
|
|
@item @code{Universal_Aliasing} @tab -- GNAT
|
|
@item @code{Unmodified} @tab -- GNAT
|
|
@item @code{Unreferenced} @tab -- GNAT
|
|
@item @code{Unreferenced_Objects} @tab -- GNAT
|
|
@item @code{Unsuppress} @tab
|
|
@item @code{Value_Size} @tab -- GNAT
|
|
@item @code{Volatile} @tab
|
|
@item @code{Volatile_Components}
|
|
@item @code{Warnings} @tab -- GNAT
|
|
@end multitable
|
|
|
|
@noindent
|
|
Note that for aspects with an expression, e.g. @code{Size}, the expression is
|
|
treated like a default expression (visibility is analyzed at the point of
|
|
occurrence of the aspect, but evaluation of the expression occurs at the
|
|
freeze point of the entity involved.
|
|
|
|
@noindent
|
|
RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6)
|
|
3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03
|
|
(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2)
|
|
9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2)
|
|
12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1)
|
|
13.03.01 (0)
|
|
|
|
|
|
@item
|
|
@emph{AI-0128 Inequality is a primitive operation (0000-00-00)}
|
|
@cindex AI-0128 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
If an equality operator ("=") is declared for a type, then the implicitly
|
|
declared inequality operator ("/=") is a primitive operation of the type.
|
|
This is the only reasonable interpretation, and is the one always implemented
|
|
by GNAT, but the RM was not entirely clear in making this point.
|
|
|
|
@noindent
|
|
RM References: 3.02.03 (6) 6.06 (6)
|
|
|
|
@item
|
|
@emph{AI-0003 Qualified expressions as names (2010-07-11)}
|
|
@cindex AI-0003 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
In Ada 2012, a qualified expression is considered to be syntactically a name,
|
|
meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
|
|
useful in disambiguating some cases of overloading.
|
|
|
|
@noindent
|
|
RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
|
|
5.04 (7)
|
|
|
|
@item
|
|
@emph{AI-0120 Constant instance of protected object (0000-00-00)}
|
|
@cindex AI-0120 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an RM editorial change only. The section that lists objects that are
|
|
constant failed to include the current instance of a protected object
|
|
within a protected function. This has always been treated as a constant
|
|
in GNAT.
|
|
|
|
@noindent
|
|
RM References: 3.03 (21)
|
|
|
|
@item
|
|
@emph{AI-0008 General access to constrained objects (0000-00-00)}
|
|
@cindex AI-0008 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The wording in the RM implied that if you have a general access to a
|
|
constrained object, it could be used to modify the discriminants. This was
|
|
obviously not intended. @code{Constraint_Error} should be raised, and GNAT
|
|
has always done so in this situation.
|
|
|
|
@noindent
|
|
RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0093 Additional rules use immutably limited (0000-00-00)}
|
|
@cindex AI-0093 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an editorial change only, to make more widespread use of the Ada 2012
|
|
``immutably limited''.
|
|
|
|
@noindent
|
|
RM References: 3.03 (23.4/3)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0096 Deriving from formal private types (2010-07-20)}
|
|
@cindex AI-0096 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
In general it is illegal for a type derived from a formal limited type to be
|
|
nonlimited. This AI makes an exception to this rule: derivation is legal
|
|
if it appears in the private part of the generic, and the formal type is not
|
|
tagged. If the type is tagged, the legality check must be applied to the
|
|
private part of the package.
|
|
|
|
@noindent
|
|
RM References: 3.04 (5.1/2) 6.02 (7)
|
|
|
|
|
|
@item
|
|
@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
|
|
@cindex AI-0181 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
From Ada 2005 on, soft hyphen is considered a non-graphic character, which
|
|
means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
|
|
@code{Image} and @code{Value} attributes for the character types. Strictly
|
|
speaking this is an inconsistency with Ada 95, but in practice the use of
|
|
these attributes is so obscure that it will not cause problems.
|
|
|
|
@noindent
|
|
RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21)
|
|
|
|
|
|
@item
|
|
@emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)}
|
|
@cindex AI-0182 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI allows @code{Character'Value} to accept the string @code{'?'} where
|
|
@code{?} is any character including non-graphic control characters. GNAT has
|
|
always accepted such strings. It also allows strings such as
|
|
@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
|
|
permission and raises @code{Constraint_Error}, as is certainly still
|
|
permitted.
|
|
|
|
@noindent
|
|
RM References: 3.05 (56/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)}
|
|
@cindex AI-0214 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Ada 2012 relaxes the restriction that forbids discriminants of tagged types
|
|
to have default expressions by allowing them when the type is limited. It
|
|
is often useful to define a default value for a discriminant even though
|
|
it can't be changed by assignment.
|
|
|
|
@noindent
|
|
RM References: 3.07 (9.1/2) 3.07.02 (3)
|
|
|
|
|
|
@item
|
|
@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)}
|
|
@cindex AI-0102 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
It is illegal to assign an anonymous access constant to an anonymous access
|
|
variable. The RM did not have a clear rule to prevent this, but GNAT has
|
|
always generated an error for this usage.
|
|
|
|
@noindent
|
|
RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0158 Generalizing membership tests (2010-09-16)}
|
|
@cindex AI-0158 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI extends the syntax of membership tests to simplify complex conditions
|
|
that can be expressed as membership in a subset of values of any type. It
|
|
introduces syntax for a list of expressions that may be used in loop contexts
|
|
as well.
|
|
|
|
@noindent
|
|
RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27)
|
|
|
|
|
|
@item
|
|
@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
|
|
@cindex AI-0173 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
|
|
with the tag of an abstract type, and @code{False} otherwise.
|
|
|
|
@noindent
|
|
RM References: 3.09 (7.4/2) 3.09 (12.4/2)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0076 function with controlling result (0000-00-00)}
|
|
@cindex AI-0076 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an editorial change only. The RM defines calls with controlling
|
|
results, but uses the term ``function with controlling result'' without an
|
|
explicit definition.
|
|
|
|
@noindent
|
|
RM References: 3.09.02 (2/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0126 Dispatching with no declared operation (0000-00-00)}
|
|
@cindex AI-0126 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies dispatching rules, and simply confirms that dispatching
|
|
executes the operation of the parent type when there is no explicitly or
|
|
implicitly declared operation for the descendant type. This has always been
|
|
the case in all versions of GNAT.
|
|
|
|
@noindent
|
|
RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0097 Treatment of abstract null extension (2010-07-19)}
|
|
@cindex AI-0097 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM as written implied that in some cases it was possible to create an
|
|
object of an abstract type, by having an abstract extension inherit a non-
|
|
abstract constructor from its parent type. This mistake has been corrected
|
|
in GNAT and in the RM, and this construct is now illegal.
|
|
|
|
@noindent
|
|
RM References: 3.09.03 (4/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0203 Extended return cannot be abstract (0000-00-00)}
|
|
@cindex AI-0203 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A return_subtype_indication cannot denote an abstract subtype. GNAT has never
|
|
permitted such usage.
|
|
|
|
@noindent
|
|
RM References: 3.09.03 (8/3)
|
|
|
|
|
|
@item
|
|
@emph{AI-0198 Inheriting abstract operators (0000-00-00)}
|
|
@cindex AI-0198 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI resolves a conflict between two rules involving inherited abstract
|
|
operations and predefined operators. If a derived numeric type inherits
|
|
an abstract operator, it overrides the predefined one. This interpretation
|
|
was always the one implemented in GNAT.
|
|
|
|
@noindent
|
|
RM References: 3.09.03 (4/3)
|
|
|
|
@item
|
|
@emph{AI-0073 Functions returning abstract types (2010-07-10)}
|
|
@cindex AI-0073 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI covers a number of issues regarding returning abstract types. In
|
|
particular generic functions cannot have abstract result types or access
|
|
result types designated an abstract type. There are some other cases which
|
|
are detailed in the AI. Note that this binding interpretation has not been
|
|
retrofitted to operate before Ada 2012 mode, since it caused a significant
|
|
number of regressions.
|
|
|
|
@noindent
|
|
RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0070 Elaboration of interface types (0000-00-00)}
|
|
@cindex AI-0070 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an editorial change only, there are no testable consequences short of
|
|
checking for the absence of generated code for an interface declaration.
|
|
|
|
@noindent
|
|
RM References: 3.09.04 (18/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0208 Characteristics of incomplete views (0000-00-00)}
|
|
@cindex AI-0208 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The wording in the Ada 2005 RM concerning characteristics of incomplete views
|
|
was incorrect and implied that some programs intended to be legal were now
|
|
illegal. GNAT had never considered such programs illegal, so it has always
|
|
implemented the intent of this AI.
|
|
|
|
@noindent
|
|
RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)}
|
|
@cindex AI-0162 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Incomplete types are made more useful by allowing them to be completed by
|
|
private types and private extensions.
|
|
|
|
@noindent
|
|
RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)}
|
|
@cindex AI-0098 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
An unintentional omission in the RM implied some inconsistent restrictions on
|
|
the use of anonymous access to subprogram values. These restrictions were not
|
|
intentional, and have never been enforced by GNAT.
|
|
|
|
@noindent
|
|
RM References: 3.10.01 (6) 3.10.01 (9.2/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)}
|
|
@cindex AI-0199 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A choice list in a record aggregate can include several components of
|
|
(distinct) anonymous access types as long as they have matching designated
|
|
subtypes.
|
|
|
|
@noindent
|
|
RM References: 4.03.01 (16)
|
|
|
|
|
|
@item
|
|
@emph{AI-0220 Needed components for aggregates (0000-00-00)}
|
|
@cindex AI-0220 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI addresses a wording problem in the RM that appears to permit some
|
|
complex cases of aggregates with non-static discriminants. GNAT has always
|
|
implemented the intended semantics.
|
|
|
|
@noindent
|
|
RM References: 4.03.01 (17)
|
|
|
|
@item
|
|
@emph{AI-0147 Conditional expressions (2009-03-29)}
|
|
@cindex AI-0147 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Conditional expressions are permitted. The form of such an expression is:
|
|
|
|
@smallexample
|
|
(@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}])
|
|
@end smallexample
|
|
|
|
The parentheses can be omitted in contexts where parentheses are present
|
|
anyway, such as subprogram arguments and pragma arguments. If the @b{else}
|
|
clause is omitted, @b{else True} is assumed;
|
|
thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent
|
|
@emph{(A implies B)} in standard logic.
|
|
|
|
@noindent
|
|
RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2)
|
|
4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
|
|
@cindex AI-0037 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI confirms that an association of the form @code{Indx => <>} in an
|
|
array aggregate must raise @code{Constraint_Error} if @code{Indx}
|
|
is out of range. The RM specified a range check on other associations, but
|
|
not when the value of the association was defaulted. GNAT has always inserted
|
|
a constraint check on the index value.
|
|
|
|
@noindent
|
|
RM References: 4.03.03 (29)
|
|
|
|
|
|
@item
|
|
@emph{AI-0123 Composability of equality (2010-04-13)}
|
|
@cindex AI-0123 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Equality of untagged record composes, so that the predefined equality for a
|
|
composite type that includes a component of some untagged record type
|
|
@code{R} uses the equality operation of @code{R} (which may be user-defined
|
|
or predefined). This makes the behavior of untagged records identical to that
|
|
of tagged types in this respect.
|
|
|
|
This change is an incompatibility with previous versions of Ada, but it
|
|
corrects a non-uniformity that was often a source of confusion. Analysis of
|
|
a large number of industrial programs indicates that in those rare cases
|
|
where a composite type had an untagged record component with a user-defined
|
|
equality, either there was no use of the composite equality, or else the code
|
|
expected the same composability as for tagged types, and thus had a bug that
|
|
would be fixed by this change.
|
|
|
|
@noindent
|
|
RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24)
|
|
8.05.04 (8)
|
|
|
|
|
|
@item
|
|
@emph{AI-0088 The value of exponentiation (0000-00-00)}
|
|
@cindex AI-0088 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the equivalence rule given for the dynamic semantics of
|
|
exponentiation: the value of the operation can be obtained by repeated
|
|
multiplication, but the operation can be implemented otherwise (for example
|
|
using the familiar divide-by-two-and-square algorithm, even if this is less
|
|
accurate), and does not imply repeated reads of a volatile base.
|
|
|
|
@noindent
|
|
RM References: 4.05.06 (11)
|
|
|
|
@item
|
|
@emph{AI-0188 Case expressions (2010-01-09)}
|
|
@cindex AI-0188 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Case expressions are permitted. This allows use of constructs such as:
|
|
@smallexample
|
|
X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
|
|
|
|
@item
|
|
@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)}
|
|
@cindex AI-0104 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise
|
|
@code{Constraint_Error} because the default value of the allocated object is
|
|
@b{null}. This useless construct is illegal in Ada 2012.
|
|
|
|
@noindent
|
|
RM References: 4.08 (2)
|
|
|
|
@item
|
|
@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)}
|
|
@cindex AI-0157 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Allocation and Deallocation from an empty storage pool (i.e. allocation or
|
|
deallocation of a pointer for which a static storage size clause of zero
|
|
has been given) is now illegal and is detected as such. GNAT
|
|
previously gave a warning but not an error.
|
|
|
|
@noindent
|
|
RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17)
|
|
|
|
@item
|
|
@emph{AI-0179 Statement not required after label (2010-04-10)}
|
|
@cindex AI-0179 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
It is not necessary to have a statement following a label, so a label
|
|
can appear at the end of a statement sequence without the need for putting a
|
|
null statement afterwards, but it is not allowable to have only labels and
|
|
no real statements in a statement sequence.
|
|
|
|
@noindent
|
|
RM References: 5.01 (2)
|
|
|
|
|
|
@item
|
|
@emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)}
|
|
@cindex AI-139-2 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The new syntax for iterating over arrays and containers is now implemented.
|
|
Iteration over containers is for now limited to read-only iterators. Only
|
|
default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}.
|
|
|
|
@noindent
|
|
RM References: 5.05
|
|
|
|
@item
|
|
@emph{AI-0134 Profiles must match for full conformance (0000-00-00)}
|
|
@cindex AI-0134 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
For full conformance, the profiles of anonymous-access-to-subprogram
|
|
parameters must match. GNAT has always enforced this rule.
|
|
|
|
@noindent
|
|
RM References: 6.03.01 (18)
|
|
|
|
@item
|
|
@emph{AI-0207 Mode conformance and access constant (0000-00-00)}
|
|
@cindex AI-0207 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI confirms that access_to_constant indication must match for mode
|
|
conformance. This was implemented in GNAT when the qualifier was originally
|
|
introduced in Ada 2005.
|
|
|
|
@noindent
|
|
RM References: 6.03.01 (16/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)}
|
|
@cindex AI-0046 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
For full conformance, in the case of access parameters, the null exclusion
|
|
must match (either both or neither must have @code{@b{not null}}).
|
|
|
|
@noindent
|
|
RM References: 6.03.02 (18)
|
|
|
|
|
|
@item
|
|
@emph{AI-0118 The association of parameter associations (0000-00-00)}
|
|
@cindex AI-0118 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the rules for named associations in subprogram calls and
|
|
generic instantiations. The rules have been in place since Ada 83.
|
|
|
|
@noindent
|
|
RM References: 6.04.01 (2) 12.03 (9)
|
|
|
|
|
|
@item
|
|
@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
|
|
@cindex AI-0196 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Null exclusion checks are not made for @code{@b{out}} parameters when
|
|
evaluating the actual parameters. GNAT has never generated these checks.
|
|
|
|
@noindent
|
|
RM References: 6.04.01 (13)
|
|
|
|
@item
|
|
@emph{AI-0015 Constant return objects (0000-00-00)}
|
|
@cindex AI-0015 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The return object declared in an @i{extended_return_statement} may be
|
|
declared constant. This was always intended, and GNAT has always allowed it.
|
|
|
|
@noindent
|
|
RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2)
|
|
6.05 (5.7/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0032 Extended return for class-wide functions (0000-00-00)}
|
|
@cindex AI-0032 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
If a function returns a class-wide type, the object of an extended return
|
|
statement can be declared with a specific type that is covered by the class-
|
|
wide type. This has been implemented in GNAT since the introduction of
|
|
extended returns. Note AI-0103 complements this AI by imposing matching
|
|
rules for constrained return types.
|
|
|
|
@noindent
|
|
RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2)
|
|
6.05 (8/2)
|
|
|
|
@item
|
|
@emph{AI-0103 Static matching for extended return (2010-07-23)}
|
|
@cindex AI-0103 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
If the return subtype of a function is an elementary type or a constrained
|
|
type, the subtype indication in an extended return statement must match
|
|
statically this return subtype.
|
|
|
|
@noindent
|
|
RM References: 6.05 (5.2/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)}
|
|
@cindex AI-0058 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM had some incorrect wording implying wrong treatment of abnormal
|
|
completion in an extended return. GNAT has always implemented the intended
|
|
correct semantics as described by this AI.
|
|
|
|
@noindent
|
|
RM References: 6.05 (22/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
|
|
@cindex AI-0050 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The implementation permissions for raising @code{Constraint_Error} early on a function call when it was clear an exception would be raised were over-permissive and allowed mishandling of discriminants in some cases. GNAT did
|
|
not take advantage of these incorrect permissions in any case.
|
|
|
|
@noindent
|
|
RM References: 6.05 (24/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)}
|
|
@cindex AI-0125 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
In Ada 2012, the declaration of a primitive operation of a type extension
|
|
or private extension can also override an inherited primitive that is not
|
|
visible at the point of this declaration.
|
|
|
|
@noindent
|
|
RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2)
|
|
|
|
@item
|
|
@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)}
|
|
@cindex AI-0062 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A full constant may have a null exclusion even if its associated deferred
|
|
constant does not. GNAT has always allowed this.
|
|
|
|
@noindent
|
|
RM References: 7.04 (6/2) 7.04 (7.1/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0178 Incomplete views are limited (0000-00-00)}
|
|
@cindex AI-0178 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the role of incomplete views and plugs an omission in the
|
|
RM. GNAT always correctly restricted the use of incomplete views and types.
|
|
|
|
@noindent
|
|
RM References: 7.05 (3/2) 7.05 (6/2)
|
|
|
|
@item
|
|
@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)}
|
|
@cindex AI-0087 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The actual for a formal nonlimited derived type cannot be limited. In
|
|
particular, a formal derived type that extends a limited interface but which
|
|
is not explicitly limited cannot be instantiated with a limited type.
|
|
|
|
@noindent
|
|
RM References: 7.05 (5/2) 12.05.01 (5.1/2)
|
|
|
|
@item
|
|
@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)}
|
|
@cindex AI-0099 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies that ``needs finalization'' is part of dynamic semantics,
|
|
and therefore depends on the run-time characteristics of an object (i.e. its
|
|
tag) and not on its nominal type. As the AI indicates: ``we do not expect
|
|
this to affect any implementation''.
|
|
|
|
@noindent
|
|
RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0064 Redundant finalization rule (0000-00-00)}
|
|
@cindex AI-0064 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is an editorial change only. The intended behavior is already checked
|
|
by an existing ACATS test, which GNAT has always executed correctly.
|
|
|
|
@noindent
|
|
RM References: 7.06.01 (17.1/1)
|
|
|
|
@item
|
|
@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)}
|
|
@cindex AI-0026 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Record representation clauses concerning Unchecked_Union types cannot mention
|
|
the discriminant of the type. The type of a component declared in the variant
|
|
part of an Unchecked_Union cannot be controlled, have controlled components,
|
|
nor have protected or task parts. If an Unchecked_Union type is declared
|
|
within the body of a generic unit or its descendants, then the type of a
|
|
component declared in the variant part cannot be a formal private type or a
|
|
formal private extension declared within the same generic unit.
|
|
|
|
@noindent
|
|
RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0205 Extended return declares visible name (0000-00-00)}
|
|
@cindex AI-0205 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI corrects a simple omission in the RM. Return objects have always
|
|
been visible within an extended return statement.
|
|
|
|
@noindent
|
|
RM References: 8.03 (17)
|
|
|
|
|
|
@item
|
|
@emph{AI-0042 Overriding versus implemented-by (0000-00-00)}
|
|
@cindex AI-0042 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI fixes a wording gap in the RM. An operation of a synchronized
|
|
interface can be implemented by a protected or task entry, but the abstract
|
|
operation is not being overridden in the usual sense, and it must be stated
|
|
separately that this implementation is legal. This has always been the case
|
|
in GNAT.
|
|
|
|
@noindent
|
|
RM References: 9.01 (9.2/2) 9.04 (11.1/2)
|
|
|
|
@item
|
|
@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)}
|
|
@cindex AI-0030 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Requeue is permitted to a protected, synchronized or task interface primitive
|
|
providing it is known that the overriding operation is an entry. Otherwise
|
|
the requeue statement has the same effect as a procedure call. Use of pragma
|
|
@code{Implemented} provides a way to impose a static requirement on the
|
|
overriding operation by adhering to one of the implementation kinds: entry,
|
|
protected procedure or any of the above.
|
|
|
|
@noindent
|
|
RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5)
|
|
9.05.04 (6) 9.05.04 (7) 9.05.04 (12)
|
|
|
|
|
|
@item
|
|
@emph{AI-0201 Independence of atomic object components (2010-07-22)}
|
|
@cindex AI-0201 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
|
|
attribute, then individual components may not be addressable by independent
|
|
tasks. However, if the representation clause has no effect (is confirming),
|
|
then independence is not compromised. Furthermore, in GNAT, specification of
|
|
other appropriately addressable component sizes (e.g. 16 for 8-bit
|
|
characters) also preserves independence. GNAT now gives very clear warnings
|
|
both for the declaration of such a type, and for any assignment to its components.
|
|
|
|
@noindent
|
|
RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2)
|
|
|
|
@item
|
|
@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
|
|
@cindex AI-0009 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI introduces the new pragmas @code{Independent} and
|
|
@code{Independent_Components},
|
|
which control guaranteeing independence of access to objects and components.
|
|
The AI also requires independence not unaffected by confirming rep clauses.
|
|
|
|
@noindent
|
|
RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2)
|
|
C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14)
|
|
|
|
|
|
@item
|
|
@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)}
|
|
@cindex AI-0072 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies that task signalling for reading @code{'Terminated} only
|
|
occurs if the result is True. GNAT semantics has always been consistent with
|
|
this notion of task signalling.
|
|
|
|
@noindent
|
|
RM References: 9.10 (6.1/1)
|
|
|
|
@item
|
|
@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)}
|
|
@cindex AI-0108 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI confirms that an incomplete type from a limited view does not have
|
|
discriminants. This has always been the case in GNAT.
|
|
|
|
@noindent
|
|
RM References: 10.01.01 (12.3/2)
|
|
|
|
@item
|
|
@emph{AI-0129 Limited views and incomplete types (0000-00-00)}
|
|
@cindex AI-0129 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the description of limited views: a limited view of a
|
|
package includes only one view of a type that has an incomplete declaration
|
|
and a full declaration (there is no possible ambiguity in a client package).
|
|
This AI also fixes an omission: a nested package in the private part has no
|
|
limited view. GNAT always implemented this correctly.
|
|
|
|
@noindent
|
|
RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)}
|
|
@cindex AI-0077 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies that a declaration does not include a context clause,
|
|
and confirms that it is illegal to have a context in which both a limited
|
|
and a nonlimited view of a package are accessible. Such double visibility
|
|
was always rejected by GNAT.
|
|
|
|
@noindent
|
|
RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2)
|
|
|
|
@item
|
|
@emph{AI-0122 Private with and children of generics (0000-00-00)}
|
|
@cindex AI-0122 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the visibility of private children of generic units within
|
|
instantiations of a parent. GNAT has always handled this correctly.
|
|
|
|
@noindent
|
|
RM References: 10.01.02 (12/2)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0040 Limited with clauses on descendant (0000-00-00)}
|
|
@cindex AI-0040 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI confirms that a limited with clause in a child unit cannot name
|
|
an ancestor of the unit. This has always been checked in GNAT.
|
|
|
|
@noindent
|
|
RM References: 10.01.02 (20/2)
|
|
|
|
@item
|
|
@emph{AI-0132 Placement of library unit pragmas (0000-00-00)}
|
|
@cindex AI-0132 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI fills a gap in the description of library unit pragmas. The pragma
|
|
clearly must apply to a library unit, even if it does not carry the name
|
|
of the enclosing unit. GNAT has always enforced the required check.
|
|
|
|
@noindent
|
|
RM References: 10.01.05 (7)
|
|
|
|
|
|
@item
|
|
@emph{AI-0034 Categorization of limited views (0000-00-00)}
|
|
@cindex AI-0034 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM makes certain limited with clauses illegal because of categorization
|
|
considerations, when the corresponding normal with would be legal. This is
|
|
not intended, and GNAT has always implemented the recommended behavior.
|
|
|
|
@noindent
|
|
RM References: 10.02.01 (11/1) 10.02.01 (17/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)}
|
|
@cindex AI-0035 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI remedies some inconsistencies in the legality rules for Pure units.
|
|
Derived access types are legal in a pure unit (on the assumption that the
|
|
rule for a zero storage pool size has been enforced on the ancestor type).
|
|
The rules are enforced in generic instances and in subunits. GNAT has always
|
|
implemented the recommended behavior.
|
|
|
|
@noindent
|
|
RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)}
|
|
@cindex AI-0219 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI refines the rules for the cases with limited parameters which do not
|
|
allow the implementations to omit ``redundant''. GNAT now properly conforms
|
|
to the requirements of this binding interpretation.
|
|
|
|
@noindent
|
|
RM References: 10.02.01 (18/2)
|
|
|
|
@item
|
|
@emph{AI-0043 Rules about raising exceptions (0000-00-00)}
|
|
@cindex AI-0043 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI covers various omissions in the RM regarding the raising of
|
|
exceptions. GNAT has always implemented the intended semantics.
|
|
|
|
@noindent
|
|
RM References: 11.04.01 (10.1/2) 11 (2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)}
|
|
@cindex AI-0200 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI plugs a gap in the RM which appeared to allow some obviously intended
|
|
illegal instantiations. GNAT has never allowed these instantiations.
|
|
|
|
@noindent
|
|
RM References: 12.07 (16)
|
|
|
|
|
|
@item
|
|
@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)}
|
|
@cindex AI-0112 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI concerns giving names to various representation aspects, but the
|
|
practical effect is simply to make the use of duplicate
|
|
@code{Atomic}[@code{_Components}],
|
|
@code{Volatile}[@code{_Components}] and
|
|
@code{Independent}[@code{_Components}] pragmas illegal, and GNAT
|
|
now performs this required check.
|
|
|
|
@noindent
|
|
RM References: 13.01 (8)
|
|
|
|
@item
|
|
@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)}
|
|
@cindex AI-0106 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM appeared to allow representation pragmas on generic formal parameters,
|
|
but this was not intended, and GNAT has never permitted this usage.
|
|
|
|
@noindent
|
|
RM References: 13.01 (9.1/1)
|
|
|
|
|
|
@item
|
|
@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
|
|
@cindex AI-0012 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
It is now illegal to give an inappropriate component size or a pragma
|
|
@code{Pack} that attempts to change the component size in the case of atomic
|
|
or aliased components. Previously GNAT ignored such an attempt with a
|
|
warning.
|
|
|
|
@noindent
|
|
RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21)
|
|
|
|
|
|
@item
|
|
@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)}
|
|
@cindex AI-0039 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})}
|
|
for stream attributes, but these were never useful and are now illegal. GNAT
|
|
has always regarded such expressions as illegal.
|
|
|
|
@noindent
|
|
RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
|
|
@cindex AI-0095 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The prefix of @code{'Address} cannot statically denote a subprogram with
|
|
convention @code{Intrinsic}. The use of the @code{Address} attribute raises
|
|
@code{Program_Error} if the prefix denotes a subprogram with convention
|
|
@code{Intrinsic}.
|
|
|
|
@noindent
|
|
RM References: 13.03 (11/1)
|
|
|
|
|
|
@item
|
|
@emph{AI-0116 Alignment of class-wide objects (0000-00-00)}
|
|
@cindex AI-0116 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI requires that the alignment of a class-wide object be no greater
|
|
than the alignment of any type in the class. GNAT has always followed this
|
|
recommendation.
|
|
|
|
@noindent
|
|
RM References: 13.03 (29) 13.11 (16)
|
|
|
|
|
|
@item
|
|
@emph{AI-0146 Type invariants (2009-09-21)}
|
|
@cindex AI-0146 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Type invariants may be specified for private types using the aspect notation.
|
|
Aspect @code{Invariant} may be specified for any private type,
|
|
@code{Invariant'Class} can
|
|
only be specified for tagged types, and is inherited by any descendent of the
|
|
tagged types. The invariant is a boolean expression that is tested for being
|
|
true in the following situations: conversions to the private type, object
|
|
declarations for the private type that are default initialized, and
|
|
[@b{in}] @b{out}
|
|
parameters and returned result on return from any primitive operation for
|
|
the type that is visible to a client.
|
|
|
|
@noindent
|
|
RM References: 13.03.03 (00)
|
|
|
|
@item
|
|
@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)}
|
|
@cindex AI-0078 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
In Ada 2012, compilers are required to support unchecked conversion where the
|
|
target alignment is a multiple of the source alignment. GNAT always supported
|
|
this case (and indeed all cases of differing alignments, doing copies where
|
|
required if the alignment was reduced).
|
|
|
|
@noindent
|
|
RM References: 13.09 (7)
|
|
|
|
|
|
@item
|
|
@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)}
|
|
@cindex AI-0195 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The handling of invalid values is now designated to be implementation
|
|
defined. This is a documentation change only, requiring Annex M in the GNAT
|
|
Reference Manual to document this handling.
|
|
In GNAT, checks for invalid values are made
|
|
only when necessary to avoid erroneous behavior. Operations like assignments
|
|
which cannot cause erroneous behavior ignore the possibility of invalid
|
|
values and do not do a check. The date given above applies only to the
|
|
documentation change, this behavior has always been implemented by GNAT.
|
|
|
|
@noindent
|
|
RM References: 13.09.01 (10)
|
|
|
|
@item
|
|
@emph{AI-0193 Alignment of allocators (2010-09-16)}
|
|
@cindex AI-0193 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
|
|
analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
|
|
of size.
|
|
|
|
@noindent
|
|
RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
|
|
13.11.01 (2) 13.11.01 (3)
|
|
|
|
|
|
@item
|
|
@emph{AI-0177 Parameterized expressions (2010-07-10)}
|
|
@cindex AI-0177 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The new Ada 2012 notion of parameterized expressions is implemented. The form
|
|
is:
|
|
@smallexample
|
|
@i{function specification} @b{is} (@i{expression})
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is exactly equivalent to the
|
|
corresponding function body that returns the expression, but it can appear
|
|
in a package spec. Note that the expression must be parenthesized.
|
|
|
|
@noindent
|
|
RM References: 13.11.01 (3/2)
|
|
|
|
@item
|
|
@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)}
|
|
@cindex AI-0033 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Neither of these two pragmas may appear within a generic template, because
|
|
the generic might be instantiated at other than the library level.
|
|
|
|
@noindent
|
|
RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
|
|
@cindex AI-0161 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
|
|
of the default stream attributes for elementary types. If this restriction is
|
|
in force, then it is necessary to provide explicit subprograms for any
|
|
stream attributes used.
|
|
|
|
@noindent
|
|
RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2)
|
|
|
|
@item
|
|
@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
|
|
@cindex AI-0194 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The @code{Stream_Size} attribute returns the default number of bits in the
|
|
stream representation of the given type.
|
|
This value is not affected by the presence
|
|
of stream subprogram attributes for the type. GNAT has always implemented
|
|
this interpretation.
|
|
|
|
@noindent
|
|
RM References: 13.13.02 (1.2/2)
|
|
|
|
@item
|
|
@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)}
|
|
@cindex AI-0109 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI is an editorial change only. It removes the need for a tag check
|
|
that can never fail.
|
|
|
|
@noindent
|
|
RM References: 13.13.02 (34/2)
|
|
|
|
@item
|
|
@emph{AI-0007 Stream read and private scalar types (0000-00-00)}
|
|
@cindex AI-0007 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM as written appeared to limit the possibilities of declaring read
|
|
attribute procedures for private scalar types. This limitation was not
|
|
intended, and has never been enforced by GNAT.
|
|
|
|
@noindent
|
|
RM References: 13.13.02 (50/2) 13.13.02 (51/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0065 Remote access types and external streaming (0000-00-00)}
|
|
@cindex AI-0065 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI clarifies the fact that all remote access types support external
|
|
streaming. This fixes an obvious oversight in the definition of the
|
|
language, and GNAT always implemented the intended correct rules.
|
|
|
|
@noindent
|
|
RM References: 13.13.02 (52/2)
|
|
|
|
@item
|
|
@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)}
|
|
@cindex AI-0019 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The RM suggests that primitive subprograms of a specific tagged type are
|
|
frozen when the tagged type is frozen. This would be an incompatible change
|
|
and is not intended. GNAT has never attempted this kind of freezing and its
|
|
behavior is consistent with the recommendation of this AI.
|
|
|
|
@noindent
|
|
RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2)
|
|
|
|
@item
|
|
@emph{AI-0017 Freezing and incomplete types (0000-00-00)}
|
|
@cindex AI-0017 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
So-called ``Taft-amendment types'' (i.e., types that are completed in package
|
|
bodies) are not frozen by the occurrence of bodies in the
|
|
enclosing declarative part. GNAT always implemented this properly.
|
|
|
|
@noindent
|
|
RM References: 13.14 (3/1)
|
|
|
|
|
|
@item
|
|
@emph{AI-0060 Extended definition of remote access types (0000-00-00)}
|
|
@cindex AI-0060 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI extends the definition of remote access types to include access
|
|
to limited, synchronized, protected or task class-wide interface types.
|
|
GNAT already implemented this extension.
|
|
|
|
@noindent
|
|
RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18)
|
|
|
|
@item
|
|
@emph{AI-0114 Classification of letters (0000-00-00)}
|
|
@cindex AI-0114 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
|
|
181 (@code{MICRO SIGN}), and
|
|
186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
|
|
lower case letters by Unicode.
|
|
However, they are not allowed in identifiers, and they
|
|
return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
|
|
This behavior is consistent with that defined in Ada 95.
|
|
|
|
@noindent
|
|
RM References: A.03.02 (59) A.04.06 (7)
|
|
|
|
|
|
@item
|
|
@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
|
|
@cindex AI-0185 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
|
|
classification functions for @code{Wide_Character} and
|
|
@code{Wide_Wide_Character}, as well as providing
|
|
case folding routines for @code{Wide_[Wide_]Character} and
|
|
@code{Wide_[Wide_]String}.
|
|
|
|
@noindent
|
|
RM References: A.03.05 (0) A.03.06 (0)
|
|
|
|
|
|
@item
|
|
@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
|
|
@cindex AI-0031 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A new version of @code{Find_Token} is added to all relevant string packages,
|
|
with an extra parameter @code{From}. Instead of starting at the first
|
|
character of the string, the search for a matching Token starts at the
|
|
character indexed by the value of @code{From}.
|
|
These procedures are available in all versions of Ada
|
|
but if used in versions earlier than Ada 2012 they will generate a warning
|
|
that an Ada 2012 subprogram is being used.
|
|
|
|
@noindent
|
|
RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51)
|
|
A.04.05 (46)
|
|
|
|
|
|
@item
|
|
@emph{AI-0056 Index on null string returns zero (0000-00-00)}
|
|
@cindex AI-0056 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The wording in the Ada 2005 RM implied an incompatible handling of the
|
|
@code{Index} functions, resulting in raising an exception instead of
|
|
returning zero in some situations.
|
|
This was not intended and has been corrected.
|
|
GNAT always returned zero, and is thus consistent with this AI.
|
|
|
|
@noindent
|
|
RM References: A.04.03 (56.2/2) A.04.03 (58.5/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0137 String encoding package (2010-03-25)}
|
|
@cindex AI-0137 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The packages @code{Ada.Strings.UTF_Encoding}, together with its child
|
|
packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
|
|
and @code{Wide_Wide_Strings} have been
|
|
implemented. These packages (whose documentation can be found in the spec
|
|
files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads},
|
|
@file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of
|
|
@code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
|
|
values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
|
|
UTF-16), as well as conversions between the different UTF encodings. With
|
|
the exception of @code{Wide_Wide_Strings}, these packages are available in
|
|
Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
|
|
The @code{Wide_Wide_Strings package}
|
|
is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
|
|
mode since it uses @code{Wide_Wide_Character}).
|
|
|
|
@noindent
|
|
RM References: A.04.11
|
|
|
|
@item
|
|
@emph{AI-0038 Minor errors in Text_IO (0000-00-00)}
|
|
@cindex AI-0038 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
These are minor errors in the description on three points. The intent on
|
|
all these points has always been clear, and GNAT has always implemented the
|
|
correct intended semantics.
|
|
|
|
@noindent
|
|
RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24)
|
|
|
|
@item
|
|
@emph{AI-0044 Restrictions on container instantiations (0000-00-00)}
|
|
@cindex AI-0044 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI places restrictions on allowed instantiations of generic containers.
|
|
These restrictions are not checked by the compiler, so there is nothing to
|
|
change in the implementation. This affects only the RM documentation.
|
|
|
|
@noindent
|
|
RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2)
|
|
|
|
@item
|
|
@emph{AI-0127 Adding Locale Capabilities (2010-09-29)}
|
|
@cindex AI-0127 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This package provides an interface for identifying the current locale.
|
|
|
|
@noindent
|
|
RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06
|
|
A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)}
|
|
@cindex AI-0002 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The compiler is not required to support exporting an Ada subprogram with
|
|
convention C if there are parameters or a return type of an unconstrained
|
|
array type (such as @code{String}). GNAT allows such declarations but
|
|
generates warnings. It is possible, but complicated, to write the
|
|
corresponding C code and certainly such code would be specific to GNAT and
|
|
non-portable.
|
|
|
|
@noindent
|
|
RM References: B.01 (17) B.03 (62) B.03 (71.1/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
|
|
@cindex AI05-0216 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
It is clearly the intention that @code{No_Task_Hierarchy} is intended to
|
|
forbid tasks declared locally within subprograms, or functions returning task
|
|
objects, and that is the implementation that GNAT has always provided.
|
|
However the language in the RM was not sufficiently clear on this point.
|
|
Thus this is a documentation change in the RM only.
|
|
|
|
@noindent
|
|
RM References: D.07 (3/3)
|
|
|
|
@item
|
|
@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
|
|
@cindex AI-0211 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
|
|
@code{Ada.Real_Time.Timing_Events.Set_Handler}.
|
|
|
|
@noindent
|
|
RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
|
|
|
|
@item
|
|
@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
|
|
@cindex AI-0190 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
|
|
used to control storage pools globally.
|
|
In particular, you can force every access
|
|
type that is used for allocation (@b{new}) to have an explicit storage pool,
|
|
or you can declare a pool globally to be used for all access types that lack
|
|
an explicit one.
|
|
|
|
@noindent
|
|
RM References: D.07 (8)
|
|
|
|
@item
|
|
@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
|
|
@cindex AI-0189 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
|
|
which says that no dynamic allocation will occur once elaboration is
|
|
completed.
|
|
In general this requires a run-time check, which is not required, and which
|
|
GNAT does not attempt. But the static cases of allocators in a task body or
|
|
in the body of the main program are detected and flagged at compile or bind
|
|
time.
|
|
|
|
@noindent
|
|
RM References: D.07 (19.1/2) H.04 (23.3/2)
|
|
|
|
@item
|
|
@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
|
|
@cindex AI-0171 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
A new package @code{System.Multiprocessors} is added, together with the
|
|
definition of pragma @code{CPU} for controlling task affinity. A new no
|
|
dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
|
|
is added to the Ravenscar profile.
|
|
|
|
@noindent
|
|
RM References: D.13.01 (4/2) D.16
|
|
|
|
|
|
@item
|
|
@emph{AI-0210 Correct Timing_Events metric (0000-00-00)}
|
|
@cindex AI-0210 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
This is a documentation only issue regarding wording of metric requirements,
|
|
that does not affect the implementation of the compiler.
|
|
|
|
@noindent
|
|
RM References: D.15 (24/2)
|
|
|
|
|
|
@item
|
|
@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)}
|
|
@cindex AI-0206 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Remote types packages are now allowed to depend on preelaborated packages.
|
|
This was formerly considered illegal.
|
|
|
|
@noindent
|
|
RM References: E.02.02 (6)
|
|
|
|
|
|
|
|
@item
|
|
@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
|
|
@cindex AI-0152 (Ada 2012 feature)
|
|
|
|
@noindent
|
|
Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
|
|
where the type of the returned value is an anonymous access type.
|
|
|
|
@noindent
|
|
RM References: H.04 (8/1)
|
|
@end itemize
|
|
|
|
|
|
@node Obsolescent Features
|
|
@chapter Obsolescent Features
|
|
|
|
@noindent
|
|
This chapter describes features that are provided by GNAT, but are
|
|
considered obsolescent since there are preferred ways of achieving
|
|
the same effect. These features are provided solely for historical
|
|
compatibility purposes.
|
|
|
|
@menu
|
|
* pragma No_Run_Time::
|
|
* pragma Ravenscar::
|
|
* pragma Restricted_Run_Time::
|
|
@end menu
|
|
|
|
@node pragma No_Run_Time
|
|
@section pragma No_Run_Time
|
|
|
|
The pragma @code{No_Run_Time} is used to achieve an affect similar
|
|
to the use of the "Zero Foot Print" configurable run time, but without
|
|
requiring a specially configured run time. The result of using this
|
|
pragma, which must be used for all units in a partition, is to restrict
|
|
the use of any language features requiring run-time support code. The
|
|
preferred usage is to use an appropriately configured run-time that
|
|
includes just those features that are to be made accessible.
|
|
|
|
@node pragma Ravenscar
|
|
@section pragma Ravenscar
|
|
|
|
The pragma @code{Ravenscar} has exactly the same effect as pragma
|
|
@code{Profile (Ravenscar)}. The latter usage is preferred since it
|
|
is part of the new Ada 2005 standard.
|
|
|
|
@node pragma Restricted_Run_Time
|
|
@section pragma Restricted_Run_Time
|
|
|
|
The pragma @code{Restricted_Run_Time} has exactly the same effect as
|
|
pragma @code{Profile (Restricted)}. The latter usage is
|
|
preferred since the Ada 2005 pragma @code{Profile} is intended for
|
|
this kind of implementation dependent addition.
|
|
|
|
@include fdl.texi
|
|
@c GNU Free Documentation License
|
|
|
|
@node Index,,GNU Free Documentation License, Top
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@contents
|
|
|
|
@bye
|