* Pragma No_Strict_Aliasing ::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
* Pragma Passive::
* Pragma Persistent_BSS::
* Pragma Polling::
* Pragma Unimplemented_Unit::
* Pragma Universal_Aliasing ::
* Pragma Universal_Data::
+* Pragma Unmodified::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* Mechanism_Code::
* Null_Parameter::
* Object_Size::
+* Old::
* Passed_By_Reference::
* Pool_Address::
* Range_Length::
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
+* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Command_Line.Response_File (a-clrefi.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
* Ada.Exceptions.Traceback (a-exctra.ads)::
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
+* Ada.Wide_Characters.Unicode (a-wichun.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
* GNAT.Altivec (g-altive.ads)::
* GNAT.Altivec.Conversions (g-altcon.ads)::
* GNAT.Most_Recent_Exception (g-moreex.ads)::
* GNAT.OS_Lib (g-os_lib.ads)::
* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
-* GNAT.Random_Numbers (g-rannum.ads)
+* GNAT.Random_Numbers (g-rannum.ads)::
* GNAT.Regexp (g-regexp.ads)::
* GNAT.Registry (g-regist.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.Serial_Communications (g-sercom.ads)::
* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Os2lib (i-os2lib.ads)::
-* Interfaces.Os2lib.Errors (i-os2err.ads)::
-* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
-* Interfaces.Os2lib.Threads (i-os2thr.ads)::
* Interfaces.Packed_Decimal (i-pacdec.ads)::
* Interfaces.VxWorks (i-vxwork.ads)::
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
* System.Assertions (s-assert.ads)::
* System.Memory (s-memory.ads)::
* System.Partition_Interface (s-parint.ads)::
+* System.Pool_Global (s-pooglo.ads)::
+* System.Pool_Local (s-pooloc.ads)::
* System.Restrictions (s-restri.ads)::
* System.Rident (s-rident.ads)::
* System.Task_Info (s-tasinf.ads)::
* Pragma No_Strict_Aliasing::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
* Pragma Passive::
* Pragma Persistent_BSS::
* Pragma Polling::
* Pragma Unimplemented_Unit::
* Pragma Universal_Aliasing ::
* Pragma Universal_Data::
+* Pragma Unmodified::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
@noindent
Same as pragma Compile_Time_Error, except a warning is issued instead
-of an error message.
+of an error message. Note that if this pragma is used in a package that
+is with'ed by a client, the client will get the warning even though it
+is issued by a with'ed package (normally warnings in with'ed units are
+suppressed, but this is a special exception to that rule).
+
+One typical use is within a generic where compile time known characteristics
+of formal parameters are tested, and warnings given appropriately. Another use
+with a first parameter of True is to warn a client about use of a package,
+for example that it is not fully implemented.
@node Pragma Complete_Representation
@unnumberedsec Pragma Complete_Representation
immediately preceding the pragma (this form cannot be used for the
enumeration literal case).
+@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 predefined units in the GNAT library (that is, members of the Ada, System,
+Interfaces, GNAT hierarchies) ignore the setting of this pragma, and thus the
+consistency requirement does not apply to them.
+
@node Pragma Passive
@unnumberedsec Pragma Passive
@findex Passive
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
User's Guide}.
@smallexample
-a turn on all optional warnings (except d,h,l)
-A turn off all optional warnings
-b turn on warnings for bad fixed value (not multiple of small)
-B turn off warnings for bad fixed value (not multiple of small)
-c turn on warnings for constant conditional
-C turn off warnings for constant conditional
-d turn on warnings for implicit dereference
-D turn off warnings for implicit dereference
-e treat all warnings as errors
-f turn on warnings for unreferenced formal
-F turn off warnings for unreferenced formal
-g turn on warnings for unrecognized pragma
-G turn off warnings for unrecognized pragma
-h turn on warnings for hiding variable
-H turn off warnings for hiding variable
-i turn on warnings for implementation unit
-I turn off warnings for implementation unit
-j turn on warnings for obsolescent (annex J) feature
-J turn off warnings for obsolescent (annex J) feature
-k turn on warnings on constant variable
-K turn off warnings on constant variable
-l turn on warnings for missing elaboration pragma
-L turn off warnings for missing elaboration pragma
-m turn on warnings for variable assigned but not read
-M turn off warnings for variable assigned but not read
-n normal warning mode (cancels -gnatws/-gnatwe)
-o turn on warnings for address clause overlay
-O turn off warnings for address clause overlay
-p turn on warnings for ineffective pragma Inline
-P turn off warnings for ineffective pragma Inline
-q turn on warnings for questionable missing parentheses
-Q turn off warnings for questionable missing parentheses
-r turn on warnings for redundant construct
-R turn off warnings for redundant construct
-s suppress all warnings
-t turn on warnings for tracking deleted code
-T turn off warnings for tracking deleted code
-u turn on warnings for unused entity
-U turn off warnings for unused entity
-v turn on warnings for unassigned variable
-V turn off warnings for unassigned variable
-w turn on warnings for wrong low bound assumption
-W turn off warnings for wrong low bound assumption
-x turn on warnings for export/import
-X turn off warnings for export/import
-y turn on warnings for Ada 2005 incompatibility
-Y turn off warnings for Ada 2005 incompatibility
-z turn on size/align warnings for unchecked conversion
-Z turn off size/align warnings for unchecked conversion
+a turn on all optional warnings (except d h l .o)
+A turn off all optional warnings
+.a* turn on warnings for failing assertions
+.A turn off warnings for failing assertions
+b turn on warnings for bad fixed value (not multiple of small)
+B* turn off warnings for bad fixed value (not multiple of small)
+c turn on warnings for constant conditional
+C* turn off warnings for constant conditional
+.c turn on warnings for unrepped components
+.C* turn off warnings for unrepped components
+d turn on warnings for implicit dereference
+D* turn off warnings for implicit dereference
+e treat all warnings as errors
+f turn on warnings for unreferenced formal
+F* turn off warnings for unreferenced formal
+g* turn on warnings for unrecognized pragma
+G turn off warnings for unrecognized pragma
+h turn on warnings for hiding variable
+H* turn off warnings for hiding variable
+i* turn on warnings for implementation unit
+I turn off warnings for implementation unit
+j turn on warnings for obsolescent (annex J) feature
+J* turn off warnings for obsolescent (annex J) feature
+k turn on warnings on constant variable
+K* turn off warnings on constant variable
+l turn on warnings for missing elaboration pragma
+L* turn off warnings for missing elaboration pragma
+m turn on warnings for variable assigned but not read
+M* turn off warnings for variable assigned but not read
+n* normal warning mode (cancels -gnatws/-gnatwe)
+o* turn on warnings for address clause overlay
+O turn off warnings for address clause overlay
+.o turn on warnings for out parameters assigned but not read
+.O* turn off warnings for out parameters assigned but not read
+p turn on warnings for ineffective pragma Inline in frontend
+P* turn off warnings for ineffective pragma Inline in frontend
+q* turn on warnings for questionable missing parentheses
+Q turn off warnings for questionable missing parentheses
+r turn on warnings for redundant construct
+R* turn off warnings for redundant construct
+.r turn on warnings for object renaming function
+.R* turn off warnings for object renaming function
+s suppress all warnings
+t turn on warnings for tracking deleted code
+T* turn off warnings for tracking deleted code
+u turn on warnings for unused entity
+U* turn off warnings for unused entity
+v* turn on warnings for unassigned variable
+V turn off warnings for unassigned variable
+w* turn on warnings for wrong low bound assumption
+W turn off warnings for wrong low bound assumption
+x* turn on warnings for export/import
+X turn off warnings for export/import
+.x turn on warnings for non-local exceptions
+.X* turn off warnings for non-local exceptions
+y* turn on warnings for Ada 2005 incompatibility
+Y turn off warnings for Ada 2005 incompatibility
+z* turn on convention/size/align warnings for unchecked conversion
+Z turn off convention/size/align warnings for unchecked conversion
+* indicates default in above list
@end smallexample
@noindent
* Mechanism_Code::
* Null_Parameter::
* Object_Size::
+* Old::
* Passed_By_Reference::
* Pool_Address::
* Range_Length::
integer field, and so the default size of record objects for this type
will be 64 (8 bytes).
-The @code{@var{type}'Object_Size} attribute
-has been added to GNAT to allow the
-default object size of a type to be easily determined. For example,
-@code{Natural'Object_Size} is 32, and
-@code{Rec'Object_Size} (for the record type in the above example) will be
-64. Note also that, unlike the situation with the
-@code{Size} attribute as defined in the Ada RM, the
-@code{Object_Size} attribute can be specified individually
-for different subtypes. For example:
+@node Old
+@unnumberedsec Old
+@cindex Capturing Old values
+@cindex Postconditions
+@noindent
+The attribute Prefix'Old can be used within a
+subprogram to refer to the value of the prefix on entry. So for
+example if you have an argument of a record type X called Arg1,
+you can refer to Arg1.Field'Old which yields the value of
+Arg1.Field on entry. The implementation simply involves generating
+an object declaration which captures the value on entry. Any
+prefix is allowed except one of a limited type (since limited
+types cannot be copied to capture their values).
+
+The following example shows the use of 'Old to implement
+a test of a postcondition:
@smallexample @c ada
-type R is new Integer;
-subtype R1 is R range 1 .. 10;
-subtype R2 is R range 1 .. 10;
-for R2'Object_Size use 8;
-@end smallexample
+with Old_Pkg;
+procedure Old is
+begin
+ Old_Pkg.Incr;
+end Old;
-@noindent
-In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
-32 since the default object size for a subtype is the same as the object size
-for the parent subtype. This means that objects of type @code{R}
-or @code{R1} will
-by default be 32 bits (four bytes). But objects of type
-@code{R2} will be only
-8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
+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
-Although @code{Object_Size} does properly reflect the default object size
-value, it is not necessarily the case that all objects will be of this size
-in a case where it is not specified explicitly. The compiler is free to
-increase the size and alignment of stand alone objects to improve efficiency
-of the generated code and sometimes does so in the case of large composite
-objects. If the size of a stand alone object is critical to the
-application, it should be specified explicitly.
+ pragma Assert (Count = Count'Old + 1);
+ end Incr;
+end Old_Pkg;
+@end smallexample
@node Passed_By_Reference
@unnumberedsec Passed_By_Reference
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
+* Ada.Command_Line.Remove (a-colire.ads)::
+* Ada.Command_Line.Response_File (a-clrefi.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
* Ada.Exceptions.Traceback (a-exctra.ads)::
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
+* Ada.Wide_Characters.Unicode (a-wichun.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
* GNAT.Altivec (g-altive.ads)::
* GNAT.Altivec.Conversions (g-altcon.ads)::
* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
-* GNAT.CRC32 (g-crc32.ads)::
* GNAT.Case_Util (g-casuti.ads)::
* GNAT.CGI (g-cgi.ads)::
* GNAT.CGI.Cookie (g-cgicoo.ads)::
* GNAT.Command_Line (g-comlin.ads)::
* GNAT.Compiler_Version (g-comver.ads)::
* GNAT.Ctrl_C (g-ctrl_c.ads)::
+* GNAT.CRC32 (g-crc32.ads)::
* GNAT.Current_Exception (g-curexc.ads)::
* GNAT.Debug_Pools (g-debpoo.ads)::
* GNAT.Debug_Utilities (g-debuti.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.Serial_Communications (g-sercom.ads)::
* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Os2lib (i-os2lib.ads)::
-* Interfaces.Os2lib.Errors (i-os2err.ads)::
-* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
-* Interfaces.Os2lib.Threads (i-os2thr.ads)::
* Interfaces.Packed_Decimal (i-pacdec.ads)::
* Interfaces.VxWorks (i-vxwork.ads)::
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
* System.Assertions (s-assert.ads)::
* System.Memory (s-memory.ads)::
* System.Partition_Interface (s-parint.ads)::
+* System.Pool_Global (s-pooglo.ads)::
+* System.Pool_Local (s-pooloc.ads)::
* System.Restrictions (s-restri.ads)::
* System.Rident (s-rident.ads)::
* System.Task_Info (s-tasinf.ads)::
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
-@node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
+@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
@cindex Latin_1 constants for Wide_Wide_Character
@noindent
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
-@node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
+@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
@cindex Latin_9 constants for Wide_Wide_Character
@noindent
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
+@node Ada.Command_Line.Environment (a-colien.ads)
+@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
+@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
+@cindex Environment entries
+
+@noindent
+This child of @code{Ada.Command_Line}
+provides a mechanism for obtaining environment values on systems
+where this concept makes sense.
+
@node Ada.Command_Line.Remove (a-colire.ads)
@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
to further calls on the subprograms in @code{Ada.Command_Line} will not
see the removed argument.
-@node Ada.Command_Line.Environment (a-colien.ads)
-@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex Environment entries
+@node Ada.Command_Line.Response_File (a-clrefi.ads)
+@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
+@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
+@cindex Response file for command line
+@cindex Command line, response file
+@cindex Command line, handling long command lines
@noindent
-This child of @code{Ada.Command_Line}
-provides a mechanism for obtaining environment values on systems
-where this concept makes sense.
+This child of @code{Ada.Command_Line} provides a mechanism facilities for
+getting command line arguments from a text file, called a "response file".
+Using a response file allow passing a set of arguments to an executable longer
+than the maximum allowed by the system on the command line.
@node Ada.Direct_IO.C_Streams (a-diocst.ads)
@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
exception occurrence (@code{Null_Occurrence}) without raising
an exception.
+@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
+@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
+@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
+@cindex Null_Occurrence, testing for
+
+@noindent
+This child subprogram is used for handling otherwise unhandled
+exceptions (hence the name last chance), and perform clean ups before
+terminating the program. Note that this subprogram never returns.
+
@node Ada.Exceptions.Traceback (a-exctra.ads)
@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Wide_Characters.Unicode (a-wichun.ads)
+@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
+@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
+@cindex Unicode categorization, Wide_Character
+
+@noindent
+This package provides subprograms that allow categorization of
+Wide_Character values according to Unicode categories.
+
@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Wide_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})
@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})
is primarily intended to be used in connection with automated tools
for the generation of C++ interfaces.
-@node Interfaces.Os2lib (i-os2lib.ads)
-@section @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
-@cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
-@cindex Interfacing, to OS/2
-@cindex OS/2 interfacing
-
-@noindent
-This package provides interface definitions to the OS/2 library.
-It is a thin binding which is a direct translation of the
-various @file{<bse@.h>} files.
-
-@node Interfaces.Os2lib.Errors (i-os2err.ads)
-@section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
-@cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
-@cindex OS/2 Error codes
-@cindex Interfacing, to OS/2
-@cindex OS/2 interfacing
-
-@noindent
-This package provides definitions of the OS/2 error codes.
-
-@node Interfaces.Os2lib.Synchronization (i-os2syn.ads)
-@section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
-@cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
-@cindex Interfacing, to OS/2
-@cindex Synchronization, OS/2
-@cindex OS/2 synchronization primitives
-
-@noindent
-This is a child package that provides definitions for interfacing
-to the @code{OS/2} synchronization primitives.
-
-@node Interfaces.Os2lib.Threads (i-os2thr.ads)
-@section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
-@cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
-@cindex Interfacing, to OS/2
-@cindex Thread control, OS/2
-@cindex OS/2 thread interfacing
-
-@noindent
-This is a child package that provides definitions for interfacing
-to the @code{OS/2} thread primitives.
-
@node Interfaces.Packed_Decimal (i-pacdec.ads)
@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
is used primarily in a distribution context when using Annex E
with @code{GLADE}.
+@node System.Pool_Global (s-pooglo.ads)
+@section @code{System.Pool_Global} (@file{s-pooglo.ads})
+@cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
+@cindex Storage pool, global
+@cindex Global storage pool
+
+@noindent
+This package provides a storage pool that is equivalent to the default
+storage pool used for access types for which no pool is specifically
+declared. It uses malloc/free to allocate/free and does not attempt to
+do any automatic reclamation.
+
+@node System.Pool_Local (s-pooloc.ads)
+@section @code{System.Pool_Local} (@file{s-pooloc.ads})
+@cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
+@cindex Storage pool, local
+@cindex Local storage pool
+
+@noindent
+This package provides a storage pool that is intended for use with locally
+defined access types. It uses malloc/free for allocate/free, and maintains
+a list of allocated blocks, so that all storage allocated for the pool can
+be freed automatically when the pool is finalized.
+
@node System.Restrictions (s-restri.ads)
@section @code{System.Restrictions} (@file{s-restri.ads})
@cindex @code{System.Restrictions} (@file{s-restri.ads})
@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2007, AdaCore o
+@c Copyright (C) 1992-2008, AdaCore o
@c o
@c GNAT is free software; you can redistribute it and/or modify it under o
@c terms of the GNU General Public License as published by the Free Soft- o
@set EDITION GNAT
@set DEFAULTLANGUAGEVERSION Ada 2005
@set NONDEFAULTLANGUAGEVERSION Ada 95
-@set FILE gnat_ugn
@ifset unw
@set PLATFORM
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
@direntry
-* @value{EDITION} User's Guide (@value{FILE}) @value{PLATFORM}
+* @value{EDITION} User's Guide (gnat_ugn) @value{PLATFORM}
@end direntry
@include gcc-common.texi
* Creating Sample Bodies Using gnatstub::
* Other Utility Programs::
* Running and Debugging Ada Programs::
+@ifclear vms
+* Code Coverage and Profiling::
+@end ifclear
@ifset vms
* Compatibility with HP Ada::
@end ifset
* The External Symbol Naming Scheme of GNAT::
* Converting Ada Files to html with gnathtml::
+@ifclear vms
+Code Coverage and Profiling
+
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end ifclear
+
Running and Debugging Ada Programs
* The GNAT Debugger GDB::
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
Example of Binder Output File
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
+@ifclear vms
+@item
+@ref{Code Coverage and Profiling}, describes how to perform a structural
+coverage and profile the execution of Ada programs.
+@end ifclear
+
@item
@ref{Running and Debugging Ada Programs}, describes how to run and debug
Ada programs.
@item -gnatwW
@emph{Suppress warnings on wrong low bound assumption.}
@cindex @option{-gnatwW} (@command{gcc})
-This switch activates warnings for indexing an unconstrained string parameter
-with a literal or S'Length. This warning can also be suppressed by providing
-an Assert pragma that checks the low bound, for example:
+This switch suppresses warnings for indexing an unconstrained string parameter
+with a literal or S'Length. Note that this warning can also be suppressed
+in a particular case by adding an
+assertion that the lower bound is 1,
+as shown in the following example.
@smallexample @c ada
procedure K (S : String) is
@dots{}
@end smallexample
+@item -gnatw.w
+@emph{Activate warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.w} (@command{gcc})
+@cindex Warnings Off control
+This switch activates warnings for use of @code{pragma Warnings (Off, entity}
+where either the pragma is entirely useless (because it suppresses no
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.The default is that these warnings are not given.
+Note that this warning is not included in -gnatwa, it must be
+activated explicitly.
+
+@item -gnatw.W
+@emph{Suppress warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.W} (@command{gcc})
+This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
+
@item -gnatwx
@emph{Activate warnings on Export/Import pragmas.}
@cindex @option{-gnatwx} (@command{gcc})
This switch activates warnings for unchecked conversions
where the types are known at compile time to have different
sizes. The default
-is that such warnings are generated.
+is that such warnings are generated. Warnings are also
+generated for subprogram pointers with different conventions,
+and, on VMS only, for data pointers with different conventions.
This warning can also be turned on using @option{-gnatwa}.
@item -gnatwZ
@cindex @option{-gnatwZ} (@command{gcc})
This switch suppresses warnings for unchecked conversions
where the types are known at compile time to have different
-sizes.
+sizes or conventions.
@item ^-Wuninitialized^WARNINGS=UNINITIALIZED^
@cindex @option{-Wuninitialized}
@cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub})
Put a sample comment header into the body stub.
+@item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^
+@cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub})
+Use the content of the file as the comment header for a generated body stub.
+
@ifclear vms
@item -IDIR
@cindex @option{-IDIR} (@command{gnatstub})
@noindent
@end ifset
+@ifclear vms
+@c ******************************
+@node Code Coverage and Profiling
+@chapter Code Coverage and Profiling
+@cindex Code Coverage
+@cindex Profiling
+
+@noindent
+This chapter describes how to use @code{gcov} - coverage testing tool - and
+@code{gprof} - profiler tool - on your Ada programs.
+
+@menu
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end menu
+
+@node Code Coverage of Ada Programs using gcov
+@section Code Coverage of Ada Programs using gcov
+@cindex gcov
+@cindex -fprofile-arcs
+@cindex -ftest-coverage
+@cindex -coverage
+@cindex Code Coverage
+
+@noindent
+@code{gcov} is a test coverage program: it analyzes the execution of a given
+program on selected tests, to help you determine the portions of the program
+that are still untested.
+
+@code{gcov} is part of the GCC suite, and is described in detail in the GCC
+User's Guide. You can refer to this documentation for a more complete
+description.
+
+This chapter provides a quick startup guide, and
+details some Gnat-specific features.
+
+@menu
+* Quick startup guide::
+* Gnat specifics::
+@end menu
+
+@node Quick startup guide
+@subsection Quick startup guide
+
+In order to perform coverage analysis of a program using @code{gcov}, 3
+steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation during the compilation process
+@item
+Execution of the instrumented program
+@item
+Execution of the @code{gcov} tool to generate the result.
+@end itemize
+
+The code instrumentation needed by gcov is created at the object level:
+The source code is not modified in any way, because the instrumentation code is
+inserted by gcc during the compilation process. To compile your code with code
+coverage activated, you need to recompile your whole project using the
+switches
+@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
+@code{-fprofile-arcs}.
+
+@smallexample
+$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \
+ -largs -fprofile-arcs
+@end smallexample
+
+This compilation process will create @file{.gcno} files together with
+the usual object files.
+
+Once the program is compiled with coverage instrumentation, you can
+run it as many times as needed - on portions of a test suite for
+example. The first execution will produce @file{.gcda} files at the
+same location as the @file{.gcno} files. The following executions
+will update those files, so that a cumulative result of the covered
+portions of the program is generated.
+
+Finaly, you need to call the @code{gcov} tool. The different options of
+@code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'.
+
+This will create anotated source files with a @file{.gcov} extension:
+@file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}.
+
+@node Gnat specifics
+@subsection Gnat specifics
+
+Because Ada semantics, portions of the source code may be shared among
+several object files. This is the case for example when generics are
+involved, when inlining is active or when declarations generate initialisation
+calls. In order to take
+into account this shared code, you need to call @code{gcov} on all
+source files of the tested program at once.
+
+The list of source files might exceed the system's maximum command line
+length. In order to bypass this limitation, a new mechanism has been
+implemented in @code{gcov}: you can now list all your project's files into a
+text file, and provide this file to gcov as a parameter, preceded by a @@
+(e.g. @samp{gcov @@mysrclist.txt}).
+
+@node Profiling an Ada Program using gprof
+@section Profiling an Ada Program using gprof
+@cindex gprof
+@cindex -pg
+@cindex Profiling
+
+@noindent
+This section is not meant to be an exhaustive documentation of @code{gprof}.
+Full documentation for it can be found in the GNU Profiler User's Guide
+documentation that is part of this GNAT distribution.
+
+Profiling a program helps determine the parts of a program that are executed
+most often, and are therefore the most time-consuming.
+
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
+better handle Ada programs and multitasking.
+It is currently supported on the following platoforms
+@itemize @bullet
+@item
+linux x86/x86_64
+@item
+solaris sparc/sparc64/x86
+@item
+windows x86
+@end itemize
+
+@noindent
+In order to profile a program using @code{gprof}, 3 steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation, requiring a full recompilation of the project with the
+proper switches.
+@item
+Execution of the program under the analysis conditions, i.e. with the desired
+input.
+@item
+Analysis of the results using the @code{gprof} tool.
+@end itemize
+
+@noindent
+The following sections detail the different steps, and indicate how
+to interpret the results:
+@menu
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
+@end menu
+
+@node Compilation for profiling
+@subsection Compilation for profiling
+@cindex -pg
+@cindex Profiling
+
+In order to profile a program the first step is to tell the compiler
+to generate the necessary profiling information. The compiler switch to be used
+is @code{-pg}, which must be added to other compilation switches. This
+switch needs to be specified both during compilation and link stages, and can
+be specified once when using gnatmake:
+
+@smallexample
+gnatmake -f -pg -P my_project
+@end smallexample
+
+@noindent
+Note that only the objects that were compiled with the @samp{-pg} switch will be
+profiled; if you need to profile your whole project, use the
+@samp{-f} gnatmake switch to force full recompilation.
+
+@node Program execution
+@subsection Program execution
+
+@noindent
+Once the program has been compiled for profiling, you can run it as usual.
+
+The only constraint imposed by profiling is that the program must terminate
+normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
+properly analyzed.
+
+Once the program completes execution, a data file called @file{gmon.out} is
+generated in the directory where the program was launched from. If this file
+already exists, it will be overwritten.
+
+@node Running gprof
+@subsection Running gprof
+
+@noindent
+The @code{gprof} tool is called as follow:
+
+@smallexample
+gprof my_prog gmon.out
+@end smallexample
+
+@noindent
+or simpler:
+
+@smallexample
+gprof my_prog
+@end smallexample
+
+@noindent
+The complete form of the gprof command line is the following:
+
+@smallexample
+gprof [^switches^options^] [executable [data-file]]
+@end smallexample
+
+@noindent
+@code{gprof} supports numerous ^switch^options^. The order of these
+^switch^options^ does not matter. The full list of options can be found in
+the GNU Profiler User's Guide documentation that comes with this documentation.
+
+The following is the subset of those switches that is most relevant:
+
+@table @option
+
+@item --demangle[=@var{style}]
+@itemx --no-demangle
+@cindex @option{--demangle} (@code{gprof})
+These options control whether symbol names should be demangled when
+printing output. The default is to demangle C++ symbols. The
+@code{--no-demangle} option may be used to turn off demangling. Different
+compilers have different mangling styles. The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler, in particular Ada symbols generated by GNAT can be demangled using
+@code{--demangle=gnat}.
+
+@item -e @var{function_name}
+@cindex @option{-e} (@code{gprof})
+The @samp{-e @var{function}} option tells @code{gprof} not to print
+information about the function @var{function_name} (and its
+children@dots{}) in the call graph. The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as @samp{[not printed]}. More than one @samp{-e} option may be
+given; only one @var{function_name} may be indicated with each @samp{-e}
+option.
+
+@item -E @var{function_name}
+@cindex @option{-E} (@code{gprof})
+The @code{-E @var{function}} option works like the @code{-e} option, but
+execution time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph. More than one @samp{-E} option may be given; only one
+@var{function_name} may be indicated with each @samp{-E} option.
+
+@item -f @var{function_name}
+@cindex @option{-f} (@code{gprof})
+The @samp{-f @var{function}} option causes @code{gprof} to limit the
+call graph to the function @var{function_name} and its children (and
+their children@dots{}). More than one @samp{-f} option may be given;
+only one @var{function_name} may be indicated with each @samp{-f}
+option.
+
+@item -F @var{function_name}
+@cindex @option{-F} (@code{gprof})
+The @samp{-F @var{function}} option works like the @code{-f} option, but
+only time spent in the function and its children (and their
+children@dots{}) will be used to determine total-time and
+percentages-of-time for the call graph. More than one @samp{-F} option
+may be given; only one @var{function_name} may be indicated with each
+@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
+
+@end table
+
+@node Interpretation of profiling results
+@subsection Interpretation of profiling results
+
+@noindent
+
+The results of the profiling analysis are represented by two arrays: the
+'flat profile' and the 'call graph'. Full documentation of those outputs
+can be found in the GNU Profiler User's Guide.
+
+The flat profile shows the time spent in each function of the program, and how
+many time it has been called. This allows you to locate easily the most
+time-consuming functions.
+
+The call graph shows, for each subprogram, the subprograms that call it,
+and the subprograms that it calls. It also provides an estimate of the time
+spent in each of those callers/called subprograms.
+@end ifclear
+
+@c ******************************
@node Running and Debugging Ada Programs
@chapter Running and Debugging Ada Programs
@cindex Debugging
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
specify a sufficiently large size for the stack of the task that contains
this call.
+@node Irix-Specific Considerations
+@section Irix-Specific Considerations
+@cindex Irix libraries
+
+@noindent
+The GCC support libraries coming with the Irix compiler have moved to
+their canonical place with respect to the general Irix ABI related
+conventions. Running applications built with the default shared GNAT
+run-time now requires the LD_LIBRARY_PATH environment variable to
+include this location. A possible way to achieve this is to issue the
+following command line on a bash prompt:
+
+@smallexample
+@group
+$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\``
+@end group
+@end smallexample
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
projects / gcc.git / commitdiff