1.. role:: switch(samp) 2 3.. _Implementation_Defined_Pragmas: 4 5****************************** 6Implementation Defined Pragmas 7****************************** 8 9Ada defines a set of pragmas that can be used to supply additional 10information to the compiler. These language defined pragmas are 11implemented in GNAT and work as described in the Ada Reference Manual. 12 13In addition, Ada allows implementations to define additional pragmas 14whose meaning is defined by the implementation. GNAT provides a number 15of these implementation-defined pragmas, which can be used to extend 16and enhance the functionality of the compiler. This section of the GNAT 17Reference Manual describes these additional pragmas. 18 19Note that any program using these pragmas might not be portable to other 20compilers (although GNAT implements this set of pragmas on all 21platforms). Therefore if portability to other compilers is an important 22consideration, the use of these pragmas should be minimized. 23 24Pragma Abort_Defer 25================== 26 27.. index:: Deferring aborts 28 29Syntax: 30 31.. code-block:: ada 32 33 pragma Abort_Defer; 34 35 36This pragma must appear at the start of the statement sequence of a 37handled sequence of statements (right after the ``begin``). It has 38the effect of deferring aborts for the sequence of statements (but not 39for the declarations or handlers, if any, associated with this statement 40sequence). This can also be useful for adding a polling point in Ada code, 41where asynchronous abort of tasks is checked when leaving the statement 42sequence, and is lighter than, for example, using ``delay 0.0;``, since with 43zero-cost exception handling, propagating exceptions (implicitly used to 44implement task abort) cannot be done reliably in an asynchronous way. 45 46An example of usage would be: 47 48.. code-block:: ada 49 50 -- Add a polling point to check for task aborts 51 52 begin 53 pragma Abort_Defer; 54 end; 55 56.. _Pragma-Abstract_State: 57 58Pragma Abstract_State 59===================== 60 61Syntax: 62 63.. code-block:: ada 64 65 pragma Abstract_State (ABSTRACT_STATE_LIST); 66 67 ABSTRACT_STATE_LIST ::= 68 null 69 | STATE_NAME_WITH_OPTIONS 70 | (STATE_NAME_WITH_OPTIONS {, STATE_NAME_WITH_OPTIONS} ) 71 72 STATE_NAME_WITH_OPTIONS ::= 73 STATE_NAME 74 | (STATE_NAME with OPTION_LIST) 75 76 OPTION_LIST ::= OPTION {, OPTION} 77 78 OPTION ::= 79 SIMPLE_OPTION 80 | NAME_VALUE_OPTION 81 82 SIMPLE_OPTION ::= Ghost | Synchronous 83 84 NAME_VALUE_OPTION ::= 85 Part_Of => ABSTRACT_STATE 86 | External [=> EXTERNAL_PROPERTY_LIST] 87 88 EXTERNAL_PROPERTY_LIST ::= 89 EXTERNAL_PROPERTY 90 | (EXTERNAL_PROPERTY {, EXTERNAL_PROPERTY} ) 91 92 EXTERNAL_PROPERTY ::= 93 Async_Readers [=> boolean_EXPRESSION] 94 | Async_Writers [=> boolean_EXPRESSION] 95 | Effective_Reads [=> boolean_EXPRESSION] 96 | Effective_Writes [=> boolean_EXPRESSION] 97 others => boolean_EXPRESSION 98 99 STATE_NAME ::= defining_identifier 100 101 ABSTRACT_STATE ::= name 102 103For the semantics of this pragma, see the entry for aspect ``Abstract_State`` in 104the SPARK 2014 Reference Manual, section 7.1.4. 105 106Pragma Ada_83 107============= 108 109Syntax: 110 111.. code-block:: ada 112 113 pragma Ada_83; 114 115 116A configuration pragma that establishes Ada 83 mode for the unit to 117which it applies, regardless of the mode set by the command line 118switches. In Ada 83 mode, GNAT attempts to be as compatible with 119the syntax and semantics of Ada 83, as defined in the original Ada 12083 Reference Manual as possible. In particular, the keywords added by Ada 95 121and Ada 2005 are not recognized, optional package bodies are allowed, 122and generics may name types with unknown discriminants without using 123the ``(<>)`` notation. In addition, some but not all of the additional 124restrictions of Ada 83 are enforced. 125 126Ada 83 mode is intended for two purposes. Firstly, it allows existing 127Ada 83 code to be compiled and adapted to GNAT with less effort. 128Secondly, it aids in keeping code backwards compatible with Ada 83. 129However, there is no guarantee that code that is processed correctly 130by GNAT in Ada 83 mode will in fact compile and execute with an Ada 13183 compiler, since GNAT does not enforce all the additional checks 132required by Ada 83. 133 134Pragma Ada_95 135============= 136 137Syntax: 138 139.. code-block:: ada 140 141 pragma Ada_95; 142 143 144A configuration pragma that establishes Ada 95 mode for the unit to which 145it applies, regardless of the mode set by the command line switches. 146This mode is set automatically for the ``Ada`` and ``System`` 147packages and their children, so you need not specify it in these 148contexts. This pragma is useful when writing a reusable component that 149itself uses Ada 95 features, but which is intended to be usable from 150either Ada 83 or Ada 95 programs. 151 152Pragma Ada_05 153============= 154 155Syntax: 156 157.. code-block:: ada 158 159 pragma Ada_05; 160 pragma Ada_05 (local_NAME); 161 162 163A configuration pragma that establishes Ada 2005 mode for the unit to which 164it applies, regardless of the mode set by the command line switches. 165This pragma is useful when writing a reusable component that 166itself uses Ada 2005 features, but which is intended to be usable from 167either Ada 83 or Ada 95 programs. 168 169The one argument form (which is not a configuration pragma) 170is used for managing the transition from 171Ada 95 to Ada 2005 in the run-time library. If an entity is marked 172as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 173mode will generate a warning. In addition, in Ada_83 or Ada_95 174mode, a preference rule is established which does not choose 175such an entity unless it is unambiguously specified. This avoids 176extra subprograms marked this way from generating ambiguities in 177otherwise legal pre-Ada_2005 programs. The one argument form is 178intended for exclusive use in the GNAT run-time library. 179 180Pragma Ada_2005 181=============== 182 183Syntax: 184 185.. code-block:: ada 186 187 pragma Ada_2005; 188 189 190This configuration pragma is a synonym for pragma Ada_05 and has the 191same syntax and effect. 192 193Pragma Ada_12 194============= 195 196Syntax: 197 198.. code-block:: ada 199 200 pragma Ada_12; 201 pragma Ada_12 (local_NAME); 202 203 204A configuration pragma that establishes Ada 2012 mode for the unit to which 205it applies, regardless of the mode set by the command line switches. 206This mode is set automatically for the ``Ada`` and ``System`` 207packages and their children, so you need not specify it in these 208contexts. This pragma is useful when writing a reusable component that 209itself uses Ada 2012 features, but which is intended to be usable from 210Ada 83, Ada 95, or Ada 2005 programs. 211 212The one argument form, which is not a configuration pragma, 213is used for managing the transition from Ada 2142005 to Ada 2012 in the run-time library. If an entity is marked 215as Ada_2012 only, then referencing the entity in any pre-Ada_2012 216mode will generate a warning. In addition, in any pre-Ada_2012 217mode, a preference rule is established which does not choose 218such an entity unless it is unambiguously specified. This avoids 219extra subprograms marked this way from generating ambiguities in 220otherwise legal pre-Ada_2012 programs. The one argument form is 221intended for exclusive use in the GNAT run-time library. 222 223Pragma Ada_2012 224=============== 225 226Syntax: 227 228.. code-block:: ada 229 230 pragma Ada_2012; 231 232 233This configuration pragma is a synonym for pragma Ada_12 and has the 234same syntax and effect. 235 236Pragma Aggregate_Individually_Assign 237==================================== 238 239Syntax: 240 241.. code-block:: ada 242 243 pragma Aggregate_Individually_Assign; 244 245Where possible, GNAT will store the binary representation of a record aggregate 246in memory for space and performance reasons. This configuration pragma changes 247this behavior so that record aggregates are instead always converted into 248individual assignment statements. 249 250 251Pragma Allow_Integer_Address 252============================ 253 254Syntax: 255 256.. code-block:: ada 257 258 pragma Allow_Integer_Address; 259 260 261In almost all versions of GNAT, ``System.Address`` is a private 262type in accordance with the implementation advice in the RM. This 263means that integer values, 264in particular integer literals, are not allowed as address values. 265If the configuration pragma 266``Allow_Integer_Address`` is given, then integer expressions may 267be used anywhere a value of type ``System.Address`` is required. 268The effect is to introduce an implicit unchecked conversion from the 269integer value to type ``System.Address``. The reverse case of using 270an address where an integer type is required is handled analogously. 271The following example compiles without errors: 272 273 274.. code-block:: ada 275 276 pragma Allow_Integer_Address; 277 with System; use System; 278 package AddrAsInt is 279 X : Integer; 280 Y : Integer; 281 for X'Address use 16#1240#; 282 for Y use at 16#3230#; 283 m : Address := 16#4000#; 284 n : constant Address := 4000; 285 p : constant Address := Address (X + Y); 286 v : Integer := y'Address; 287 w : constant Integer := Integer (Y'Address); 288 type R is new integer; 289 RR : R := 1000; 290 Z : Integer; 291 for Z'Address use RR; 292 end AddrAsInt; 293 294 295Note that pragma ``Allow_Integer_Address`` is ignored if ``System.Address`` 296is not a private type. In implementations of ``GNAT`` where 297System.Address is a visible integer type, 298this pragma serves no purpose but is ignored 299rather than rejected to allow common sets of sources to be used 300in the two situations. 301 302.. _Pragma-Annotate: 303 304Pragma Annotate 305=============== 306 307Syntax:: 308 309 pragma Annotate (IDENTIFIER [, IDENTIFIER {, ARG}] [, entity => local_NAME]); 310 311 ARG ::= NAME | EXPRESSION 312 313 314This pragma is used to annotate programs. IDENTIFIER identifies 315the type of annotation. GNAT verifies that it is an identifier, but does 316not otherwise analyze it. The second optional identifier is also left 317unanalyzed, and by convention is used to control the action of the tool to 318which the annotation is addressed. The remaining ARG arguments 319can be either string literals or more generally expressions. 320String literals (and concatenations of string literals) are assumed to be 321either of type 322``Standard.String`` or else ``Wide_String`` or ``Wide_Wide_String`` 323depending on the character literals they contain. 324All other kinds of arguments are analyzed as expressions, and must be 325unambiguous. The last argument if present must have the identifier 326``Entity`` and GNAT verifies that a local name is given. 327 328The analyzed pragma is retained in the tree, but not otherwise processed 329by any part of the GNAT compiler, except to generate corresponding note 330lines in the generated ALI file. For the format of these note lines, see 331the compiler source file lib-writ.ads. This pragma is intended for use by 332external tools, including ASIS. The use of pragma Annotate does not 333affect the compilation process in any way. This pragma may be used as 334a configuration pragma. 335 336Pragma Assert 337============= 338 339Syntax:: 340 341 pragma Assert ( 342 boolean_EXPRESSION 343 [, string_EXPRESSION]); 344 345 346The effect of this pragma depends on whether the corresponding command 347line switch is set to activate assertions. The pragma expands into code 348equivalent to the following: 349 350.. code-block:: ada 351 352 if assertions-enabled then 353 if not boolean_EXPRESSION then 354 System.Assertions.Raise_Assert_Failure 355 (string_EXPRESSION); 356 end if; 357 end if; 358 359 360The string argument, if given, is the message that will be associated 361with the exception occurrence if the exception is raised. If no second 362argument is given, the default message is ``file``:``nnn``, 363where ``file`` is the name of the source file containing the assert, 364and ``nnn`` is the line number of the assert. 365 366Note that, as with the ``if`` statement to which it is equivalent, the 367type of the expression is either ``Standard.Boolean``, or any type derived 368from this standard type. 369 370Assert checks can be either checked or ignored. By default they are ignored. 371They will be checked if either the command line switch *-gnata* is 372used, or if an ``Assertion_Policy`` or ``Check_Policy`` pragma is used 373to enable ``Assert_Checks``. 374 375If assertions are ignored, then there 376is no run-time effect (and in particular, any side effects from the 377expression will not occur at run time). (The expression is still 378analyzed at compile time, and may cause types to be frozen if they are 379mentioned here for the first time). 380 381If assertions are checked, then the given expression is tested, and if 382it is ``False`` then ``System.Assertions.Raise_Assert_Failure`` is called 383which results in the raising of ``Assert_Failure`` with the given message. 384 385You should generally avoid side effects in the expression arguments of 386this pragma, because these side effects will turn on and off with the 387setting of the assertions mode, resulting in assertions that have an 388effect on the program. However, the expressions are analyzed for 389semantic correctness whether or not assertions are enabled, so turning 390assertions on and off cannot affect the legality of a program. 391 392Note that the implementation defined policy ``DISABLE``, given in a 393pragma ``Assertion_Policy``, can be used to suppress this semantic analysis. 394 395Note: this is a standard language-defined pragma in versions 396of Ada from 2005 on. In GNAT, it is implemented in all versions 397of Ada, and the DISABLE policy is an implementation-defined 398addition. 399 400Pragma Assert_And_Cut 401===================== 402 403Syntax:: 404 405 pragma Assert_And_Cut ( 406 boolean_EXPRESSION 407 [, string_EXPRESSION]); 408 409 410The effect of this pragma is identical to that of pragma ``Assert``, 411except that in an ``Assertion_Policy`` pragma, the identifier 412``Assert_And_Cut`` is used to control whether it is ignored or checked 413(or disabled). 414 415The intention is that this be used within a subprogram when the 416given test expresion sums up all the work done so far in the 417subprogram, so that the rest of the subprogram can be verified 418(informally or formally) using only the entry preconditions, 419and the expression in this pragma. This allows dividing up 420a subprogram into sections for the purposes of testing or 421formal verification. The pragma also serves as useful 422documentation. 423 424Pragma Assertion_Policy 425======================= 426 427Syntax:: 428 429 pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); 430 431 pragma Assertion_Policy ( 432 ASSERTION_KIND => POLICY_IDENTIFIER 433 {, ASSERTION_KIND => POLICY_IDENTIFIER}); 434 435 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 436 437 RM_ASSERTION_KIND ::= Assert | 438 Static_Predicate | 439 Dynamic_Predicate | 440 Pre | 441 Pre'Class | 442 Post | 443 Post'Class | 444 Type_Invariant | 445 Type_Invariant'Class | 446 Default_Initial_Condition 447 448 ID_ASSERTION_KIND ::= Assertions | 449 Assert_And_Cut | 450 Assume | 451 Contract_Cases | 452 Debug | 453 Ghost | 454 Initial_Condition | 455 Invariant | 456 Invariant'Class | 457 Loop_Invariant | 458 Loop_Variant | 459 Postcondition | 460 Precondition | 461 Predicate | 462 Refined_Post | 463 Statement_Assertions | 464 Subprogram_Variant 465 466 POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 467 468 469This is a standard Ada 2012 pragma that is available as an 470implementation-defined pragma in earlier versions of Ada. 471The assertion kinds ``RM_ASSERTION_KIND`` are those defined in 472the Ada standard. The assertion kinds ``ID_ASSERTION_KIND`` 473are implementation defined additions recognized by the GNAT compiler. 474 475The pragma applies in both cases to pragmas and aspects with matching 476names, e.g. ``Pre`` applies to the Pre aspect, and ``Precondition`` 477applies to both the ``Precondition`` pragma 478and the aspect ``Precondition``. Note that the identifiers for 479pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 480Pre_Class and Post_Class), since these pragmas are intended to be 481identical to the corresponding aspects). 482 483If the policy is ``CHECK``, then assertions are enabled, i.e. 484the corresponding pragma or aspect is activated. 485If the policy is ``IGNORE``, then assertions are ignored, i.e. 486the corresponding pragma or aspect is deactivated. 487This pragma overrides the effect of the *-gnata* switch on the 488command line. 489If the policy is ``SUPPRESSIBLE``, then assertions are enabled by default, 490however, if the *-gnatp* switch is specified all assertions are ignored. 491 492The implementation defined policy ``DISABLE`` is like 493``IGNORE`` except that it completely disables semantic 494checking of the corresponding pragma or aspect. This is 495useful when the pragma or aspect argument references subprograms 496in a with'ed package which is replaced by a dummy package 497for the final build. 498 499The implementation defined assertion kind ``Assertions`` applies to all 500assertion kinds. The form with no assertion kind given implies this 501choice, so it applies to all assertion kinds (RM defined, and 502implementation defined). 503 504The implementation defined assertion kind ``Statement_Assertions`` 505applies to ``Assert``, ``Assert_And_Cut``, 506``Assume``, ``Loop_Invariant``, and ``Loop_Variant``. 507 508Pragma Assume 509============= 510 511Syntax: 512 513:: 514 515 pragma Assume ( 516 boolean_EXPRESSION 517 [, string_EXPRESSION]); 518 519 520The effect of this pragma is identical to that of pragma ``Assert``, 521except that in an ``Assertion_Policy`` pragma, the identifier 522``Assume`` is used to control whether it is ignored or checked 523(or disabled). 524 525The intention is that this be used for assumptions about the 526external environment. So you cannot expect to verify formally 527or informally that the condition is met, this must be 528established by examining things outside the program itself. 529For example, we may have code that depends on the size of 530``Long_Long_Integer`` being at least 64. So we could write: 531 532.. code-block:: ada 533 534 pragma Assume (Long_Long_Integer'Size >= 64); 535 536 537This assumption cannot be proved from the program itself, 538but it acts as a useful run-time check that the assumption 539is met, and documents the need to ensure that it is met by 540reference to information outside the program. 541 542Pragma Assume_No_Invalid_Values 543=============================== 544.. index:: Invalid representations 545 546.. index:: Invalid values 547 548Syntax: 549 550.. code-block:: ada 551 552 pragma Assume_No_Invalid_Values (On | Off); 553 554 555This is a configuration pragma that controls the assumptions made by the 556compiler about the occurrence of invalid representations (invalid values) 557in the code. 558 559The default behavior (corresponding to an Off argument for this pragma), is 560to assume that values may in general be invalid unless the compiler can 561prove they are valid. Consider the following example: 562 563.. code-block:: ada 564 565 V1 : Integer range 1 .. 10; 566 V2 : Integer range 11 .. 20; 567 ... 568 for J in V2 .. V1 loop 569 ... 570 end loop; 571 572 573if V1 and V2 have valid values, then the loop is known at compile 574time not to execute since the lower bound must be greater than the 575upper bound. However in default mode, no such assumption is made, 576and the loop may execute. If ``Assume_No_Invalid_Values (On)`` 577is given, the compiler will assume that any occurrence of a variable 578other than in an explicit ``'Valid`` test always has a valid 579value, and the loop above will be optimized away. 580 581The use of ``Assume_No_Invalid_Values (On)`` is appropriate if 582you know your code is free of uninitialized variables and other 583possible sources of invalid representations, and may result in 584more efficient code. A program that accesses an invalid representation 585with this pragma in effect is erroneous, so no guarantees can be made 586about its behavior. 587 588It is peculiar though permissible to use this pragma in conjunction 589with validity checking (-gnatVa). In such cases, accessing invalid 590values will generally give an exception, though formally the program 591is erroneous so there are no guarantees that this will always be the 592case, and it is recommended that these two options not be used together. 593 594.. _Pragma-Async_Readers: 595 596Pragma Async_Readers 597==================== 598 599Syntax: 600 601.. code-block:: ada 602 603 pragma Async_Readers [ (boolean_EXPRESSION) ]; 604 605For the semantics of this pragma, see the entry for aspect ``Async_Readers`` in 606the SPARK 2014 Reference Manual, section 7.1.2. 607 608.. _Pragma-Async_Writers: 609 610Pragma Async_Writers 611==================== 612 613Syntax: 614 615.. code-block:: ada 616 617 pragma Async_Writers [ (boolean_EXPRESSION) ]; 618 619For the semantics of this pragma, see the entry for aspect ``Async_Writers`` in 620the SPARK 2014 Reference Manual, section 7.1.2. 621 622Pragma Attribute_Definition 623=========================== 624 625Syntax: 626 627:: 628 629 pragma Attribute_Definition 630 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 631 [Entity =>] LOCAL_NAME, 632 [Expression =>] EXPRESSION | NAME); 633 634 635If ``Attribute`` is a known attribute name, this pragma is equivalent to 636the attribute definition clause: 637 638 639.. code-block:: ada 640 641 for Entity'Attribute use Expression; 642 643 644If ``Attribute`` is not a recognized attribute name, the pragma is 645ignored, and a warning is emitted. This allows source 646code to be written that takes advantage of some new attribute, while remaining 647compilable with earlier compilers. 648 649Pragma C_Pass_By_Copy 650===================== 651.. index:: Passing by copy 652 653 654Syntax: 655 656:: 657 658 pragma C_Pass_By_Copy 659 ([Max_Size =>] static_integer_EXPRESSION); 660 661 662Normally the default mechanism for passing C convention records to C 663convention subprograms is to pass them by reference, as suggested by RM 664B.3(69). Use the configuration pragma ``C_Pass_By_Copy`` to change 665this default, by requiring that record formal parameters be passed by 666copy if all of the following conditions are met: 667 668* 669 The size of the record type does not exceed the value specified for 670 ``Max_Size``. 671* 672 The record type has ``Convention C``. 673* 674 The formal parameter has this record type, and the subprogram has a 675 foreign (non-Ada) convention. 676 677If these conditions are met the argument is passed by copy; i.e., in a 678manner consistent with what C expects if the corresponding formal in the 679C prototype is a struct (rather than a pointer to a struct). 680 681You can also pass records by copy by specifying the convention 682``C_Pass_By_Copy`` for the record type, or by using the extended 683``Import`` and ``Export`` pragmas, which allow specification of 684passing mechanisms on a parameter by parameter basis. 685 686Pragma Check 687============ 688.. index:: Assertions 689 690.. index:: Named assertions 691 692 693Syntax: 694 695:: 696 697 pragma Check ( 698 [Name =>] CHECK_KIND, 699 [Check =>] Boolean_EXPRESSION 700 [, [Message =>] string_EXPRESSION] ); 701 702 CHECK_KIND ::= IDENTIFIER | 703 Pre'Class | 704 Post'Class | 705 Type_Invariant'Class | 706 Invariant'Class 707 708 709This pragma is similar to the predefined pragma ``Assert`` except that an 710extra identifier argument is present. In conjunction with pragma 711``Check_Policy``, this can be used to define groups of assertions that can 712be independently controlled. The identifier ``Assertion`` is special, it 713refers to the normal set of pragma ``Assert`` statements. 714 715Checks introduced by this pragma are normally deactivated by default. They can 716be activated either by the command line option *-gnata*, which turns on 717all checks, or individually controlled using pragma ``Check_Policy``. 718 719The identifiers ``Assertions`` and ``Statement_Assertions`` are not 720permitted as check kinds, since this would cause confusion with the use 721of these identifiers in ``Assertion_Policy`` and ``Check_Policy`` 722pragmas, where they are used to refer to sets of assertions. 723 724Pragma Check_Float_Overflow 725=========================== 726.. index:: Floating-point overflow 727 728 729Syntax: 730 731.. code-block:: ada 732 733 pragma Check_Float_Overflow; 734 735 736In Ada, the predefined floating-point types (``Short_Float``, 737``Float``, ``Long_Float``, ``Long_Long_Float``) are 738defined to be *unconstrained*. This means that even though each 739has a well-defined base range, an operation that delivers a result 740outside this base range is not required to raise an exception. 741This implementation permission accommodates the notion 742of infinities in IEEE floating-point, and corresponds to the 743efficient execution mode on most machines. GNAT will not raise 744overflow exceptions on these machines; instead it will generate 745infinities and NaN's as defined in the IEEE standard. 746 747Generating infinities, although efficient, is not always desirable. 748Often the preferable approach is to check for overflow, even at the 749(perhaps considerable) expense of run-time performance. 750This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 751range constraints -- and indeed such a subtype 752can have the same base range as its base type. For example: 753 754 755.. code-block:: ada 756 757 subtype My_Float is Float range Float'Range; 758 759 760Here ``My_Float`` has the same range as 761``Float`` but is constrained, so operations on 762``My_Float`` values will be checked for overflow 763against this range. 764 765This style will achieve the desired goal, but 766it is often more convenient to be able to simply use 767the standard predefined floating-point types as long 768as overflow checking could be guaranteed. 769The ``Check_Float_Overflow`` 770configuration pragma achieves this effect. If a unit is compiled 771subject to this configuration pragma, then all operations 772on predefined floating-point types including operations on 773base types of these floating-point types will be treated as 774though those types were constrained, and overflow checks 775will be generated. The ``Constraint_Error`` 776exception is raised if the result is out of range. 777 778This mode can also be set by use of the compiler 779switch *-gnateF*. 780 781Pragma Check_Name 782================= 783.. index:: Defining check names 784 785.. index:: Check names, defining 786 787 788Syntax: 789 790.. code-block:: ada 791 792 pragma Check_Name (check_name_IDENTIFIER); 793 794 795This is a configuration pragma that defines a new implementation 796defined check name (unless IDENTIFIER matches one of the predefined 797check names, in which case the pragma has no effect). Check names 798are global to a partition, so if two or more configuration pragmas 799are present in a partition mentioning the same name, only one new 800check name is introduced. 801 802An implementation defined check name introduced with this pragma may 803be used in only three contexts: ``pragma Suppress``, 804``pragma Unsuppress``, 805and as the prefix of a ``Check_Name'Enabled`` attribute reference. For 806any of these three cases, the check name must be visible. A check 807name is visible if it is in the configuration pragmas applying to 808the current unit, or if it appears at the start of any unit that 809is part of the dependency set of the current unit (e.g., units that 810are mentioned in ``with`` clauses). 811 812Check names introduced by this pragma are subject to control by compiler 813switches (in particular -gnatp) in the usual manner. 814 815Pragma Check_Policy 816=================== 817.. index:: Controlling assertions 818 819.. index:: Assertions, control 820 821.. index:: Check pragma control 822 823.. index:: Named assertions 824 825 826Syntax: 827 828:: 829 830 pragma Check_Policy 831 ([Name =>] CHECK_KIND, 832 [Policy =>] POLICY_IDENTIFIER); 833 834 pragma Check_Policy ( 835 CHECK_KIND => POLICY_IDENTIFIER 836 {, CHECK_KIND => POLICY_IDENTIFIER}); 837 838 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 839 840 CHECK_KIND ::= IDENTIFIER | 841 Pre'Class | 842 Post'Class | 843 Type_Invariant'Class | 844 Invariant'Class 845 846 The identifiers Name and Policy are not allowed as CHECK_KIND values. This 847 avoids confusion between the two possible syntax forms for this pragma. 848 849 POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 850 851 852This pragma is used to set the checking policy for assertions (specified 853by aspects or pragmas), the ``Debug`` pragma, or additional checks 854to be checked using the ``Check`` pragma. It may appear either as 855a configuration pragma, or within a declarative part of package. In the 856latter case, it applies from the point where it appears to the end of 857the declarative region (like pragma ``Suppress``). 858 859The ``Check_Policy`` pragma is similar to the 860predefined ``Assertion_Policy`` pragma, 861and if the check kind corresponds to one of the assertion kinds that 862are allowed by ``Assertion_Policy``, then the effect is identical. 863 864If the first argument is Debug, then the policy applies to Debug pragmas, 865disabling their effect if the policy is ``OFF``, ``DISABLE``, or 866``IGNORE``, and allowing them to execute with normal semantics if 867the policy is ``ON`` or ``CHECK``. In addition if the policy is 868``DISABLE``, then the procedure call in ``Debug`` pragmas will 869be totally ignored and not analyzed semantically. 870 871Finally the first argument may be some other identifier than the above 872possibilities, in which case it controls a set of named assertions 873that can be checked using pragma ``Check``. For example, if the pragma: 874 875 876.. code-block:: ada 877 878 pragma Check_Policy (Critical_Error, OFF); 879 880 881is given, then subsequent ``Check`` pragmas whose first argument is also 882``Critical_Error`` will be disabled. 883 884The check policy is ``OFF`` to turn off corresponding checks, and ``ON`` 885to turn on corresponding checks. The default for a set of checks for which no 886``Check_Policy`` is given is ``OFF`` unless the compiler switch 887*-gnata* is given, which turns on all checks by default. 888 889The check policy settings ``CHECK`` and ``IGNORE`` are recognized 890as synonyms for ``ON`` and ``OFF``. These synonyms are provided for 891compatibility with the standard ``Assertion_Policy`` pragma. The check 892policy setting ``DISABLE`` causes the second argument of a corresponding 893``Check`` pragma to be completely ignored and not analyzed. 894 895Pragma Comment 896============== 897 898Syntax: 899 900 901.. code-block:: ada 902 903 pragma Comment (static_string_EXPRESSION); 904 905 906This is almost identical in effect to pragma ``Ident``. It allows the 907placement of a comment into the object file and hence into the 908executable file if the operating system permits such usage. The 909difference is that ``Comment``, unlike ``Ident``, has 910no limitations on placement of the pragma (it can be placed 911anywhere in the main source unit), and if more than one pragma 912is used, all comments are retained. 913 914Pragma Common_Object 915==================== 916 917Syntax: 918 919 920:: 921 922 pragma Common_Object ( 923 [Internal =>] LOCAL_NAME 924 [, [External =>] EXTERNAL_SYMBOL] 925 [, [Size =>] EXTERNAL_SYMBOL] ); 926 927 EXTERNAL_SYMBOL ::= 928 IDENTIFIER 929 | static_string_EXPRESSION 930 931 932This pragma enables the shared use of variables stored in overlaid 933linker areas corresponding to the use of ``COMMON`` 934in Fortran. The single 935object ``LOCAL_NAME`` is assigned to the area designated by 936the ``External`` argument. 937You may define a record to correspond to a series 938of fields. The ``Size`` argument 939is syntax checked in GNAT, but otherwise ignored. 940 941``Common_Object`` is not supported on all platforms. If no 942support is available, then the code generator will issue a message 943indicating that the necessary attribute for implementation of this 944pragma is not available. 945 946.. _Compile_Time_Error: 947 948Pragma Compile_Time_Error 949========================= 950 951Syntax: 952 953 954.. code-block:: ada 955 956 pragma Compile_Time_Error 957 (boolean_EXPRESSION, static_string_EXPRESSION); 958 959 960This pragma can be used to generate additional compile time 961error messages. It 962is particularly useful in generics, where errors can be issued for 963specific problematic instantiations. The first parameter is a boolean 964expression. The pragma ensures that the value of an expression 965is known at compile time, and has the value False. The set of expressions 966whose values are known at compile time includes all static boolean 967expressions, and also other values which the compiler can determine 968at compile time (e.g., the size of a record type set by an explicit 969size representation clause, or the value of a variable which was 970initialized to a constant and is known not to have been modified). 971If these conditions are not met, an error message is generated using 972the value given as the second argument. This string value may contain 973embedded ASCII.LF characters to break the message into multiple lines. 974 975Pragma Compile_Time_Warning 976=========================== 977 978Syntax: 979 980 981.. code-block:: ada 982 983 pragma Compile_Time_Warning 984 (boolean_EXPRESSION, static_string_EXPRESSION); 985 986 987Same as pragma Compile_Time_Error, except a warning is issued instead 988of an error message. If switch *-gnatw_C* is used, a warning is only issued 989if the value of the expression is known to be True at compile time, not when 990the value of the expression is not known at compile time. 991Note that if this pragma is used in a package that 992is with'ed by a client, the client will get the warning even though it 993is issued by a with'ed package (normally warnings in with'ed units are 994suppressed, but this is a special exception to that rule). 995 996One typical use is within a generic where compile time known characteristics 997of formal parameters are tested, and warnings given appropriately. Another use 998with a first parameter of True is to warn a client about use of a package, 999for example that it is not fully implemented. 1000 1001In previous versions of the compiler, combining *-gnatwe* with 1002Compile_Time_Warning resulted in a fatal error. Now the compiler always emits 1003a warning. You can use :ref:`Compile_Time_Error` to force the generation of 1004an error. 1005 1006Pragma Compiler_Unit 1007==================== 1008 1009Syntax: 1010 1011 1012.. code-block:: ada 1013 1014 pragma Compiler_Unit; 1015 1016 1017This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 1018retained so that old versions of the GNAT run-time that use this pragma can 1019be compiled with newer versions of the compiler. 1020 1021Pragma Compiler_Unit_Warning 1022============================ 1023 1024Syntax: 1025 1026 1027.. code-block:: ada 1028 1029 pragma Compiler_Unit_Warning; 1030 1031 1032This pragma is intended only for internal use in the GNAT run-time library. 1033It indicates that the unit is used as part of the compiler build. The effect 1034is to generate warnings for the use of constructs (for example, conditional 1035expressions) that would cause trouble when bootstrapping using an older 1036version of GNAT. For the exact list of restrictions, see the compiler sources 1037and references to Check_Compiler_Unit. 1038 1039Pragma Complete_Representation 1040============================== 1041 1042Syntax: 1043 1044 1045.. code-block:: ada 1046 1047 pragma Complete_Representation; 1048 1049 1050This pragma must appear immediately within a record representation 1051clause. Typical placements are before the first component clause 1052or after the last component clause. The effect is to give an error 1053message if any component is missing a component clause. This pragma 1054may be used to ensure that a record representation clause is 1055complete, and that this invariant is maintained if fields are 1056added to the record in the future. 1057 1058Pragma Complex_Representation 1059============================= 1060 1061Syntax: 1062 1063 1064:: 1065 1066 pragma Complex_Representation 1067 ([Entity =>] LOCAL_NAME); 1068 1069 1070The ``Entity`` argument must be the name of a record type which has 1071two fields of the same floating-point type. The effect of this pragma is 1072to force gcc to use the special internal complex representation form for 1073this record, which may be more efficient. Note that this may result in 1074the code for this type not conforming to standard ABI (application 1075binary interface) requirements for the handling of record types. For 1076example, in some environments, there is a requirement for passing 1077records by pointer, and the use of this pragma may result in passing 1078this type in floating-point registers. 1079 1080Pragma Component_Alignment 1081========================== 1082.. index:: Alignments of components 1083.. index:: Pragma Component_Alignment 1084 1085 1086Syntax: 1087 1088:: 1089 1090 pragma Component_Alignment ( 1091 [Form =>] ALIGNMENT_CHOICE 1092 [, [Name =>] type_LOCAL_NAME]); 1093 1094 ALIGNMENT_CHOICE ::= 1095 Component_Size 1096 | Component_Size_4 1097 | Storage_Unit 1098 | Default 1099 1100 1101Specifies the alignment of components in array or record types. 1102The meaning of the ``Form`` argument is as follows: 1103 1104 1105 .. index:: Component_Size (in pragma Component_Alignment) 1106 1107*Component_Size* 1108 Aligns scalar components and subcomponents of the array or record type 1109 on boundaries appropriate to their inherent size (naturally 1110 aligned). For example, 1-byte components are aligned on byte boundaries, 1111 2-byte integer components are aligned on 2-byte boundaries, 4-byte 1112 integer components are aligned on 4-byte boundaries and so on. These 1113 alignment rules correspond to the normal rules for C compilers on all 1114 machines except the VAX. 1115 1116 .. index:: Component_Size_4 (in pragma Component_Alignment) 1117 1118*Component_Size_4* 1119 Naturally aligns components with a size of four or fewer 1120 bytes. Components that are larger than 4 bytes are placed on the next 1121 4-byte boundary. 1122 1123 .. index:: Storage_Unit (in pragma Component_Alignment) 1124 1125*Storage_Unit* 1126 Specifies that array or record components are byte aligned, i.e., 1127 aligned on boundaries determined by the value of the constant 1128 ``System.Storage_Unit``. 1129 1130 .. index:: Default (in pragma Component_Alignment) 1131 1132*Default* 1133 Specifies that array or record components are aligned on default 1134 boundaries, appropriate to the underlying hardware or operating system or 1135 both. The ``Default`` choice is the same as ``Component_Size`` (natural 1136 alignment). 1137 1138If the ``Name`` parameter is present, ``type_LOCAL_NAME`` must 1139refer to a local record or array type, and the specified alignment 1140choice applies to the specified type. The use of 1141``Component_Alignment`` together with a pragma ``Pack`` causes the 1142``Component_Alignment`` pragma to be ignored. The use of 1143``Component_Alignment`` together with a record representation clause 1144is only effective for fields not specified by the representation clause. 1145 1146If the ``Name`` parameter is absent, the pragma can be used as either 1147a configuration pragma, in which case it applies to one or more units in 1148accordance with the normal rules for configuration pragmas, or it can be 1149used within a declarative part, in which case it applies to types that 1150are declared within this declarative part, or within any nested scope 1151within this declarative part. In either case it specifies the alignment 1152to be applied to any record or array type which has otherwise standard 1153representation. 1154 1155If the alignment for a record or array type is not specified (using 1156pragma ``Pack``, pragma ``Component_Alignment``, or a record rep 1157clause), the GNAT uses the default alignment as described previously. 1158 1159.. _Pragma-Constant_After_Elaboration: 1160 1161Pragma Constant_After_Elaboration 1162================================= 1163 1164Syntax: 1165 1166.. code-block:: ada 1167 1168 pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 1169 1170For the semantics of this pragma, see the entry for aspect 1171``Constant_After_Elaboration`` in the SPARK 2014 Reference Manual, section 3.3.1. 1172 1173.. _Pragma-Contract_Cases: 1174 1175Pragma Contract_Cases 1176===================== 1177.. index:: Contract cases 1178 1179Syntax: 1180 1181.. code-block:: ada 1182 1183 pragma Contract_Cases ((CONTRACT_CASE {, CONTRACT_CASE)); 1184 1185 CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 1186 1187 CASE_GUARD ::= boolean_EXPRESSION | others 1188 1189 CONSEQUENCE ::= boolean_EXPRESSION 1190 1191The ``Contract_Cases`` pragma allows defining fine-grain specifications 1192that can complement or replace the contract given by a precondition and a 1193postcondition. Additionally, the ``Contract_Cases`` pragma can be used 1194by testing and formal verification tools. The compiler checks its validity and, 1195depending on the assertion policy at the point of declaration of the pragma, 1196it may insert a check in the executable. For code generation, the contract 1197cases 1198 1199 1200.. code-block:: ada 1201 1202 pragma Contract_Cases ( 1203 Cond1 => Pred1, 1204 Cond2 => Pred2); 1205 1206 1207are equivalent to 1208 1209 1210.. code-block:: ada 1211 1212 C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 1213 C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 1214 pragma Precondition ((C1 and not C2) or (C2 and not C1)); 1215 pragma Postcondition (if C1 then Pred1); 1216 pragma Postcondition (if C2 then Pred2); 1217 1218 1219The precondition ensures that one and only one of the case guards is 1220satisfied on entry to the subprogram. 1221The postcondition ensures that for the case guard that was True on entry, 1222the corresponding consequence is True on exit. Other consequence expressions 1223are not evaluated. 1224 1225A precondition ``P`` and postcondition ``Q`` can also be 1226expressed as contract cases: 1227 1228.. code-block:: ada 1229 1230 pragma Contract_Cases (P => Q); 1231 1232 1233The placement and visibility rules for ``Contract_Cases`` pragmas are 1234identical to those described for preconditions and postconditions. 1235 1236The compiler checks that boolean expressions given in case guards and 1237consequences are valid, where the rules for case guards are the same as 1238the rule for an expression in ``Precondition`` and the rules for 1239consequences are the same as the rule for an expression in 1240``Postcondition``. In particular, attributes ``'Old`` and 1241``'Result`` can only be used within consequence expressions. 1242The case guard for the last contract case may be ``others``, to denote 1243any case not captured by the previous cases. The 1244following is an example of use within a package spec: 1245 1246 1247.. code-block:: ada 1248 1249 package Math_Functions is 1250 ... 1251 function Sqrt (Arg : Float) return Float; 1252 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 1253 Arg >= 100.0 => Sqrt'Result >= 10.0, 1254 others => Sqrt'Result = 0.0)); 1255 ... 1256 end Math_Functions; 1257 1258 1259The meaning of contract cases is that only one case should apply at each 1260call, as determined by the corresponding case guard evaluating to True, 1261and that the consequence for this case should hold when the subprogram 1262returns. 1263 1264Pragma Convention_Identifier 1265============================ 1266.. index:: Conventions, synonyms 1267 1268Syntax: 1269 1270 1271:: 1272 1273 pragma Convention_Identifier ( 1274 [Name =>] IDENTIFIER, 1275 [Convention =>] convention_IDENTIFIER); 1276 1277 1278This pragma provides a mechanism for supplying synonyms for existing 1279convention identifiers. The ``Name`` identifier can subsequently 1280be used as a synonym for the given convention in other pragmas (including 1281for example pragma ``Import`` or another ``Convention_Identifier`` 1282pragma). As an example of the use of this, suppose you had legacy code 1283which used Fortran77 as the identifier for Fortran. Then the pragma: 1284 1285 1286.. code-block:: ada 1287 1288 pragma Convention_Identifier (Fortran77, Fortran); 1289 1290 1291would allow the use of the convention identifier ``Fortran77`` in 1292subsequent code, avoiding the need to modify the sources. As another 1293example, you could use this to parameterize convention requirements 1294according to systems. Suppose you needed to use ``Stdcall`` on 1295windows systems, and ``C`` on some other system, then you could 1296define a convention identifier ``Library`` and use a single 1297``Convention_Identifier`` pragma to specify which convention 1298would be used system-wide. 1299 1300Pragma CPP_Class 1301================ 1302.. index:: Interfacing with C++ 1303 1304Syntax: 1305 1306 1307:: 1308 1309 pragma CPP_Class ([Entity =>] LOCAL_NAME); 1310 1311 1312The argument denotes an entity in the current declarative region that is 1313declared as a record type. It indicates that the type corresponds to an 1314externally declared C++ class type, and is to be laid out the same way 1315that C++ would lay out the type. If the C++ class has virtual primitives 1316then the record must be declared as a tagged record type. 1317 1318Types for which ``CPP_Class`` is specified do not have assignment or 1319equality operators defined (such operations can be imported or declared 1320as subprograms as required). Initialization is allowed only by constructor 1321functions (see pragma ``CPP_Constructor``). Such types are implicitly 1322limited if not explicitly declared as limited or derived from a limited 1323type, and an error is issued in that case. 1324 1325See :ref:`Interfacing_to_C++` for related information. 1326 1327Note: Pragma ``CPP_Class`` is currently obsolete. It is supported 1328for backward compatibility but its functionality is available 1329using pragma ``Import`` with ``Convention`` = ``CPP``. 1330 1331Pragma CPP_Constructor 1332====================== 1333.. index:: Interfacing with C++ 1334 1335 1336Syntax: 1337 1338 1339:: 1340 1341 pragma CPP_Constructor ([Entity =>] LOCAL_NAME 1342 [, [External_Name =>] static_string_EXPRESSION ] 1343 [, [Link_Name =>] static_string_EXPRESSION ]); 1344 1345 1346This pragma identifies an imported function (imported in the usual way 1347with pragma ``Import``) as corresponding to a C++ constructor. If 1348``External_Name`` and ``Link_Name`` are not specified then the 1349``Entity`` argument is a name that must have been previously mentioned 1350in a pragma ``Import`` with ``Convention`` = ``CPP``. Such name 1351must be of one of the following forms: 1352 1353* 1354 **function** ``Fname`` **return** T` 1355 1356* 1357 **function** ``Fname`` **return** T'Class 1358 1359* 1360 **function** ``Fname`` (...) **return** T` 1361 1362* 1363 **function** ``Fname`` (...) **return** T'Class 1364 1365where ``T`` is a limited record type imported from C++ with pragma 1366``Import`` and ``Convention`` = ``CPP``. 1367 1368The first two forms import the default constructor, used when an object 1369of type ``T`` is created on the Ada side with no explicit constructor. 1370The latter two forms cover all the non-default constructors of the type. 1371See the GNAT User's Guide for details. 1372 1373If no constructors are imported, it is impossible to create any objects 1374on the Ada side and the type is implicitly declared abstract. 1375 1376Pragma ``CPP_Constructor`` is intended primarily for automatic generation 1377using an automatic binding generator tool (such as the :switch:`-fdump-ada-spec` 1378GCC switch). 1379See :ref:`Interfacing_to_C++` for more related information. 1380 1381Note: The use of functions returning class-wide types for constructors is 1382currently obsolete. They are supported for backward compatibility. The 1383use of functions returning the type T leave the Ada sources more clear 1384because the imported C++ constructors always return an object of type T; 1385that is, they never return an object whose type is a descendant of type T. 1386 1387Pragma CPP_Virtual 1388================== 1389.. index:: Interfacing to C++ 1390 1391 1392This pragma is now obsolete and, other than generating a warning if warnings 1393on obsolescent features are enabled, is completely ignored. 1394It is retained for compatibility 1395purposes. It used to be required to ensure compoatibility with C++, but 1396is no longer required for that purpose because GNAT generates 1397the same object layout as the G++ compiler by default. 1398 1399See :ref:`Interfacing_to_C++` for related information. 1400 1401Pragma CPP_Vtable 1402================= 1403.. index:: Interfacing with C++ 1404 1405 1406This pragma is now obsolete and, other than generating a warning if warnings 1407on obsolescent features are enabled, is completely ignored. 1408It used to be required to ensure compatibility with C++, but 1409is no longer required for that purpose because GNAT generates 1410the same object layout as the G++ compiler by default. 1411 1412See :ref:`Interfacing_to_C++` for related information. 1413 1414Pragma CPU 1415========== 1416 1417Syntax: 1418 1419 1420.. code-block:: ada 1421 1422 pragma CPU (EXPRESSION); 1423 1424 1425This pragma is standard in Ada 2012, but is available in all earlier 1426versions of Ada as an implementation-defined pragma. 1427See Ada 2012 Reference Manual for details. 1428 1429Pragma Deadline_Floor 1430===================== 1431 1432Syntax: 1433 1434 1435.. code-block:: ada 1436 1437 pragma Deadline_Floor (time_span_EXPRESSION); 1438 1439 1440This pragma applies only to protected types and specifies the floor 1441deadline inherited by a task when the task enters a protected object. 1442It is effective only when the EDF scheduling policy is used. 1443 1444.. _Pragma-Default_Initial_Condition: 1445 1446Pragma Default_Initial_Condition 1447================================ 1448 1449Syntax: 1450 1451.. code-block:: ada 1452 1453 pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 1454 1455For the semantics of this pragma, see the entry for aspect 1456``Default_Initial_Condition`` in the SPARK 2014 Reference Manual, section 7.3.3. 1457 1458Pragma Debug 1459============ 1460 1461Syntax: 1462 1463 1464:: 1465 1466 pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 1467 1468 PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 1469 PROCEDURE_NAME 1470 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 1471 1472 1473The procedure call argument has the syntactic form of an expression, meeting 1474the syntactic requirements for pragmas. 1475 1476If debug pragmas are not enabled or if the condition is present and evaluates 1477to False, this pragma has no effect. If debug pragmas are enabled, the 1478semantics of the pragma is exactly equivalent to the procedure call statement 1479corresponding to the argument with a terminating semicolon. Pragmas are 1480permitted in sequences of declarations, so you can use pragma ``Debug`` to 1481intersperse calls to debug procedures in the middle of declarations. Debug 1482pragmas can be enabled either by use of the command line switch *-gnata* 1483or by use of the pragma ``Check_Policy`` with a first argument of 1484``Debug``. 1485 1486Pragma Debug_Policy 1487=================== 1488 1489Syntax: 1490 1491 1492.. code-block:: ada 1493 1494 pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 1495 1496 1497This pragma is equivalent to a corresponding ``Check_Policy`` pragma 1498with a first argument of ``Debug``. It is retained for historical 1499compatibility reasons. 1500 1501Pragma Default_Scalar_Storage_Order 1502=================================== 1503.. index:: Default_Scalar_Storage_Order 1504 1505.. index:: Scalar_Storage_Order 1506 1507 1508Syntax: 1509 1510 1511.. code-block:: ada 1512 1513 pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 1514 1515 1516Normally if no explicit ``Scalar_Storage_Order`` is given for a record 1517type or array type, then the scalar storage order defaults to the ordinary 1518default for the target. But this default may be overridden using this pragma. 1519The pragma may appear as a configuration pragma, or locally within a package 1520spec or declarative part. In the latter case, it applies to all subsequent 1521types declared within that package spec or declarative part. 1522 1523The following example shows the use of this pragma: 1524 1525 1526.. code-block:: ada 1527 1528 pragma Default_Scalar_Storage_Order (High_Order_First); 1529 with System; use System; 1530 package DSSO1 is 1531 type H1 is record 1532 a : Integer; 1533 end record; 1534 1535 type L2 is record 1536 a : Integer; 1537 end record; 1538 for L2'Scalar_Storage_Order use Low_Order_First; 1539 1540 type L2a is new L2; 1541 1542 package Inner is 1543 type H3 is record 1544 a : Integer; 1545 end record; 1546 1547 pragma Default_Scalar_Storage_Order (Low_Order_First); 1548 1549 type L4 is record 1550 a : Integer; 1551 end record; 1552 end Inner; 1553 1554 type H4a is new Inner.L4; 1555 1556 type H5 is record 1557 a : Integer; 1558 end record; 1559 end DSSO1; 1560 1561 1562In this example record types with names starting with *L* have `Low_Order_First` scalar 1563storage order, and record types with names starting with *H* have ``High_Order_First``. 1564Note that in the case of ``H4a``, the order is not inherited 1565from the parent type. Only an explicitly set ``Scalar_Storage_Order`` 1566gets inherited on type derivation. 1567 1568If this pragma is used as a configuration pragma which appears within a 1569configuration pragma file (as opposed to appearing explicitly at the start 1570of a single unit), then the binder will require that all units in a partition 1571be compiled in a similar manner, other than run-time units, which are not 1572affected by this pragma. Note that the use of this form is discouraged because 1573it may significantly degrade the run-time performance of the software, instead 1574the default scalar storage order ought to be changed only on a local basis. 1575 1576Pragma Default_Storage_Pool 1577=========================== 1578.. index:: Default_Storage_Pool 1579 1580 1581Syntax: 1582 1583 1584.. code-block:: ada 1585 1586 pragma Default_Storage_Pool (storage_pool_NAME | null); 1587 1588 1589This pragma is standard in Ada 2012, but is available in all earlier 1590versions of Ada as an implementation-defined pragma. 1591See Ada 2012 Reference Manual for details. 1592 1593.. _Pragma-Depends: 1594 1595Pragma Depends 1596============== 1597 1598Syntax: 1599 1600.. code-block:: ada 1601 1602 pragma Depends (DEPENDENCY_RELATION); 1603 1604 DEPENDENCY_RELATION ::= 1605 null 1606 | (DEPENDENCY_CLAUSE {, DEPENDENCY_CLAUSE}) 1607 1608 DEPENDENCY_CLAUSE ::= 1609 OUTPUT_LIST =>[+] INPUT_LIST 1610 | NULL_DEPENDENCY_CLAUSE 1611 1612 NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 1613 1614 OUTPUT_LIST ::= OUTPUT | (OUTPUT {, OUTPUT}) 1615 1616 INPUT_LIST ::= null | INPUT | (INPUT {, INPUT}) 1617 1618 OUTPUT ::= NAME | FUNCTION_RESULT 1619 INPUT ::= NAME 1620 1621 where FUNCTION_RESULT is a function Result attribute_reference 1622 1623For the semantics of this pragma, see the entry for aspect ``Depends`` in the 1624SPARK 2014 Reference Manual, section 6.1.5. 1625 1626Pragma Detect_Blocking 1627====================== 1628 1629Syntax: 1630 1631.. code-block:: ada 1632 1633 pragma Detect_Blocking; 1634 1635 1636This is a standard pragma in Ada 2005, that is available in all earlier 1637versions of Ada as an implementation-defined pragma. 1638 1639This is a configuration pragma that forces the detection of potentially 1640blocking operations within a protected operation, and to raise Program_Error 1641if that happens. 1642 1643Pragma Disable_Atomic_Synchronization 1644===================================== 1645 1646.. index:: Atomic Synchronization 1647 1648Syntax: 1649 1650:: 1651 1652 pragma Disable_Atomic_Synchronization [(Entity)]; 1653 1654 1655Ada requires that accesses (reads or writes) of an atomic variable be 1656regarded as synchronization points in the case of multiple tasks. 1657Particularly in the case of multi-processors this may require special 1658handling, e.g. the generation of memory barriers. This capability may 1659be turned off using this pragma in cases where it is known not to be 1660required. 1661 1662The placement and scope rules for this pragma are the same as those 1663for ``pragma Suppress``. In particular it can be used as a 1664configuration pragma, or in a declaration sequence where it applies 1665till the end of the scope. If an ``Entity`` argument is present, 1666the action applies only to that entity. 1667 1668Pragma Dispatching_Domain 1669========================= 1670 1671Syntax: 1672 1673 1674.. code-block:: ada 1675 1676 pragma Dispatching_Domain (EXPRESSION); 1677 1678 1679This pragma is standard in Ada 2012, but is available in all earlier 1680versions of Ada as an implementation-defined pragma. 1681See Ada 2012 Reference Manual for details. 1682 1683.. _Pragma-Effective_Reads: 1684 1685Pragma Effective_Reads 1686====================== 1687 1688Syntax: 1689 1690.. code-block:: ada 1691 1692 pragma Effective_Reads [ (boolean_EXPRESSION) ]; 1693 1694For the semantics of this pragma, see the entry for aspect ``Effective_Reads`` in 1695the SPARK 2014 Reference Manual, section 7.1.2. 1696 1697.. _Pragma-Effective_Writes: 1698 1699Pragma Effective_Writes 1700======================= 1701 1702Syntax: 1703 1704.. code-block:: ada 1705 1706 pragma Effective_Writes [ (boolean_EXPRESSION) ]; 1707 1708For the semantics of this pragma, see the entry for aspect ``Effective_Writes`` 1709in the SPARK 2014 Reference Manual, section 7.1.2. 1710 1711Pragma Elaboration_Checks 1712========================= 1713.. index:: Elaboration control 1714 1715 1716Syntax: 1717 1718 1719.. code-block:: ada 1720 1721 pragma Elaboration_Checks (Dynamic | Static); 1722 1723 1724This is a configuration pragma which specifies the elaboration model to be 1725used during compilation. For more information on the elaboration models of 1726GNAT, consult the chapter on elaboration order handling in the *GNAT User's 1727Guide*. 1728 1729The pragma may appear in the following contexts: 1730 1731* Configuration pragmas file 1732 1733* Prior to the context clauses of a compilation unit's initial declaration 1734 1735Any other placement of the pragma will result in a warning and the effects of 1736the offending pragma will be ignored. 1737 1738If the pragma argument is ``Dynamic``, then the dynamic elaboration model is in 1739effect. If the pragma argument is ``Static``, then the static elaboration model 1740is in effect. 1741 1742Pragma Eliminate 1743================ 1744.. index:: Elimination of unused subprograms 1745 1746 1747Syntax: 1748 1749 1750:: 1751 1752 pragma Eliminate ( 1753 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 1754 [ Entity => ] IDENTIFIER | 1755 SELECTED_COMPONENT | 1756 STRING_LITERAL 1757 [, Source_Location => SOURCE_TRACE ] ); 1758 1759 SOURCE_TRACE ::= STRING_LITERAL 1760 1761 1762This pragma indicates that the given entity is not used in the program to be 1763compiled and built, thus allowing the compiler to 1764eliminate the code or data associated with the named entity. Any reference to 1765an eliminated entity causes a compile-time or link-time error. 1766 1767The pragma has the following semantics, where ``U`` is the unit specified by 1768the ``Unit_Name`` argument and ``E`` is the entity specified by the ``Entity`` 1769argument: 1770 1771* ``E`` must be a subprogram that is explicitly declared either: 1772 1773 o Within ``U``, or 1774 1775 o Within a generic package that is instantiated in ``U``, or 1776 1777 o As an instance of generic subprogram instantiated in ``U``. 1778 1779 Otherwise the pragma is ignored. 1780 1781* If ``E`` is overloaded within ``U`` then, in the absence of a 1782 ``Source_Location`` argument, all overloadings are eliminated. 1783 1784* If ``E`` is overloaded within ``U`` and only some overloadings 1785 are to be eliminated, then each overloading to be eliminated 1786 must be specified in a corresponding pragma ``Eliminate`` 1787 with a ``Source_Location`` argument identifying the line where the 1788 declaration appears, as described below. 1789 1790* If ``E`` is declared as the result of a generic instantiation, then 1791 a ``Source_Location`` argument is needed, as described below 1792 1793Pragma ``Eliminate`` allows a program to be compiled in a system-independent 1794manner, so that unused entities are eliminated but without 1795needing to modify the source text. Normally the required set of 1796``Eliminate`` pragmas is constructed automatically using the ``gnatelim`` tool. 1797 1798Any source file change that removes, splits, or 1799adds lines may make the set of ``Eliminate`` pragmas invalid because their 1800``Source_Location`` argument values may get out of date. 1801 1802Pragma ``Eliminate`` may be used where the referenced entity is a dispatching 1803operation. In this case all the subprograms to which the given operation can 1804dispatch are considered to be unused (are never called as a result of a direct 1805or a dispatching call). 1806 1807The string literal given for the source location specifies the line number 1808of the declaration of the entity, using the following syntax for ``SOURCE_TRACE``: 1809 1810:: 1811 1812 SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 1813 1814 LBRACKET ::= '[' 1815 RBRACKET ::= ']' 1816 1817 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 1818 1819 LINE_NUMBER ::= DIGIT {DIGIT} 1820 1821 1822Spaces around the colon in a ``SOURCE_REFERENCE`` are optional. 1823 1824The source trace that is given as the ``Source_Location`` must obey the 1825following rules (or else the pragma is ignored), where ``U`` is 1826the unit ``U`` specified by the ``Unit_Name`` argument and ``E`` is the 1827subprogram specified by the ``Entity`` argument: 1828 1829* ``FILE_NAME`` is the short name (with no directory 1830 information) of the Ada source file for ``U``, using the required syntax 1831 for the underlying file system (e.g. case is significant if the underlying 1832 operating system is case sensitive). 1833 If ``U`` is a package and ``E`` is a subprogram declared in the package 1834 specification and its full declaration appears in the package body, 1835 then the relevant source file is the one for the package specification; 1836 analogously if ``U`` is a generic package. 1837 1838* If ``E`` is not declared in a generic instantiation (this includes 1839 generic subprogram instances), the source trace includes only one source 1840 line reference. ``LINE_NUMBER`` gives the line number of the occurrence 1841 of the declaration of ``E`` within the source file (as a decimal literal 1842 without an exponent or point). 1843 1844* If ``E`` is declared by a generic instantiation, its source trace 1845 (from left to right) starts with the source location of the 1846 declaration of ``E`` in the generic unit and ends with the source 1847 location of the instantiation, given in square brackets. This approach is 1848 applied recursively with nested instantiations: the rightmost (nested 1849 most deeply in square brackets) element of the source trace is the location 1850 of the outermost instantiation, and the leftmost element (that is, outside 1851 of any square brackets) is the location of the declaration of ``E`` in 1852 the generic unit. 1853 1854Examples: 1855 1856 .. code-block:: ada 1857 1858 pragma Eliminate (Pkg0, Proc); 1859 -- Eliminate (all overloadings of) Proc in Pkg0 1860 1861 pragma Eliminate (Pkg1, Proc, 1862 Source_Location => "pkg1.ads:8"); 1863 -- Eliminate overloading of Proc at line 8 in pkg1.ads 1864 1865 -- Assume the following file contents: 1866 -- gen_pkg.ads 1867 -- 1: generic 1868 -- 2: type T is private; 1869 -- 3: package Gen_Pkg is 1870 -- 4: procedure Proc(N : T); 1871 -- ... ... 1872 -- ... end Gen_Pkg; 1873 -- 1874 -- q.adb 1875 -- 1: with Gen_Pkg; 1876 -- 2: procedure Q is 1877 -- 3: package Inst_Pkg is new Gen_Pkg(Integer); 1878 -- ... -- No calls on Inst_Pkg.Proc 1879 -- ... end Q; 1880 1881 -- The following pragma eliminates Inst_Pkg.Proc from Q 1882 pragma Eliminate (Q, Proc, 1883 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 1884 1885 1886 1887Pragma Enable_Atomic_Synchronization 1888==================================== 1889.. index:: Atomic Synchronization 1890 1891 1892Syntax: 1893 1894 1895:: 1896 1897 pragma Enable_Atomic_Synchronization [(Entity)]; 1898 1899 1900Ada requires that accesses (reads or writes) of an atomic variable be 1901regarded as synchronization points in the case of multiple tasks. 1902Particularly in the case of multi-processors this may require special 1903handling, e.g. the generation of memory barriers. This synchronization 1904is performed by default, but can be turned off using 1905``pragma Disable_Atomic_Synchronization``. The 1906``Enable_Atomic_Synchronization`` pragma can be used to turn 1907it back on. 1908 1909The placement and scope rules for this pragma are the same as those 1910for ``pragma Unsuppress``. In particular it can be used as a 1911configuration pragma, or in a declaration sequence where it applies 1912till the end of the scope. If an ``Entity`` argument is present, 1913the action applies only to that entity. 1914 1915Pragma Export_Function 1916====================== 1917.. index:: Argument passing mechanisms 1918 1919 1920Syntax: 1921 1922 1923:: 1924 1925 pragma Export_Function ( 1926 [Internal =>] LOCAL_NAME 1927 [, [External =>] EXTERNAL_SYMBOL] 1928 [, [Parameter_Types =>] PARAMETER_TYPES] 1929 [, [Result_Type =>] result_SUBTYPE_MARK] 1930 [, [Mechanism =>] MECHANISM] 1931 [, [Result_Mechanism =>] MECHANISM_NAME]); 1932 1933 EXTERNAL_SYMBOL ::= 1934 IDENTIFIER 1935 | static_string_EXPRESSION 1936 | "" 1937 1938 PARAMETER_TYPES ::= 1939 null 1940 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 1941 1942 TYPE_DESIGNATOR ::= 1943 subtype_NAME 1944 | subtype_Name ' Access 1945 1946 MECHANISM ::= 1947 MECHANISM_NAME 1948 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 1949 1950 MECHANISM_ASSOCIATION ::= 1951 [formal_parameter_NAME =>] MECHANISM_NAME 1952 1953 MECHANISM_NAME ::= Value | Reference 1954 1955 1956Use this pragma to make a function externally callable and optionally 1957provide information on mechanisms to be used for passing parameter and 1958result values. We recommend, for the purposes of improving portability, 1959this pragma always be used in conjunction with a separate pragma 1960``Export``, which must precede the pragma ``Export_Function``. 1961GNAT does not require a separate pragma ``Export``, but if none is 1962present, ``Convention Ada`` is assumed, which is usually 1963not what is wanted, so it is usually appropriate to use this 1964pragma in conjunction with a ``Export`` or ``Convention`` 1965pragma that specifies the desired foreign convention. 1966Pragma ``Export_Function`` 1967(and ``Export``, if present) must appear in the same declarative 1968region as the function to which they apply. 1969 1970The ``internal_name`` must uniquely designate the function to which the 1971pragma applies. If more than one function name exists of this name in 1972the declarative part you must use the ``Parameter_Types`` and 1973``Result_Type`` parameters to achieve the required 1974unique designation. The `subtype_mark`\ s in these parameters must 1975exactly match the subtypes in the corresponding function specification, 1976using positional notation to match parameters with subtype marks. 1977The form with an ``'Access`` attribute can be used to match an 1978anonymous access parameter. 1979 1980.. index:: Suppressing external name 1981 1982Special treatment is given if the EXTERNAL is an explicit null 1983string or a static string expressions that evaluates to the null 1984string. In this case, no external name is generated. This form 1985still allows the specification of parameter mechanisms. 1986 1987Pragma Export_Object 1988==================== 1989 1990Syntax: 1991 1992 1993:: 1994 1995 pragma Export_Object 1996 [Internal =>] LOCAL_NAME 1997 [, [External =>] EXTERNAL_SYMBOL] 1998 [, [Size =>] EXTERNAL_SYMBOL] 1999 2000 EXTERNAL_SYMBOL ::= 2001 IDENTIFIER 2002 | static_string_EXPRESSION 2003 2004 2005This pragma designates an object as exported, and apart from the 2006extended rules for external symbols, is identical in effect to the use of 2007the normal ``Export`` pragma applied to an object. You may use a 2008separate Export pragma (and you probably should from the point of view 2009of portability), but it is not required. ``Size`` is syntax checked, 2010but otherwise ignored by GNAT. 2011 2012Pragma Export_Procedure 2013======================= 2014 2015Syntax: 2016 2017 2018:: 2019 2020 pragma Export_Procedure ( 2021 [Internal =>] LOCAL_NAME 2022 [, [External =>] EXTERNAL_SYMBOL] 2023 [, [Parameter_Types =>] PARAMETER_TYPES] 2024 [, [Mechanism =>] MECHANISM]); 2025 2026 EXTERNAL_SYMBOL ::= 2027 IDENTIFIER 2028 | static_string_EXPRESSION 2029 | "" 2030 2031 PARAMETER_TYPES ::= 2032 null 2033 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 2034 2035 TYPE_DESIGNATOR ::= 2036 subtype_NAME 2037 | subtype_Name ' Access 2038 2039 MECHANISM ::= 2040 MECHANISM_NAME 2041 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 2042 2043 MECHANISM_ASSOCIATION ::= 2044 [formal_parameter_NAME =>] MECHANISM_NAME 2045 2046 MECHANISM_NAME ::= Value | Reference 2047 2048 2049This pragma is identical to ``Export_Function`` except that it 2050applies to a procedure rather than a function and the parameters 2051``Result_Type`` and ``Result_Mechanism`` are not permitted. 2052GNAT does not require a separate pragma ``Export``, but if none is 2053present, ``Convention Ada`` is assumed, which is usually 2054not what is wanted, so it is usually appropriate to use this 2055pragma in conjunction with a ``Export`` or ``Convention`` 2056pragma that specifies the desired foreign convention. 2057 2058.. index:: Suppressing external name 2059 2060Special treatment is given if the EXTERNAL is an explicit null 2061string or a static string expressions that evaluates to the null 2062string. In this case, no external name is generated. This form 2063still allows the specification of parameter mechanisms. 2064 2065Pragma Export_Value 2066=================== 2067 2068Syntax: 2069 2070 2071:: 2072 2073 pragma Export_Value ( 2074 [Value =>] static_integer_EXPRESSION, 2075 [Link_Name =>] static_string_EXPRESSION); 2076 2077 2078This pragma serves to export a static integer value for external use. 2079The first argument specifies the value to be exported. The Link_Name 2080argument specifies the symbolic name to be associated with the integer 2081value. This pragma is useful for defining a named static value in Ada 2082that can be referenced in assembly language units to be linked with 2083the application. This pragma is currently supported only for the 2084AAMP target and is ignored for other targets. 2085 2086Pragma Export_Valued_Procedure 2087============================== 2088 2089Syntax: 2090 2091 2092:: 2093 2094 pragma Export_Valued_Procedure ( 2095 [Internal =>] LOCAL_NAME 2096 [, [External =>] EXTERNAL_SYMBOL] 2097 [, [Parameter_Types =>] PARAMETER_TYPES] 2098 [, [Mechanism =>] MECHANISM]); 2099 2100 EXTERNAL_SYMBOL ::= 2101 IDENTIFIER 2102 | static_string_EXPRESSION 2103 | "" 2104 2105 PARAMETER_TYPES ::= 2106 null 2107 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 2108 2109 TYPE_DESIGNATOR ::= 2110 subtype_NAME 2111 | subtype_Name ' Access 2112 2113 MECHANISM ::= 2114 MECHANISM_NAME 2115 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 2116 2117 MECHANISM_ASSOCIATION ::= 2118 [formal_parameter_NAME =>] MECHANISM_NAME 2119 2120 MECHANISM_NAME ::= Value | Reference 2121 2122 2123This pragma is identical to ``Export_Procedure`` except that the 2124first parameter of ``LOCAL_NAME``, which must be present, must be of 2125mode ``out``, and externally the subprogram is treated as a function 2126with this parameter as the result of the function. GNAT provides for 2127this capability to allow the use of ``out`` and ``in out`` 2128parameters in interfacing to external functions (which are not permitted 2129in Ada functions). 2130GNAT does not require a separate pragma ``Export``, but if none is 2131present, ``Convention Ada`` is assumed, which is almost certainly 2132not what is wanted since the whole point of this pragma is to interface 2133with foreign language functions, so it is usually appropriate to use this 2134pragma in conjunction with a ``Export`` or ``Convention`` 2135pragma that specifies the desired foreign convention. 2136 2137.. index:: Suppressing external name 2138 2139Special treatment is given if the EXTERNAL is an explicit null 2140string or a static string expressions that evaluates to the null 2141string. In this case, no external name is generated. This form 2142still allows the specification of parameter mechanisms. 2143 2144Pragma Extend_System 2145==================== 2146.. index:: System, extending 2147 2148.. index:: DEC Ada 83 2149 2150 2151Syntax: 2152 2153 2154:: 2155 2156 pragma Extend_System ([Name =>] IDENTIFIER); 2157 2158 2159This pragma is used to provide backwards compatibility with other 2160implementations that extend the facilities of package ``System``. In 2161GNAT, ``System`` contains only the definitions that are present in 2162the Ada RM. However, other implementations, notably the DEC Ada 83 2163implementation, provide many extensions to package ``System``. 2164 2165For each such implementation accommodated by this pragma, GNAT provides a 2166package :samp:`Aux_{xxx}`, e.g., ``Aux_DEC`` for the DEC Ada 83 2167implementation, which provides the required additional definitions. You 2168can use this package in two ways. You can ``with`` it in the normal 2169way and access entities either by selection or using a ``use`` 2170clause. In this case no special processing is required. 2171 2172However, if existing code contains references such as 2173:samp:`System.{xxx}` where *xxx* is an entity in the extended 2174definitions provided in package ``System``, you may use this pragma 2175to extend visibility in ``System`` in a non-standard way that 2176provides greater compatibility with the existing code. Pragma 2177``Extend_System`` is a configuration pragma whose single argument is 2178the name of the package containing the extended definition 2179(e.g., ``Aux_DEC`` for the DEC Ada case). A unit compiled under 2180control of this pragma will be processed using special visibility 2181processing that looks in package :samp:`System.Aux_{xxx}` where 2182:samp:`Aux_{xxx}` is the pragma argument for any entity referenced in 2183package ``System``, but not found in package ``System``. 2184 2185You can use this pragma either to access a predefined ``System`` 2186extension supplied with the compiler, for example ``Aux_DEC`` or 2187you can construct your own extension unit following the above 2188definition. Note that such a package is a child of ``System`` 2189and thus is considered part of the implementation. 2190To compile it you will have to use the *-gnatg* switch 2191for compiling System units, as explained in the 2192GNAT User's Guide. 2193 2194Pragma Extensions_Allowed 2195========================= 2196.. index:: Ada Extensions 2197 2198.. index:: GNAT Extensions 2199 2200 2201Syntax: 2202 2203.. code-block:: ada 2204 2205 pragma Extensions_Allowed (On | Off); 2206 2207 2208This configuration pragma enables or disables the implementation 2209extension mode (the use of Off as a parameter cancels the effect 2210of the *-gnatX* command switch). 2211 2212In extension mode, the latest version of the Ada language is 2213implemented (currently Ada 202x), and in addition a small number 2214of GNAT specific extensions are recognized as follows: 2215 2216* Constrained attribute for generic objects 2217 2218 The ``Constrained`` attribute is permitted for objects of 2219 generic types. The result indicates if the corresponding actual 2220 is constrained. 2221 2222* ``Static`` aspect on intrinsic functions 2223 2224 The Ada 202x ``Static`` aspect can be specified on Intrinsic imported 2225 functions and the compiler will evaluate some of these intrinsic statically, 2226 in particular the ``Shift_Left`` and ``Shift_Right`` intrinsics. 2227 2228* ``'Reduce`` attribute 2229 2230 This attribute part of the Ada 202x language definition is provided for 2231 now under -gnatX to confirm and potentially refine its usage and syntax. 2232 2233* ``[]`` aggregates 2234 2235 This new aggregate syntax for arrays and containers is provided under -gnatX 2236 to experiment and confirm this new language syntax. 2237 2238 2239.. _Pragma-Extensions_Visible: 2240 2241Pragma Extensions_Visible 2242========================= 2243 2244Syntax: 2245 2246.. code-block:: ada 2247 2248 pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 2249 2250For the semantics of this pragma, see the entry for aspect ``Extensions_Visible`` 2251in the SPARK 2014 Reference Manual, section 6.1.7. 2252 2253Pragma External 2254=============== 2255 2256Syntax: 2257 2258 2259:: 2260 2261 pragma External ( 2262 [ Convention =>] convention_IDENTIFIER, 2263 [ Entity =>] LOCAL_NAME 2264 [, [External_Name =>] static_string_EXPRESSION ] 2265 [, [Link_Name =>] static_string_EXPRESSION ]); 2266 2267 2268This pragma is identical in syntax and semantics to pragma 2269``Export`` as defined in the Ada Reference Manual. It is 2270provided for compatibility with some Ada 83 compilers that 2271used this pragma for exactly the same purposes as pragma 2272``Export`` before the latter was standardized. 2273 2274Pragma External_Name_Casing 2275=========================== 2276.. index:: Dec Ada 83 casing compatibility 2277 2278.. index:: External Names, casing 2279 2280.. index:: Casing of External names 2281 2282 2283Syntax: 2284 2285 2286:: 2287 2288 pragma External_Name_Casing ( 2289 Uppercase | Lowercase 2290 [, Uppercase | Lowercase | As_Is]); 2291 2292 2293This pragma provides control over the casing of external names associated 2294with Import and Export pragmas. There are two cases to consider: 2295 2296 2297 2298* Implicit external names 2299 2300 Implicit external names are derived from identifiers. The most common case 2301 arises when a standard Ada Import or Export pragma is used with only two 2302 arguments, as in: 2303 2304 .. code-block:: ada 2305 2306 pragma Import (C, C_Routine); 2307 2308 Since Ada is a case-insensitive language, the spelling of the identifier in 2309 the Ada source program does not provide any information on the desired 2310 casing of the external name, and so a convention is needed. In GNAT the 2311 default treatment is that such names are converted to all lower case 2312 letters. This corresponds to the normal C style in many environments. 2313 The first argument of pragma ``External_Name_Casing`` can be used to 2314 control this treatment. If ``Uppercase`` is specified, then the name 2315 will be forced to all uppercase letters. If ``Lowercase`` is specified, 2316 then the normal default of all lower case letters will be used. 2317 2318 This same implicit treatment is also used in the case of extended DEC Ada 83 2319 compatible Import and Export pragmas where an external name is explicitly 2320 specified using an identifier rather than a string. 2321 2322 2323* Explicit external names 2324 2325 Explicit external names are given as string literals. The most common case 2326 arises when a standard Ada Import or Export pragma is used with three 2327 arguments, as in: 2328 2329 .. code-block:: ada 2330 2331 pragma Import (C, C_Routine, "C_routine"); 2332 2333 In this case, the string literal normally provides the exact casing required 2334 for the external name. The second argument of pragma 2335 ``External_Name_Casing`` may be used to modify this behavior. 2336 If ``Uppercase`` is specified, then the name 2337 will be forced to all uppercase letters. If ``Lowercase`` is specified, 2338 then the name will be forced to all lowercase letters. A specification of 2339 ``As_Is`` provides the normal default behavior in which the casing is 2340 taken from the string provided. 2341 2342This pragma may appear anywhere that a pragma is valid. In particular, it 2343can be used as a configuration pragma in the :file:`gnat.adc` file, in which 2344case it applies to all subsequent compilations, or it can be used as a program 2345unit pragma, in which case it only applies to the current unit, or it can 2346be used more locally to control individual Import/Export pragmas. 2347 2348It was primarily intended for use with OpenVMS systems, where many 2349compilers convert all symbols to upper case by default. For interfacing to 2350such compilers (e.g., the DEC C compiler), it may be convenient to use 2351the pragma: 2352 2353.. code-block:: ada 2354 2355 pragma External_Name_Casing (Uppercase, Uppercase); 2356 2357 2358to enforce the upper casing of all external symbols. 2359 2360Pragma Fast_Math 2361================ 2362 2363Syntax: 2364 2365 2366.. code-block:: ada 2367 2368 pragma Fast_Math; 2369 2370 2371This is a configuration pragma which activates a mode in which speed is 2372considered more important for floating-point operations than absolutely 2373accurate adherence to the requirements of the standard. Currently the 2374following operations are affected: 2375 2376 2377 2378*Complex Multiplication* 2379 The normal simple formula for complex multiplication can result in intermediate 2380 overflows for numbers near the end of the range. The Ada standard requires that 2381 this situation be detected and corrected by scaling, but in Fast_Math mode such 2382 cases will simply result in overflow. Note that to take advantage of this you 2383 must instantiate your own version of ``Ada.Numerics.Generic_Complex_Types`` 2384 under control of the pragma, rather than use the preinstantiated versions. 2385 2386.. _Pragma-Favor_Top_Level: 2387 2388Pragma Favor_Top_Level 2389====================== 2390 2391Syntax: 2392 2393 2394.. code-block:: ada 2395 2396 pragma Favor_Top_Level (type_NAME); 2397 2398 2399The argument of pragma ``Favor_Top_Level`` must be a named access-to-subprogram 2400type. This pragma is an efficiency hint to the compiler, regarding the use of 2401``'Access`` or ``'Unrestricted_Access`` on nested (non-library-level) subprograms. 2402The pragma means that nested subprograms are not used with this type, or are 2403rare, so that the generated code should be efficient in the top-level case. 2404When this pragma is used, dynamically generated trampolines may be used on some 2405targets for nested subprograms. See restriction ``No_Implicit_Dynamic_Code``. 2406 2407Pragma Finalize_Storage_Only 2408============================ 2409 2410Syntax: 2411 2412 2413.. code-block:: ada 2414 2415 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 2416 2417 2418The argument of pragma ``Finalize_Storage_Only`` must denote a local type which 2419is derived from ``Ada.Finalization.Controlled`` or ``Limited_Controlled``. The 2420pragma suppresses the call to ``Finalize`` for declared library-level objects 2421of the argument type. This is mostly useful for types where finalization is 2422only used to deal with storage reclamation since in most environments it is 2423not necessary to reclaim memory just before terminating execution, hence the 2424name. Note that this pragma does not suppress Finalize calls for library-level 2425heap-allocated objects (see pragma ``No_Heap_Finalization``). 2426 2427Pragma Float_Representation 2428=========================== 2429 2430Syntax:: 2431 2432 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 2433 2434 FLOAT_REP ::= VAX_Float | IEEE_Float 2435 2436 2437In the one argument form, this pragma is a configuration pragma which 2438allows control over the internal representation chosen for the predefined 2439floating point types declared in the packages ``Standard`` and 2440``System``. This pragma is only provided for compatibility and has no effect. 2441 2442The two argument form specifies the representation to be used for 2443the specified floating-point type. The argument must 2444be ``IEEE_Float`` to specify the use of IEEE format, as follows: 2445 2446* 2447 For a digits value of 6, 32-bit IEEE short format will be used. 2448* 2449 For a digits value of 15, 64-bit IEEE long format will be used. 2450* 2451 No other value of digits is permitted. 2452 2453.. _Pragma-Ghost: 2454 2455Pragma Ghost 2456============ 2457 2458Syntax: 2459 2460.. code-block:: ada 2461 2462 pragma Ghost [ (boolean_EXPRESSION) ]; 2463 2464For the semantics of this pragma, see the entry for aspect ``Ghost`` in the SPARK 24652014 Reference Manual, section 6.9. 2466 2467.. _Pragma-Global: 2468 2469Pragma Global 2470============= 2471 2472Syntax: 2473 2474.. code-block:: ada 2475 2476 pragma Global (GLOBAL_SPECIFICATION); 2477 2478 GLOBAL_SPECIFICATION ::= 2479 null 2480 | (GLOBAL_LIST) 2481 | (MODED_GLOBAL_LIST {, MODED_GLOBAL_LIST}) 2482 2483 MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 2484 2485 MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 2486 GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM}) 2487 GLOBAL_ITEM ::= NAME 2488 2489For the semantics of this pragma, see the entry for aspect ``Global`` in the 2490SPARK 2014 Reference Manual, section 6.1.4. 2491 2492Pragma Ident 2493============ 2494 2495Syntax: 2496 2497 2498.. code-block:: ada 2499 2500 pragma Ident (static_string_EXPRESSION); 2501 2502 2503This pragma is identical in effect to pragma ``Comment``. It is provided 2504for compatibility with other Ada compilers providing this pragma. 2505 2506Pragma Ignore_Pragma 2507==================== 2508 2509Syntax: 2510 2511 2512.. code-block:: ada 2513 2514 pragma Ignore_Pragma (pragma_IDENTIFIER); 2515 2516This is a configuration pragma 2517that takes a single argument that is a simple identifier. Any subsequent 2518use of a pragma whose pragma identifier matches this argument will be 2519silently ignored. This may be useful when legacy code or code intended 2520for compilation with some other compiler contains pragmas that match the 2521name, but not the exact implementation, of a GNAT pragma. The use of this 2522pragma allows such pragmas to be ignored, which may be useful in CodePeer 2523mode, or during porting of legacy code. 2524 2525Pragma Implementation_Defined 2526============================= 2527 2528Syntax: 2529 2530 2531.. code-block:: ada 2532 2533 pragma Implementation_Defined (local_NAME); 2534 2535 2536This pragma marks a previously declared entity as implementation-defined. 2537For an overloaded entity, applies to the most recent homonym. 2538 2539 2540.. code-block:: ada 2541 2542 pragma Implementation_Defined; 2543 2544 2545The form with no arguments appears anywhere within a scope, most 2546typically a package spec, and indicates that all entities that are 2547defined within the package spec are Implementation_Defined. 2548 2549This pragma is used within the GNAT runtime library to identify 2550implementation-defined entities introduced in language-defined units, 2551for the purpose of implementing the No_Implementation_Identifiers 2552restriction. 2553 2554Pragma Implemented 2555================== 2556 2557Syntax: 2558 2559 2560:: 2561 2562 pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 2563 2564 implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 2565 2566 2567This is an Ada 2012 representation pragma which applies to protected, task 2568and synchronized interface primitives. The use of pragma Implemented provides 2569a way to impose a static requirement on the overriding operation by adhering 2570to one of the three implementation kinds: entry, protected procedure or any of 2571the above. This pragma is available in all earlier versions of Ada as an 2572implementation-defined pragma. 2573 2574 2575.. code-block:: ada 2576 2577 type Synch_Iface is synchronized interface; 2578 procedure Prim_Op (Obj : in out Iface) is abstract; 2579 pragma Implemented (Prim_Op, By_Protected_Procedure); 2580 2581 protected type Prot_1 is new Synch_Iface with 2582 procedure Prim_Op; -- Legal 2583 end Prot_1; 2584 2585 protected type Prot_2 is new Synch_Iface with 2586 entry Prim_Op; -- Illegal 2587 end Prot_2; 2588 2589 task type Task_Typ is new Synch_Iface with 2590 entry Prim_Op; -- Illegal 2591 end Task_Typ; 2592 2593 2594When applied to the procedure_or_entry_NAME of a requeue statement, pragma 2595Implemented determines the runtime behavior of the requeue. Implementation kind 2596By_Entry guarantees that the action of requeueing will proceed from an entry to 2597another entry. Implementation kind By_Protected_Procedure transforms the 2598requeue into a dispatching call, thus eliminating the chance of blocking. Kind 2599By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 2600the target's overriding subprogram kind. 2601 2602Pragma Implicit_Packing 2603======================= 2604.. index:: Rational Profile 2605 2606Syntax: 2607 2608 2609.. code-block:: ada 2610 2611 pragma Implicit_Packing; 2612 2613 2614This is a configuration pragma that requests implicit packing for packed 2615arrays for which a size clause is given but no explicit pragma Pack or 2616specification of Component_Size is present. It also applies to records 2617where no record representation clause is present. Consider this example: 2618 2619 2620.. code-block:: ada 2621 2622 type R is array (0 .. 7) of Boolean; 2623 for R'Size use 8; 2624 2625 2626In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 2627does not change the layout of a composite object. So the Size clause in the 2628above example is normally rejected, since the default layout of the array uses 26298-bit components, and thus the array requires a minimum of 64 bits. 2630 2631If this declaration is compiled in a region of code covered by an occurrence 2632of the configuration pragma Implicit_Packing, then the Size clause in this 2633and similar examples will cause implicit packing and thus be accepted. For 2634this implicit packing to occur, the type in question must be an array of small 2635components whose size is known at compile time, and the Size clause must 2636specify the exact size that corresponds to the number of elements in the array 2637multiplied by the size in bits of the component type (both single and 2638multi-dimensioned arrays can be controlled with this pragma). 2639 2640.. index:: Array packing 2641 2642Similarly, the following example shows the use in the record case 2643 2644 2645.. code-block:: ada 2646 2647 type r is record 2648 a, b, c, d, e, f, g, h : boolean; 2649 chr : character; 2650 end record; 2651 for r'size use 16; 2652 2653 2654Without a pragma Pack, each Boolean field requires 8 bits, so the 2655minimum size is 72 bits, but with a pragma Pack, 16 bits would be 2656sufficient. The use of pragma Implicit_Packing allows this record 2657declaration to compile without an explicit pragma Pack. 2658 2659Pragma Import_Function 2660====================== 2661 2662Syntax: 2663 2664 2665:: 2666 2667 pragma Import_Function ( 2668 [Internal =>] LOCAL_NAME, 2669 [, [External =>] EXTERNAL_SYMBOL] 2670 [, [Parameter_Types =>] PARAMETER_TYPES] 2671 [, [Result_Type =>] SUBTYPE_MARK] 2672 [, [Mechanism =>] MECHANISM] 2673 [, [Result_Mechanism =>] MECHANISM_NAME]); 2674 2675 EXTERNAL_SYMBOL ::= 2676 IDENTIFIER 2677 | static_string_EXPRESSION 2678 2679 PARAMETER_TYPES ::= 2680 null 2681 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 2682 2683 TYPE_DESIGNATOR ::= 2684 subtype_NAME 2685 | subtype_Name ' Access 2686 2687 MECHANISM ::= 2688 MECHANISM_NAME 2689 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 2690 2691 MECHANISM_ASSOCIATION ::= 2692 [formal_parameter_NAME =>] MECHANISM_NAME 2693 2694 MECHANISM_NAME ::= 2695 Value 2696 | Reference 2697 2698 2699This pragma is used in conjunction with a pragma ``Import`` to 2700specify additional information for an imported function. The pragma 2701``Import`` (or equivalent pragma ``Interface``) must precede the 2702``Import_Function`` pragma and both must appear in the same 2703declarative part as the function specification. 2704 2705The ``Internal`` argument must uniquely designate 2706the function to which the 2707pragma applies. If more than one function name exists of this name in 2708the declarative part you must use the ``Parameter_Types`` and 2709``Result_Type`` parameters to achieve the required unique 2710designation. Subtype marks in these parameters must exactly match the 2711subtypes in the corresponding function specification, using positional 2712notation to match parameters with subtype marks. 2713The form with an ``'Access`` attribute can be used to match an 2714anonymous access parameter. 2715 2716You may optionally use the ``Mechanism`` and ``Result_Mechanism`` 2717parameters to specify passing mechanisms for the 2718parameters and result. If you specify a single mechanism name, it 2719applies to all parameters. Otherwise you may specify a mechanism on a 2720parameter by parameter basis using either positional or named 2721notation. If the mechanism is not specified, the default mechanism 2722is used. 2723 2724Pragma Import_Object 2725==================== 2726 2727Syntax: 2728 2729 2730:: 2731 2732 pragma Import_Object 2733 [Internal =>] LOCAL_NAME 2734 [, [External =>] EXTERNAL_SYMBOL] 2735 [, [Size =>] EXTERNAL_SYMBOL]); 2736 2737 EXTERNAL_SYMBOL ::= 2738 IDENTIFIER 2739 | static_string_EXPRESSION 2740 2741 2742This pragma designates an object as imported, and apart from the 2743extended rules for external symbols, is identical in effect to the use of 2744the normal ``Import`` pragma applied to an object. Unlike the 2745subprogram case, you need not use a separate ``Import`` pragma, 2746although you may do so (and probably should do so from a portability 2747point of view). ``size`` is syntax checked, but otherwise ignored by 2748GNAT. 2749 2750Pragma Import_Procedure 2751======================= 2752 2753Syntax: 2754 2755 2756:: 2757 2758 pragma Import_Procedure ( 2759 [Internal =>] LOCAL_NAME 2760 [, [External =>] EXTERNAL_SYMBOL] 2761 [, [Parameter_Types =>] PARAMETER_TYPES] 2762 [, [Mechanism =>] MECHANISM]); 2763 2764 EXTERNAL_SYMBOL ::= 2765 IDENTIFIER 2766 | static_string_EXPRESSION 2767 2768 PARAMETER_TYPES ::= 2769 null 2770 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 2771 2772 TYPE_DESIGNATOR ::= 2773 subtype_NAME 2774 | subtype_Name ' Access 2775 2776 MECHANISM ::= 2777 MECHANISM_NAME 2778 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 2779 2780 MECHANISM_ASSOCIATION ::= 2781 [formal_parameter_NAME =>] MECHANISM_NAME 2782 2783 MECHANISM_NAME ::= Value | Reference 2784 2785 2786This pragma is identical to ``Import_Function`` except that it 2787applies to a procedure rather than a function and the parameters 2788``Result_Type`` and ``Result_Mechanism`` are not permitted. 2789 2790Pragma Import_Valued_Procedure 2791============================== 2792 2793Syntax: 2794 2795 2796:: 2797 2798 pragma Import_Valued_Procedure ( 2799 [Internal =>] LOCAL_NAME 2800 [, [External =>] EXTERNAL_SYMBOL] 2801 [, [Parameter_Types =>] PARAMETER_TYPES] 2802 [, [Mechanism =>] MECHANISM]); 2803 2804 EXTERNAL_SYMBOL ::= 2805 IDENTIFIER 2806 | static_string_EXPRESSION 2807 2808 PARAMETER_TYPES ::= 2809 null 2810 | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} 2811 2812 TYPE_DESIGNATOR ::= 2813 subtype_NAME 2814 | subtype_Name ' Access 2815 2816 MECHANISM ::= 2817 MECHANISM_NAME 2818 | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) 2819 2820 MECHANISM_ASSOCIATION ::= 2821 [formal_parameter_NAME =>] MECHANISM_NAME 2822 2823 MECHANISM_NAME ::= Value | Reference 2824 2825 2826This pragma is identical to ``Import_Procedure`` except that the 2827first parameter of ``LOCAL_NAME``, which must be present, must be of 2828mode ``out``, and externally the subprogram is treated as a function 2829with this parameter as the result of the function. The purpose of this 2830capability is to allow the use of ``out`` and ``in out`` 2831parameters in interfacing to external functions (which are not permitted 2832in Ada functions). You may optionally use the ``Mechanism`` 2833parameters to specify passing mechanisms for the parameters. 2834If you specify a single mechanism name, it applies to all parameters. 2835Otherwise you may specify a mechanism on a parameter by parameter 2836basis using either positional or named notation. If the mechanism is not 2837specified, the default mechanism is used. 2838 2839Note that it is important to use this pragma in conjunction with a separate 2840pragma Import that specifies the desired convention, since otherwise the 2841default convention is Ada, which is almost certainly not what is required. 2842 2843Pragma Independent 2844================== 2845 2846Syntax: 2847 2848 2849.. code-block:: ada 2850 2851 pragma Independent (Local_NAME); 2852 2853 2854This pragma is standard in Ada 2012 mode (which also provides an aspect 2855of the same name). It is also available as an implementation-defined 2856pragma in all earlier versions. It specifies that the 2857designated object or all objects of the designated type must be 2858independently addressable. This means that separate tasks can safely 2859manipulate such objects. For example, if two components of a record are 2860independent, then two separate tasks may access these two components. 2861This may place 2862constraints on the representation of the object (for instance prohibiting 2863tight packing). 2864 2865Pragma Independent_Components 2866============================= 2867 2868Syntax: 2869 2870 2871.. code-block:: ada 2872 2873 pragma Independent_Components (Local_NAME); 2874 2875 2876This pragma is standard in Ada 2012 mode (which also provides an aspect 2877of the same name). It is also available as an implementation-defined 2878pragma in all earlier versions. It specifies that the components of the 2879designated object, or the components of each object of the designated 2880type, must be 2881independently addressable. This means that separate tasks can safely 2882manipulate separate components in the composite object. This may place 2883constraints on the representation of the object (for instance prohibiting 2884tight packing). 2885 2886.. _Pragma-Initial_Condition: 2887 2888Pragma Initial_Condition 2889======================== 2890 2891Syntax: 2892 2893.. code-block:: ada 2894 2895 pragma Initial_Condition (boolean_EXPRESSION); 2896 2897For the semantics of this pragma, see the entry for aspect ``Initial_Condition`` 2898in the SPARK 2014 Reference Manual, section 7.1.6. 2899 2900Pragma Initialize_Scalars 2901========================= 2902.. index:: debugging with Initialize_Scalars 2903 2904Syntax: 2905 2906 2907.. code-block:: ada 2908 2909 pragma Initialize_Scalars 2910 [ ( TYPE_VALUE_PAIR {, TYPE_VALUE_PAIR} ) ]; 2911 2912 TYPE_VALUE_PAIR ::= 2913 SCALAR_TYPE => static_EXPRESSION 2914 2915 SCALAR_TYPE := 2916 Short_Float 2917 | Float 2918 | Long_Float 2919 | Long_Long_Flat 2920 | Signed_8 2921 | Signed_16 2922 | Signed_32 2923 | Signed_64 2924 | Unsigned_8 2925 | Unsigned_16 2926 | Unsigned_32 2927 | Unsigned_64 2928 2929 2930This pragma is similar to ``Normalize_Scalars`` conceptually but has two 2931important differences. 2932 2933First, there is no requirement for the pragma to be used uniformly in all units 2934of a partition. In particular, it is fine to use this just for some or all of 2935the application units of a partition, without needing to recompile the run-time 2936library. In the case where some units are compiled with the pragma, and some 2937without, then a declaration of a variable where the type is defined in package 2938Standard or is locally declared will always be subject to initialization, as 2939will any declaration of a scalar variable. For composite variables, whether the 2940variable is initialized may also depend on whether the package in which the 2941type of the variable is declared is compiled with the pragma. 2942 2943The other important difference is that the programmer can control the value 2944used for initializing scalar objects. This effect can be achieved in several 2945different ways: 2946 2947* At compile time, the programmer can specify the invalid value for a 2948 particular family of scalar types using the optional arguments of the pragma. 2949 2950 The compile-time approach is intended to optimize the generated code for the 2951 pragma, by possibly using fast operations such as ``memset``. Note that such 2952 optimizations require using values where the bytes all have the same binary 2953 representation. 2954 2955* At bind time, the programmer has several options: 2956 2957 * Initialization with invalid values (similar to Normalize_Scalars, though 2958 for Initialize_Scalars it is not always possible to determine the invalid 2959 values in complex cases like signed component fields with nonstandard 2960 sizes). 2961 2962 * Initialization with high values. 2963 2964 * Initialization with low values. 2965 2966 * Initialization with a specific bit pattern. 2967 2968 See the GNAT User's Guide for binder options for specifying these cases. 2969 2970 The bind-time approach is intended to provide fast turnaround for testing 2971 with different values, without having to recompile the program. 2972 2973* At execution time, the programmer can specify the invalid values using an 2974 environment variable. See the GNAT User's Guide for details. 2975 2976 The execution-time approach is intended to provide fast turnaround for 2977 testing with different values, without having to recompile and rebind the 2978 program. 2979 2980Note that pragma ``Initialize_Scalars`` is particularly useful in conjunction 2981with the enhanced validity checking that is now provided in GNAT, which checks 2982for invalid values under more conditions. Using this feature (see description 2983of the *-gnatV* flag in the GNAT User's Guide) in conjunction with pragma 2984``Initialize_Scalars`` provides a powerful new tool to assist in the detection 2985of problems caused by uninitialized variables. 2986 2987Note: the use of ``Initialize_Scalars`` has a fairly extensive effect on the 2988generated code. This may cause your code to be substantially larger. It may 2989also cause an increase in the amount of stack required, so it is probably a 2990good idea to turn on stack checking (see description of stack checking in the 2991GNAT User's Guide) when using this pragma. 2992 2993.. _Pragma-Initializes: 2994 2995Pragma Initializes 2996================== 2997 2998Syntax: 2999 3000.. code-block:: ada 3001 3002 pragma Initializes (INITIALIZATION_LIST); 3003 3004 INITIALIZATION_LIST ::= 3005 null 3006 | (INITIALIZATION_ITEM {, INITIALIZATION_ITEM}) 3007 3008 INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 3009 3010 INPUT_LIST ::= 3011 null 3012 | INPUT 3013 | (INPUT {, INPUT}) 3014 3015 INPUT ::= name 3016 3017For the semantics of this pragma, see the entry for aspect ``Initializes`` in the 3018SPARK 2014 Reference Manual, section 7.1.5. 3019 3020.. _Pragma-Inline_Always: 3021 3022Pragma Inline_Always 3023==================== 3024 3025Syntax: 3026 3027 3028:: 3029 3030 pragma Inline_Always (NAME [, NAME]); 3031 3032 3033Similar to pragma ``Inline`` except that inlining is unconditional. 3034Inline_Always instructs the compiler to inline every direct call to the 3035subprogram or else to emit a compilation error, independently of any 3036option, in particular *-gnatn* or *-gnatN* or the optimization level. 3037It is an error to take the address or access of ``NAME``. It is also an error to 3038apply this pragma to a primitive operation of a tagged type. Thanks to such 3039restrictions, the compiler is allowed to remove the out-of-line body of ``NAME``. 3040 3041Pragma Inline_Generic 3042===================== 3043 3044Syntax: 3045 3046 3047:: 3048 3049 pragma Inline_Generic (GNAME {, GNAME}); 3050 3051 GNAME ::= generic_unit_NAME | generic_instance_NAME 3052 3053 3054This pragma is provided for compatibility with Dec Ada 83. It has 3055no effect in GNAT (which always inlines generics), other 3056than to check that the given names are all names of generic units or 3057generic instances. 3058 3059Pragma Interface 3060================ 3061 3062Syntax: 3063 3064 3065:: 3066 3067 pragma Interface ( 3068 [Convention =>] convention_identifier, 3069 [Entity =>] local_NAME 3070 [, [External_Name =>] static_string_expression] 3071 [, [Link_Name =>] static_string_expression]); 3072 3073 3074This pragma is identical in syntax and semantics to 3075the standard Ada pragma ``Import``. It is provided for compatibility 3076with Ada 83. The definition is upwards compatible both with pragma 3077``Interface`` as defined in the Ada 83 Reference Manual, and also 3078with some extended implementations of this pragma in certain Ada 83 3079implementations. The only difference between pragma ``Interface`` 3080and pragma ``Import`` is that there is special circuitry to allow 3081both pragmas to appear for the same subprogram entity (normally it 3082is illegal to have multiple ``Import`` pragmas. This is useful in 3083maintaining Ada 83/Ada 95 compatibility and is compatible with other 3084Ada 83 compilers. 3085 3086Pragma Interface_Name 3087===================== 3088 3089Syntax: 3090 3091 3092:: 3093 3094 pragma Interface_Name ( 3095 [Entity =>] LOCAL_NAME 3096 [, [External_Name =>] static_string_EXPRESSION] 3097 [, [Link_Name =>] static_string_EXPRESSION]); 3098 3099 3100This pragma provides an alternative way of specifying the interface name 3101for an interfaced subprogram, and is provided for compatibility with Ada 310283 compilers that use the pragma for this purpose. You must provide at 3103least one of ``External_Name`` or ``Link_Name``. 3104 3105Pragma Interrupt_Handler 3106======================== 3107 3108Syntax: 3109 3110 3111.. code-block:: ada 3112 3113 pragma Interrupt_Handler (procedure_LOCAL_NAME); 3114 3115 3116This program unit pragma is supported for parameterless protected procedures 3117as described in Annex C of the Ada Reference Manual. On the AAMP target 3118the pragma can also be specified for nonprotected parameterless procedures 3119that are declared at the library level (which includes procedures 3120declared at the top level of a library package). In the case of AAMP, 3121when this pragma is applied to a nonprotected procedure, the instruction 3122``IERET`` is generated for returns from the procedure, enabling 3123maskable interrupts, in place of the normal return instruction. 3124 3125Pragma Interrupt_State 3126====================== 3127 3128Syntax: 3129 3130 3131:: 3132 3133 pragma Interrupt_State 3134 ([Name =>] value, 3135 [State =>] SYSTEM | RUNTIME | USER); 3136 3137 3138Normally certain interrupts are reserved to the implementation. Any attempt 3139to attach an interrupt causes Program_Error to be raised, as described in 3140RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in 3141many systems for an :kbd:`Ctrl-C` interrupt. Normally this interrupt is 3142reserved to the implementation, so that :kbd:`Ctrl-C` can be used to 3143interrupt execution. Additionally, signals such as ``SIGSEGV``, 3144``SIGABRT``, ``SIGFPE`` and ``SIGILL`` are often mapped to specific 3145Ada exceptions, or used to implement run-time functions such as the 3146``abort`` statement and stack overflow checking. 3147 3148Pragma ``Interrupt_State`` provides a general mechanism for overriding 3149such uses of interrupts. It subsumes the functionality of pragma 3150``Unreserve_All_Interrupts``. Pragma ``Interrupt_State`` is not 3151available on Windows. On all other platforms than VxWorks, 3152it applies to signals; on VxWorks, it applies to vectored hardware interrupts 3153and may be used to mark interrupts required by the board support package 3154as reserved. 3155 3156Interrupts can be in one of three states: 3157 3158* System 3159 3160 The interrupt is reserved (no Ada handler can be installed), and the 3161 Ada run-time may not install a handler. As a result you are guaranteed 3162 standard system default action if this interrupt is raised. This also allows 3163 installing a low level handler via C APIs such as sigaction(), outside 3164 of Ada control. 3165 3166* Runtime 3167 3168 The interrupt is reserved (no Ada handler can be installed). The run time 3169 is allowed to install a handler for internal control purposes, but is 3170 not required to do so. 3171 3172* User 3173 3174 The interrupt is unreserved. The user may install an Ada handler via 3175 Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 3176 some other action. 3177 3178These states are the allowed values of the ``State`` parameter of the 3179pragma. The ``Name`` parameter is a value of the type 3180``Ada.Interrupts.Interrupt_ID``. Typically, it is a name declared in 3181``Ada.Interrupts.Names``. 3182 3183This is a configuration pragma, and the binder will check that there 3184are no inconsistencies between different units in a partition in how a 3185given interrupt is specified. It may appear anywhere a pragma is legal. 3186 3187The effect is to move the interrupt to the specified state. 3188 3189By declaring interrupts to be SYSTEM, you guarantee the standard system 3190action, such as a core dump. 3191 3192By declaring interrupts to be USER, you guarantee that you can install 3193a handler. 3194 3195Note that certain signals on many operating systems cannot be caught and 3196handled by applications. In such cases, the pragma is ignored. See the 3197operating system documentation, or the value of the array ``Reserved`` 3198declared in the spec of package ``System.OS_Interface``. 3199 3200Overriding the default state of signals used by the Ada runtime may interfere 3201with an application's runtime behavior in the cases of the synchronous signals, 3202and in the case of the signal used to implement the ``abort`` statement. 3203 3204.. _Pragma-Invariant: 3205 3206Pragma Invariant 3207================ 3208 3209Syntax: 3210 3211 3212:: 3213 3214 pragma Invariant 3215 ([Entity =>] private_type_LOCAL_NAME, 3216 [Check =>] EXPRESSION 3217 [,[Message =>] String_Expression]); 3218 3219 3220This pragma provides exactly the same capabilities as the Type_Invariant aspect 3221defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 3222Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 3223requires the use of the aspect syntax, which is not available except in 2012 3224mode, it is not possible to use the Type_Invariant aspect in earlier versions 3225of Ada. However the Invariant pragma may be used in any version of Ada. Also 3226note that the aspect Invariant is a synonym in GNAT for the aspect 3227Type_Invariant, but there is no pragma Type_Invariant. 3228 3229The pragma must appear within the visible part of the package specification, 3230after the type to which its Entity argument appears. As with the Invariant 3231aspect, the Check expression is not analyzed until the end of the visible 3232part of the package, so it may contain forward references. The Message 3233argument, if present, provides the exception message used if the invariant 3234is violated. If no Message parameter is provided, a default message that 3235identifies the line on which the pragma appears is used. 3236 3237It is permissible to have multiple Invariants for the same type entity, in 3238which case they are and'ed together. It is permissible to use this pragma 3239in Ada 2012 mode, but you cannot have both an invariant aspect and an 3240invariant pragma for the same entity. 3241 3242For further details on the use of this pragma, see the Ada 2012 documentation 3243of the Type_Invariant aspect. 3244 3245Pragma Keep_Names 3246================= 3247 3248Syntax: 3249 3250 3251:: 3252 3253 pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 3254 3255 3256The ``LOCAL_NAME`` argument 3257must refer to an enumeration first subtype 3258in the current declarative part. The effect is to retain the enumeration 3259literal names for use by ``Image`` and ``Value`` even if a global 3260``Discard_Names`` pragma applies. This is useful when you want to 3261generally suppress enumeration literal names and for example you therefore 3262use a ``Discard_Names`` pragma in the :file:`gnat.adc` file, but you 3263want to retain the names for specific enumeration types. 3264 3265Pragma License 3266============== 3267.. index:: License checking 3268 3269Syntax: 3270 3271 3272.. code-block:: ada 3273 3274 pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 3275 3276 3277This pragma is provided to allow automated checking for appropriate license 3278conditions with respect to the standard and modified GPL. A pragma 3279``License``, which is a configuration pragma that typically appears at 3280the start of a source file or in a separate :file:`gnat.adc` file, specifies 3281the licensing conditions of a unit as follows: 3282 3283* Unrestricted 3284 This is used for a unit that can be freely used with no license restrictions. 3285 Examples of such units are public domain units, and units from the Ada 3286 Reference Manual. 3287 3288* GPL 3289 This is used for a unit that is licensed under the unmodified GPL, and which 3290 therefore cannot be ``with``\ ed by a restricted unit. 3291 3292* Modified_GPL 3293 This is used for a unit licensed under the GNAT modified GPL that includes 3294 a special exception paragraph that specifically permits the inclusion of 3295 the unit in programs without requiring the entire program to be released 3296 under the GPL. 3297 3298* Restricted 3299 This is used for a unit that is restricted in that it is not permitted to 3300 depend on units that are licensed under the GPL. Typical examples are 3301 proprietary code that is to be released under more restrictive license 3302 conditions. Note that restricted units are permitted to ``with`` units 3303 which are licensed under the modified GPL (this is the whole point of the 3304 modified GPL). 3305 3306 3307Normally a unit with no ``License`` pragma is considered to have an 3308unknown license, and no checking is done. However, standard GNAT headers 3309are recognized, and license information is derived from them as follows. 3310 3311A GNAT license header starts with a line containing 78 hyphens. The following 3312comment text is searched for the appearance of any of the following strings. 3313 3314If the string 'GNU General Public License' is found, then the unit is assumed 3315to have GPL license, unless the string 'As a special exception' follows, in 3316which case the license is assumed to be modified GPL. 3317 3318If one of the strings 3319'This specification is adapted from the Ada Semantic Interface' or 3320'This specification is derived from the Ada Reference Manual' is found 3321then the unit is assumed to be unrestricted. 3322 3323These default actions means that a program with a restricted license pragma 3324will automatically get warnings if a GPL unit is inappropriately 3325``with``\ ed. For example, the program: 3326 3327.. code-block:: ada 3328 3329 with Sem_Ch3; 3330 with GNAT.Sockets; 3331 procedure Secret_Stuff is 3332 ... 3333 end Secret_Stuff 3334 3335 3336if compiled with pragma ``License`` (``Restricted``) in a 3337:file:`gnat.adc` file will generate the warning:: 3338 3339 1. with Sem_Ch3; 3340 | 3341 >>> license of withed unit "Sem_Ch3" is incompatible 3342 3343 2. with GNAT.Sockets; 3344 3. procedure Secret_Stuff is 3345 3346 3347Here we get a warning on ``Sem_Ch3`` since it is part of the GNAT 3348compiler and is licensed under the 3349GPL, but no warning for ``GNAT.Sockets`` which is part of the GNAT 3350run time, and is therefore licensed under the modified GPL. 3351 3352Pragma Link_With 3353================ 3354 3355Syntax: 3356 3357 3358:: 3359 3360 pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION}); 3361 3362 3363This pragma is provided for compatibility with certain Ada 83 compilers. 3364It has exactly the same effect as pragma ``Linker_Options`` except 3365that spaces occurring within one of the string expressions are treated 3366as separators. For example, in the following case: 3367 3368.. code-block:: ada 3369 3370 pragma Link_With ("-labc -ldef"); 3371 3372 3373results in passing the strings ``-labc`` and ``-ldef`` as two 3374separate arguments to the linker. In addition pragma Link_With allows 3375multiple arguments, with the same effect as successive pragmas. 3376 3377Pragma Linker_Alias 3378=================== 3379 3380Syntax: 3381 3382 3383:: 3384 3385 pragma Linker_Alias ( 3386 [Entity =>] LOCAL_NAME, 3387 [Target =>] static_string_EXPRESSION); 3388 3389 3390``LOCAL_NAME`` must refer to an object that is declared at the library 3391level. This pragma establishes the given entity as a linker alias for the 3392given target. It is equivalent to ``__attribute__((alias))`` in GNU C 3393and causes ``LOCAL_NAME`` to be emitted as an alias for the symbol 3394``static_string_EXPRESSION`` in the object file, that is to say no space 3395is reserved for ``LOCAL_NAME`` by the assembler and it will be resolved 3396to the same address as ``static_string_EXPRESSION`` by the linker. 3397 3398The actual linker name for the target must be used (e.g., the fully 3399encoded name with qualification in Ada, or the mangled name in C++), 3400or it must be declared using the C convention with ``pragma Import`` 3401or ``pragma Export``. 3402 3403Not all target machines support this pragma. On some of them it is accepted 3404only if ``pragma Weak_External`` has been applied to ``LOCAL_NAME``. 3405 3406 3407.. code-block:: ada 3408 3409 -- Example of the use of pragma Linker_Alias 3410 3411 package p is 3412 i : Integer := 1; 3413 pragma Export (C, i); 3414 3415 new_name_for_i : Integer; 3416 pragma Linker_Alias (new_name_for_i, "i"); 3417 end p; 3418 3419 3420Pragma Linker_Constructor 3421========================= 3422 3423Syntax: 3424 3425 3426.. code-block:: ada 3427 3428 pragma Linker_Constructor (procedure_LOCAL_NAME); 3429 3430 3431``procedure_LOCAL_NAME`` must refer to a parameterless procedure that 3432is declared at the library level. A procedure to which this pragma is 3433applied will be treated as an initialization routine by the linker. 3434It is equivalent to ``__attribute__((constructor))`` in GNU C and 3435causes ``procedure_LOCAL_NAME`` to be invoked before the entry point 3436of the executable is called (or immediately after the shared library is 3437loaded if the procedure is linked in a shared library), in particular 3438before the Ada run-time environment is set up. 3439 3440Because of these specific contexts, the set of operations such a procedure 3441can perform is very limited and the type of objects it can manipulate is 3442essentially restricted to the elementary types. In particular, it must only 3443contain code to which pragma Restrictions (No_Elaboration_Code) applies. 3444 3445This pragma is used by GNAT to implement auto-initialization of shared Stand 3446Alone Libraries, which provides a related capability without the restrictions 3447listed above. Where possible, the use of Stand Alone Libraries is preferable 3448to the use of this pragma. 3449 3450Pragma Linker_Destructor 3451======================== 3452 3453Syntax: 3454 3455 3456.. code-block:: ada 3457 3458 pragma Linker_Destructor (procedure_LOCAL_NAME); 3459 3460 3461``procedure_LOCAL_NAME`` must refer to a parameterless procedure that 3462is declared at the library level. A procedure to which this pragma is 3463applied will be treated as a finalization routine by the linker. 3464It is equivalent to ``__attribute__((destructor))`` in GNU C and 3465causes ``procedure_LOCAL_NAME`` to be invoked after the entry point 3466of the executable has exited (or immediately before the shared library 3467is unloaded if the procedure is linked in a shared library), in particular 3468after the Ada run-time environment is shut down. 3469 3470See ``pragma Linker_Constructor`` for the set of restrictions that apply 3471because of these specific contexts. 3472 3473.. _Pragma-Linker_Section: 3474 3475Pragma Linker_Section 3476===================== 3477 3478Syntax: 3479 3480 3481:: 3482 3483 pragma Linker_Section ( 3484 [Entity =>] LOCAL_NAME, 3485 [Section =>] static_string_EXPRESSION); 3486 3487 3488``LOCAL_NAME`` must refer to an object, type, or subprogram that is 3489declared at the library level. This pragma specifies the name of the 3490linker section for the given entity. It is equivalent to 3491``__attribute__((section))`` in GNU C and causes ``LOCAL_NAME`` to 3492be placed in the ``static_string_EXPRESSION`` section of the 3493executable (assuming the linker doesn't rename the section). 3494GNAT also provides an implementation defined aspect of the same name. 3495 3496In the case of specifying this aspect for a type, the effect is to 3497specify the corresponding section for all library-level objects of 3498the type that do not have an explicit linker section set. Note that 3499this only applies to whole objects, not to components of composite objects. 3500 3501In the case of a subprogram, the linker section applies to all previously 3502declared matching overloaded subprograms in the current declarative part 3503which do not already have a linker section assigned. The linker section 3504aspect is useful in this case for specifying different linker sections 3505for different elements of such an overloaded set. 3506 3507Note that an empty string specifies that no linker section is specified. 3508This is not quite the same as omitting the pragma or aspect, since it 3509can be used to specify that one element of an overloaded set of subprograms 3510has the default linker section, or that one object of a type for which a 3511linker section is specified should has the default linker section. 3512 3513The compiler normally places library-level entities in standard sections 3514depending on the class: procedures and functions generally go in the 3515``.text`` section, initialized variables in the ``.data`` section 3516and uninitialized variables in the ``.bss`` section. 3517 3518Other, special sections may exist on given target machines to map special 3519hardware, for example I/O ports or flash memory. This pragma is a means to 3520defer the final layout of the executable to the linker, thus fully working 3521at the symbolic level with the compiler. 3522 3523Some file formats do not support arbitrary sections so not all target 3524machines support this pragma. The use of this pragma may cause a program 3525execution to be erroneous if it is used to place an entity into an 3526inappropriate section (e.g., a modified variable into the ``.text`` 3527section). See also ``pragma Persistent_BSS``. 3528 3529 3530.. code-block:: ada 3531 3532 -- Example of the use of pragma Linker_Section 3533 3534 package IO_Card is 3535 Port_A : Integer; 3536 pragma Volatile (Port_A); 3537 pragma Linker_Section (Port_A, ".bss.port_a"); 3538 3539 Port_B : Integer; 3540 pragma Volatile (Port_B); 3541 pragma Linker_Section (Port_B, ".bss.port_b"); 3542 3543 type Port_Type is new Integer with Linker_Section => ".bss"; 3544 PA : Port_Type with Linker_Section => ".bss.PA"; 3545 PB : Port_Type; -- ends up in linker section ".bss" 3546 3547 procedure Q with Linker_Section => "Qsection"; 3548 end IO_Card; 3549 3550.. _Pragma-Lock_Free: 3551 3552Pragma Lock_Free 3553================ 3554 3555Syntax: 3556This pragma may be specified for protected types or objects. It specifies that 3557the implementation of protected operations must be implemented without locks. 3558Compilation fails if the compiler cannot generate lock-free code for the 3559operations. 3560 3561The current conditions required to support this pragma are: 3562 3563* Protected type declarations may not contain entries 3564* Protected subprogram declarations may not have nonelementary parameters 3565 3566In addition, each protected subprogram body must satisfy: 3567 3568* May reference only one protected component 3569* May not reference nonconstant entities outside the protected subprogram 3570 scope. 3571* May not contain address representation items, allocators, or quantified 3572 expressions. 3573* May not contain delay, goto, loop, or procedure-call statements. 3574* May not contain exported and imported entities 3575* May not dereferenced access values 3576* Function calls and attribute references must be static 3577 3578 3579Pragma Loop_Invariant 3580===================== 3581 3582Syntax: 3583 3584 3585.. code-block:: ada 3586 3587 pragma Loop_Invariant ( boolean_EXPRESSION ); 3588 3589 3590The effect of this pragma is similar to that of pragma ``Assert``, 3591except that in an ``Assertion_Policy`` pragma, the identifier 3592``Loop_Invariant`` is used to control whether it is ignored or checked 3593(or disabled). 3594 3595``Loop_Invariant`` can only appear as one of the items in the sequence 3596of statements of a loop body, or nested inside block statements that 3597appear in the sequence of statements of a loop body. 3598The intention is that it be used to 3599represent a "loop invariant" assertion, i.e. something that is true each 3600time through the loop, and which can be used to show that the loop is 3601achieving its purpose. 3602 3603Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that 3604apply to the same loop should be grouped in the same sequence of 3605statements. 3606 3607To aid in writing such invariants, the special attribute ``Loop_Entry`` 3608may be used to refer to the value of an expression on entry to the loop. This 3609attribute can only be used within the expression of a ``Loop_Invariant`` 3610pragma. For full details, see documentation of attribute ``Loop_Entry``. 3611 3612Pragma Loop_Optimize 3613==================== 3614 3615Syntax: 3616 3617 3618:: 3619 3620 pragma Loop_Optimize (OPTIMIZATION_HINT {, OPTIMIZATION_HINT}); 3621 3622 OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 3623 3624 3625This pragma must appear immediately within a loop statement. It allows the 3626programmer to specify optimization hints for the enclosing loop. The hints 3627are not mutually exclusive and can be freely mixed, but not all combinations 3628will yield a sensible outcome. 3629 3630There are five supported optimization hints for a loop: 3631 3632* Ivdep 3633 3634 The programmer asserts that there are no loop-carried dependencies 3635 which would prevent consecutive iterations of the loop from being 3636 executed simultaneously. 3637 3638* No_Unroll 3639 3640 The loop must not be unrolled. This is a strong hint: the compiler will not 3641 unroll a loop marked with this hint. 3642 3643* Unroll 3644 3645 The loop should be unrolled. This is a weak hint: the compiler will try to 3646 apply unrolling to this loop preferably to other optimizations, notably 3647 vectorization, but there is no guarantee that the loop will be unrolled. 3648 3649* No_Vector 3650 3651 The loop must not be vectorized. This is a strong hint: the compiler will not 3652 vectorize a loop marked with this hint. 3653 3654* Vector 3655 3656 The loop should be vectorized. This is a weak hint: the compiler will try to 3657 apply vectorization to this loop preferably to other optimizations, notably 3658 unrolling, but there is no guarantee that the loop will be vectorized. 3659 3660 3661These hints do not remove the need to pass the appropriate switches to the 3662compiler in order to enable the relevant optimizations, that is to say 3663*-funroll-loops* for unrolling and *-ftree-vectorize* for 3664vectorization. 3665 3666Pragma Loop_Variant 3667=================== 3668 3669Syntax: 3670 3671 3672:: 3673 3674 pragma Loop_Variant ( LOOP_VARIANT_ITEM {, LOOP_VARIANT_ITEM } ); 3675 LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 3676 CHANGE_DIRECTION ::= Increases | Decreases 3677 3678 3679``Loop_Variant`` can only appear as one of the items in the sequence 3680of statements of a loop body, or nested inside block statements that 3681appear in the sequence of statements of a loop body. 3682It allows the specification of quantities which must always 3683decrease or increase in successive iterations of the loop. In its simplest 3684form, just one expression is specified, whose value must increase or decrease 3685on each iteration of the loop. 3686 3687In a more complex form, multiple arguments can be given which are intepreted 3688in a nesting lexicographic manner. For example: 3689 3690.. code-block:: ada 3691 3692 pragma Loop_Variant (Increases => X, Decreases => Y); 3693 3694 3695specifies that each time through the loop either X increases, or X stays 3696the same and Y decreases. A ``Loop_Variant`` pragma ensures that the 3697loop is making progress. It can be useful in helping to show informally 3698or prove formally that the loop always terminates. 3699 3700``Loop_Variant`` is an assertion whose effect can be controlled using 3701an ``Assertion_Policy`` with a check name of ``Loop_Variant``. The 3702policy can be ``Check`` to enable the loop variant check, ``Ignore`` 3703to ignore the check (in which case the pragma has no effect on the program), 3704or ``Disable`` in which case the pragma is not even checked for correct 3705syntax. 3706 3707Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that 3708apply to the same loop should be grouped in the same sequence of 3709statements. 3710 3711The ``Loop_Entry`` attribute may be used within the expressions of the 3712``Loop_Variant`` pragma to refer to values on entry to the loop. 3713 3714Pragma Machine_Attribute 3715======================== 3716 3717Syntax: 3718 3719 3720:: 3721 3722 pragma Machine_Attribute ( 3723 [Entity =>] LOCAL_NAME, 3724 [Attribute_Name =>] static_string_EXPRESSION 3725 [, [Info =>] static_EXPRESSION {, static_EXPRESSION}] ); 3726 3727 3728Machine-dependent attributes can be specified for types and/or 3729declarations. This pragma is semantically equivalent to 3730:samp:`__attribute__(({attribute_name}))` (if ``info`` is not 3731specified) or :samp:`__attribute__(({attribute_name(info})))` 3732or :samp:`__attribute__(({attribute_name(info,...})))` in GNU C, 3733where *attribute_name* is recognized by the compiler middle-end 3734or the ``TARGET_ATTRIBUTE_TABLE`` machine specific macro. Note 3735that a string literal for the optional parameter ``info`` or the 3736following ones is transformed by default into an identifier, 3737which may make this pragma unusable for some attributes. 3738For further information see :title:`GNU Compiler Collection (GCC) Internals`. 3739 3740Pragma Main 3741=========== 3742 3743Syntax:: 3744 3745 pragma Main 3746 (MAIN_OPTION [, MAIN_OPTION]); 3747 3748 MAIN_OPTION ::= 3749 [Stack_Size =>] static_integer_EXPRESSION 3750 | [Task_Stack_Size_Default =>] static_integer_EXPRESSION 3751 | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 3752 3753 3754This pragma is provided for compatibility with OpenVMS VAX Systems. It has 3755no effect in GNAT, other than being syntax checked. 3756 3757Pragma Main_Storage 3758=================== 3759 3760Syntax:: 3761 3762 pragma Main_Storage 3763 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 3764 3765 MAIN_STORAGE_OPTION ::= 3766 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 3767 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION 3768 3769 3770This pragma is provided for compatibility with OpenVMS VAX Systems. It has 3771no effect in GNAT, other than being syntax checked. 3772 3773.. _Pragma-Max_Queue_Length: 3774 3775Pragma Max_Queue_Length 3776======================= 3777 3778Syntax:: 3779 3780 pragma Max_Entry_Queue (static_integer_EXPRESSION); 3781 3782 3783This pragma is used to specify the maximum callers per entry queue for 3784individual protected entries and entry families. It accepts a single 3785integer (-1 or more) as a parameter and must appear after the declaration of an 3786entry. 3787 3788A value of -1 represents no additional restriction on queue length. 3789 3790Pragma No_Body 3791============== 3792 3793Syntax: 3794 3795 3796.. code-block:: ada 3797 3798 pragma No_Body; 3799 3800 3801There are a number of cases in which a package spec does not require a body, 3802and in fact a body is not permitted. GNAT will not permit the spec to be 3803compiled if there is a body around. The pragma No_Body allows you to provide 3804a body file, even in a case where no body is allowed. The body file must 3805contain only comments and a single No_Body pragma. This is recognized by 3806the compiler as indicating that no body is logically present. 3807 3808This is particularly useful during maintenance when a package is modified in 3809such a way that a body needed before is no longer needed. The provision of a 3810dummy body with a No_Body pragma ensures that there is no interference from 3811earlier versions of the package body. 3812 3813.. _Pragma-No_Caching: 3814 3815Pragma No_Caching 3816================= 3817 3818Syntax: 3819 3820.. code-block:: ada 3821 3822 pragma No_Caching [ (boolean_EXPRESSION) ]; 3823 3824For the semantics of this pragma, see the entry for aspect ``No_Caching`` in 3825the SPARK 2014 Reference Manual, section 7.1.2. 3826 3827Pragma No_Component_Reordering 3828============================== 3829 3830Syntax: 3831 3832 3833:: 3834 3835 pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 3836 3837 3838``type_LOCAL_NAME`` must refer to a record type declaration in the current 3839declarative part. The effect is to preclude any reordering of components 3840for the layout of the record, i.e. the record is laid out by the compiler 3841in the order in which the components are declared textually. The form with 3842no argument is a configuration pragma which applies to all record types 3843declared in units to which the pragma applies and there is a requirement 3844that this pragma be used consistently within a partition. 3845 3846.. _Pragma-No_Elaboration_Code_All: 3847 3848Pragma No_Elaboration_Code_All 3849============================== 3850 3851Syntax: 3852 3853 3854:: 3855 3856 pragma No_Elaboration_Code_All [(program_unit_NAME)]; 3857 3858 3859This is a program unit pragma (there is also an equivalent aspect of the 3860same name) that establishes the restriction ``No_Elaboration_Code`` for 3861the current unit and any extended main source units (body and subunits). 3862It also has the effect of enforcing a transitive application of this 3863aspect, so that if any unit is implicitly or explicitly with'ed by the 3864current unit, it must also have the No_Elaboration_Code_All aspect set. 3865It may be applied to package or subprogram specs or their generic versions. 3866 3867Pragma No_Heap_Finalization 3868=========================== 3869 3870Syntax: 3871 3872 3873:: 3874 3875 pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 3876 3877 3878Pragma ``No_Heap_Finalization`` may be used as a configuration pragma or as a 3879type-specific pragma. 3880 3881In its configuration form, the pragma must appear within a configuration file 3882such as gnat.adc, without an argument. The pragma suppresses the call to 3883``Finalize`` for heap-allocated objects created through library-level named 3884access-to-object types in cases where the designated type requires finalization 3885actions. 3886 3887In its type-specific form, the argument of the pragma must denote a 3888library-level named access-to-object type. The pragma suppresses the call to 3889``Finalize`` for heap-allocated objects created through the specific access type 3890in cases where the designated type requires finalization actions. 3891 3892It is still possible to finalize such heap-allocated objects by explicitly 3893deallocating them. 3894 3895A library-level named access-to-object type declared within a generic unit will 3896lose its ``No_Heap_Finalization`` pragma when the corresponding instance does not 3897appear at the library level. 3898 3899.. _Pragma-No_Inline: 3900 3901Pragma No_Inline 3902================ 3903 3904Syntax: 3905 3906 3907:: 3908 3909 pragma No_Inline (NAME {, NAME}); 3910 3911 3912This pragma suppresses inlining for the callable entity or the instances of 3913the generic subprogram designated by ``NAME``, including inlining that 3914results from the use of pragma ``Inline``. This pragma is always active, 3915in particular it is not subject to the use of option *-gnatn* or 3916*-gnatN*. It is illegal to specify both pragma ``No_Inline`` and 3917pragma ``Inline_Always`` for the same ``NAME``. 3918 3919Pragma No_Return 3920================ 3921 3922Syntax: 3923 3924 3925:: 3926 3927 pragma No_Return (procedure_LOCAL_NAME {, procedure_LOCAL_NAME}); 3928 3929 3930Each ``procedure_LOCAL_NAME`` argument must refer to one or more procedure 3931declarations in the current declarative part. A procedure to which this 3932pragma is applied may not contain any explicit ``return`` statements. 3933In addition, if the procedure contains any implicit returns from falling 3934off the end of a statement sequence, then execution of that implicit 3935return will cause Program_Error to be raised. 3936 3937One use of this pragma is to identify procedures whose only purpose is to raise 3938an exception. Another use of this pragma is to suppress incorrect warnings 3939about missing returns in functions, where the last statement of a function 3940statement sequence is a call to such a procedure. 3941 3942Note that in Ada 2005 mode, this pragma is part of the language. It is 3943available in all earlier versions of Ada as an implementation-defined 3944pragma. 3945 3946Pragma No_Strict_Aliasing 3947========================= 3948 3949Syntax: 3950 3951 3952:: 3953 3954 pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 3955 3956 3957``type_LOCAL_NAME`` must refer to an access type 3958declaration in the current declarative part. The effect is to inhibit 3959strict aliasing optimization for the given type. The form with no 3960arguments is a configuration pragma which applies to all access types 3961declared in units to which the pragma applies. For a detailed 3962description of the strict aliasing optimization, and the situations 3963in which it must be suppressed, see the section on Optimization and Strict Aliasing 3964in the :title:`GNAT User's Guide`. 3965 3966This pragma currently has no effects on access to unconstrained array types. 3967 3968.. _Pragma-No_Tagged_Streams: 3969 3970Pragma No_Tagged_Streams 3971======================== 3972 3973Syntax: 3974 3975 3976:: 3977 3978 pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 3979 3980 3981Normally when a tagged type is introduced using a full type declaration, 3982part of the processing includes generating stream access routines to be 3983used by stream attributes referencing the type (or one of its subtypes 3984or derived types). This can involve the generation of significant amounts 3985of code which is wasted space if stream routines are not needed for the 3986type in question. 3987 3988The ``No_Tagged_Streams`` pragma causes the generation of these stream 3989routines to be skipped, and any attempt to use stream operations on 3990types subject to this pragma will be statically rejected as illegal. 3991 3992There are two forms of the pragma. The form with no arguments must appear 3993in a declarative sequence or in the declarations of a package spec. This 3994pragma affects all subsequent root tagged types declared in the declaration 3995sequence, and specifies that no stream routines be generated. The form with 3996an argument (for which there is also a corresponding aspect) specifies a 3997single root tagged type for which stream routines are not to be generated. 3998 3999Once the pragma has been given for a particular root tagged type, all subtypes 4000and derived types of this type inherit the pragma automatically, so the effect 4001applies to a complete hierarchy (this is necessary to deal with the class-wide 4002dispatching versions of the stream routines). 4003 4004When pragmas ``Discard_Names`` and ``No_Tagged_Streams`` are simultaneously 4005applied to a tagged type its Expanded_Name and External_Tag are initialized 4006with empty strings. This is useful to avoid exposing entity names at binary 4007level but has a negative impact on the debuggability of tagged types. 4008 4009Pragma Normalize_Scalars 4010======================== 4011 4012Syntax: 4013 4014 4015.. code-block:: ada 4016 4017 pragma Normalize_Scalars; 4018 4019 4020This is a language defined pragma which is fully implemented in GNAT. The 4021effect is to cause all scalar objects that are not otherwise initialized 4022to be initialized. The initial values are implementation dependent and 4023are as follows: 4024 4025 4026 4027*Standard.Character* 4028 Objects whose root type is Standard.Character are initialized to 4029 Character'Last unless the subtype range excludes NUL (in which case 4030 NUL is used). This choice will always generate an invalid value if 4031 one exists. 4032 4033 4034*Standard.Wide_Character* 4035 Objects whose root type is Standard.Wide_Character are initialized to 4036 Wide_Character'Last unless the subtype range excludes NUL (in which case 4037 NUL is used). This choice will always generate an invalid value if 4038 one exists. 4039 4040 4041*Standard.Wide_Wide_Character* 4042 Objects whose root type is Standard.Wide_Wide_Character are initialized to 4043 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 4044 which case NUL is used). This choice will always generate an invalid value if 4045 one exists. 4046 4047 4048*Integer types* 4049 Objects of an integer type are treated differently depending on whether 4050 negative values are present in the subtype. If no negative values are 4051 present, then all one bits is used as the initial value except in the 4052 special case where zero is excluded from the subtype, in which case 4053 all zero bits are used. This choice will always generate an invalid 4054 value if one exists. 4055 4056 For subtypes with negative values present, the largest negative number 4057 is used, except in the unusual case where this largest negative number 4058 is in the subtype, and the largest positive number is not, in which case 4059 the largest positive value is used. This choice will always generate 4060 an invalid value if one exists. 4061 4062 4063*Floating-Point Types* 4064 Objects of all floating-point types are initialized to all 1-bits. For 4065 standard IEEE format, this corresponds to a NaN (not a number) which is 4066 indeed an invalid value. 4067 4068 4069*Fixed-Point Types* 4070 Objects of all fixed-point types are treated as described above for integers, 4071 with the rules applying to the underlying integer value used to represent 4072 the fixed-point value. 4073 4074 4075*Modular types* 4076 Objects of a modular type are initialized to all one bits, except in 4077 the special case where zero is excluded from the subtype, in which 4078 case all zero bits are used. This choice will always generate an 4079 invalid value if one exists. 4080 4081 4082*Enumeration types* 4083 Objects of an enumeration type are initialized to all one-bits, i.e., to 4084 the value ``2 ** typ'Size - 1`` unless the subtype excludes the literal 4085 whose Pos value is zero, in which case a code of zero is used. This choice 4086 will always generate an invalid value if one exists. 4087 4088.. _Pragma_Obsolescent: 4089 4090Pragma Obsolescent 4091================== 4092 4093Syntax: 4094 4095 4096:: 4097 4098 pragma Obsolescent; 4099 4100 pragma Obsolescent ( 4101 [Message =>] static_string_EXPRESSION 4102 [,[Version =>] Ada_05]]); 4103 4104 pragma Obsolescent ( 4105 [Entity =>] NAME 4106 [,[Message =>] static_string_EXPRESSION 4107 [,[Version =>] Ada_05]] ); 4108 4109 4110This pragma can occur immediately following a declaration of an entity, 4111including the case of a record component. If no Entity argument is present, 4112then this declaration is the one to which the pragma applies. If an Entity 4113parameter is present, it must either match the name of the entity in this 4114declaration, or alternatively, the pragma can immediately follow an enumeration 4115type declaration, where the Entity argument names one of the enumeration 4116literals. 4117 4118This pragma is used to indicate that the named entity 4119is considered obsolescent and should not be used. Typically this is 4120used when an API must be modified by eventually removing or modifying 4121existing subprograms or other entities. The pragma can be used at an 4122intermediate stage when the entity is still present, but will be 4123removed later. 4124 4125The effect of this pragma is to output a warning message on a reference to 4126an entity thus marked that the subprogram is obsolescent if the appropriate 4127warning option in the compiler is activated. If the ``Message`` parameter is 4128present, then a second warning message is given containing this text. In 4129addition, a reference to the entity is considered to be a violation of pragma 4130``Restrictions (No_Obsolescent_Features)``. 4131 4132This pragma can also be used as a program unit pragma for a package, 4133in which case the entity name is the name of the package, and the 4134pragma indicates that the entire package is considered 4135obsolescent. In this case a client ``with``\ ing such a package 4136violates the restriction, and the ``with`` clause is 4137flagged with warnings if the warning option is set. 4138 4139If the ``Version`` parameter is present (which must be exactly 4140the identifier ``Ada_05``, no other argument is allowed), then the 4141indication of obsolescence applies only when compiling in Ada 2005 4142mode. This is primarily intended for dealing with the situations 4143in the predefined library where subprograms or packages 4144have become defined as obsolescent in Ada 2005 4145(e.g., in ``Ada.Characters.Handling``), but may be used anywhere. 4146 4147The following examples show typical uses of this pragma: 4148 4149 4150.. code-block:: ada 4151 4152 package p is 4153 pragma Obsolescent (p, Message => "use pp instead of p"); 4154 end p; 4155 4156 package q is 4157 procedure q2; 4158 pragma Obsolescent ("use q2new instead"); 4159 4160 type R is new integer; 4161 pragma Obsolescent 4162 (Entity => R, 4163 Message => "use RR in Ada 2005", 4164 Version => Ada_05); 4165 4166 type M is record 4167 F1 : Integer; 4168 F2 : Integer; 4169 pragma Obsolescent; 4170 F3 : Integer; 4171 end record; 4172 4173 type E is (a, bc, 'd', quack); 4174 pragma Obsolescent (Entity => bc) 4175 pragma Obsolescent (Entity => 'd') 4176 4177 function "+" 4178 (a, b : character) return character; 4179 pragma Obsolescent (Entity => "+"); 4180 end; 4181 4182 4183Note that, as for all pragmas, if you use a pragma argument identifier, 4184then all subsequent parameters must also use a pragma argument identifier. 4185So if you specify ``Entity =>`` for the ``Entity`` argument, and a ``Message`` 4186argument is present, it must be preceded by ``Message =>``. 4187 4188Pragma Optimize_Alignment 4189========================= 4190.. index:: Alignment, default settings 4191 4192Syntax: 4193 4194 4195.. code-block:: ada 4196 4197 pragma Optimize_Alignment (TIME | SPACE | OFF); 4198 4199 4200This is a configuration pragma which affects the choice of default alignments 4201for types and objects where no alignment is explicitly specified. There is a 4202time/space trade-off in the selection of these values. Large alignments result 4203in more efficient code, at the expense of larger data space, since sizes have 4204to be increased to match these alignments. Smaller alignments save space, but 4205the access code is slower. The normal choice of default alignments for types 4206and individual alignment promotions for objects (which is what you get if you 4207do not use this pragma, or if you use an argument of OFF), tries to balance 4208these two requirements. 4209 4210Specifying SPACE causes smaller default alignments to be chosen in two cases. 4211First any packed record is given an alignment of 1. Second, if a size is given 4212for the type, then the alignment is chosen to avoid increasing this size. For 4213example, consider: 4214 4215 4216.. code-block:: ada 4217 4218 type R is record 4219 X : Integer; 4220 Y : Character; 4221 end record; 4222 4223 for R'Size use 5*8; 4224 4225 4226In the default mode, this type gets an alignment of 4, so that access to the 4227Integer field X are efficient. But this means that objects of the type end up 4228with a size of 8 bytes. This is a valid choice, since sizes of objects are 4229allowed to be bigger than the size of the type, but it can waste space if for 4230example fields of type R appear in an enclosing record. If the above type is 4231compiled in ``Optimize_Alignment (Space)`` mode, the alignment is set to 1. 4232 4233However, there is one case in which SPACE is ignored. If a variable length 4234record (that is a discriminated record with a component which is an array 4235whose length depends on a discriminant), has a pragma Pack, then it is not 4236in general possible to set the alignment of such a record to one, so the 4237pragma is ignored in this case (with a warning). 4238 4239Specifying SPACE also disables alignment promotions for standalone objects, 4240which occur when the compiler increases the alignment of a specific object 4241without changing the alignment of its type. 4242 4243Specifying SPACE also disables component reordering in unpacked record types, 4244which can result in larger sizes in order to meet alignment requirements. 4245 4246Specifying TIME causes larger default alignments to be chosen in the case of 4247small types with sizes that are not a power of 2. For example, consider: 4248 4249 4250.. code-block:: ada 4251 4252 type R is record 4253 A : Character; 4254 B : Character; 4255 C : Boolean; 4256 end record; 4257 4258 pragma Pack (R); 4259 for R'Size use 17; 4260 4261 4262The default alignment for this record is normally 1, but if this type is 4263compiled in ``Optimize_Alignment (Time)`` mode, then the alignment is set 4264to 4, which wastes space for objects of the type, since they are now 4 bytes 4265long, but results in more efficient access when the whole record is referenced. 4266 4267As noted above, this is a configuration pragma, and there is a requirement 4268that all units in a partition be compiled with a consistent setting of the 4269optimization setting. This would normally be achieved by use of a configuration 4270pragma file containing the appropriate setting. The exception to this rule is 4271that units with an explicit configuration pragma in the same file as the source 4272unit are excluded from the consistency check, as are all predefined units. The 4273latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 4274pragma appears at the start of the file. 4275 4276Pragma Ordered 4277============== 4278 4279Syntax: 4280 4281 4282.. code-block:: ada 4283 4284 pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 4285 4286 4287Most enumeration types are from a conceptual point of view unordered. 4288For example, consider: 4289 4290 4291.. code-block:: ada 4292 4293 type Color is (Red, Blue, Green, Yellow); 4294 4295 4296By Ada semantics ``Blue > Red`` and ``Green > Blue``, 4297but really these relations make no sense; the enumeration type merely 4298specifies a set of possible colors, and the order is unimportant. 4299 4300For unordered enumeration types, it is generally a good idea if 4301clients avoid comparisons (other than equality or inequality) and 4302explicit ranges. (A *client* is a unit where the type is referenced, 4303other than the unit where the type is declared, its body, and its subunits.) 4304For example, if code buried in some client says: 4305 4306 4307.. code-block:: ada 4308 4309 if Current_Color < Yellow then ... 4310 if Current_Color in Blue .. Green then ... 4311 4312 4313then the client code is relying on the order, which is undesirable. 4314It makes the code hard to read and creates maintenance difficulties if 4315entries have to be added to the enumeration type. Instead, 4316the code in the client should list the possibilities, or an 4317appropriate subtype should be declared in the unit that declares 4318the original enumeration type. E.g., the following subtype could 4319be declared along with the type ``Color``: 4320 4321 4322.. code-block:: ada 4323 4324 subtype RBG is Color range Red .. Green; 4325 4326 4327and then the client could write: 4328 4329 4330.. code-block:: ada 4331 4332 if Current_Color in RBG then ... 4333 if Current_Color = Blue or Current_Color = Green then ... 4334 4335 4336However, some enumeration types are legitimately ordered from a conceptual 4337point of view. For example, if you declare: 4338 4339 4340.. code-block:: ada 4341 4342 type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 4343 4344 4345then the ordering imposed by the language is reasonable, and 4346clients can depend on it, writing for example: 4347 4348 4349.. code-block:: ada 4350 4351 if D in Mon .. Fri then ... 4352 if D < Wed then ... 4353 4354 4355The pragma *Ordered* is provided to mark enumeration types that 4356are conceptually ordered, alerting the reader that clients may depend 4357on the ordering. GNAT provides a pragma to mark enumerations as ordered 4358rather than one to mark them as unordered, since in our experience, 4359the great majority of enumeration types are conceptually unordered. 4360 4361The types ``Boolean``, ``Character``, ``Wide_Character``, 4362and ``Wide_Wide_Character`` 4363are considered to be ordered types, so each is declared with a 4364pragma ``Ordered`` in package ``Standard``. 4365 4366Normally pragma ``Ordered`` serves only as documentation and a guide for 4367coding standards, but GNAT provides a warning switch *-gnatw.u* that 4368requests warnings for inappropriate uses (comparisons and explicit 4369subranges) for unordered types. If this switch is used, then any 4370enumeration type not marked with pragma ``Ordered`` will be considered 4371as unordered, and will generate warnings for inappropriate uses. 4372 4373Note that generic types are not considered ordered or unordered (since the 4374template can be instantiated for both cases), so we never generate warnings 4375for the case of generic enumerated types. 4376 4377For additional information please refer to the description of the 4378*-gnatw.u* switch in the GNAT User's Guide. 4379 4380Pragma Overflow_Mode 4381==================== 4382 4383Syntax: 4384 4385 4386:: 4387 4388 pragma Overflow_Mode 4389 ( [General =>] MODE 4390 [,[Assertions =>] MODE]); 4391 4392 MODE ::= STRICT | MINIMIZED | ELIMINATED 4393 4394 4395This pragma sets the current overflow mode to the given setting. For details 4396of the meaning of these modes, please refer to the 4397'Overflow Check Handling in GNAT' appendix in the 4398GNAT User's Guide. If only the ``General`` parameter is present, 4399the given mode applies to all expressions. If both parameters are present, 4400the ``General`` mode applies to expressions outside assertions, and 4401the ``Eliminated`` mode applies to expressions within assertions. 4402 4403The case of the ``MODE`` parameter is ignored, 4404so ``MINIMIZED``, ``Minimized`` and 4405``minimized`` all have the same effect. 4406 4407The ``Overflow_Mode`` pragma has the same scoping and placement 4408rules as pragma ``Suppress``, so it can occur either as a 4409configuration pragma, specifying a default for the whole 4410program, or in a declarative scope, where it applies to the 4411remaining declarations and statements in that scope. 4412 4413The pragma ``Suppress (Overflow_Check)`` suppresses 4414overflow checking, but does not affect the overflow mode. 4415 4416The pragma ``Unsuppress (Overflow_Check)`` unsuppresses (enables) 4417overflow checking, but does not affect the overflow mode. 4418 4419Pragma Overriding_Renamings 4420=========================== 4421.. index:: Rational profile 4422 4423.. index:: Rational compatibility 4424 4425Syntax: 4426 4427 4428.. code-block:: ada 4429 4430 pragma Overriding_Renamings; 4431 4432 4433This is a GNAT configuration pragma to simplify porting 4434legacy code accepted by the Rational 4435Ada compiler. In the presence of this pragma, a renaming declaration that 4436renames an inherited operation declared in the same scope is legal if selected 4437notation is used as in: 4438 4439 4440.. code-block:: ada 4441 4442 pragma Overriding_Renamings; 4443 ... 4444 package R is 4445 function F (..); 4446 ... 4447 function F (..) renames R.F; 4448 end R; 4449 4450 4451even though 4452RM 8.3 (15) stipulates that an overridden operation is not visible within the 4453declaration of the overriding operation. 4454 4455Pragma Partition_Elaboration_Policy 4456=================================== 4457 4458Syntax: 4459 4460 4461:: 4462 4463 pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 4464 4465 POLICY_IDENTIFIER ::= Concurrent | Sequential 4466 4467 4468This pragma is standard in Ada 2005, but is available in all earlier 4469versions of Ada as an implementation-defined pragma. 4470See Ada 2012 Reference Manual for details. 4471 4472.. _Pragma-Part_Of: 4473 4474Pragma Part_Of 4475============== 4476 4477Syntax: 4478 4479.. code-block:: ada 4480 4481 pragma Part_Of (ABSTRACT_STATE); 4482 4483 ABSTRACT_STATE ::= NAME 4484 4485For the semantics of this pragma, see the entry for aspect ``Part_Of`` in the 4486SPARK 2014 Reference Manual, section 7.2.6. 4487 4488Pragma Passive 4489============== 4490 4491Syntax: 4492 4493 4494:: 4495 4496 pragma Passive [(Semaphore | No)]; 4497 4498 4499Syntax checked, but otherwise ignored by GNAT. This is recognized for 4500compatibility with DEC Ada 83 implementations, where it is used within a 4501task definition to request that a task be made passive. If the argument 4502``Semaphore`` is present, or the argument is omitted, then DEC Ada 83 4503treats the pragma as an assertion that the containing task is passive 4504and that optimization of context switch with this task is permitted and 4505desired. If the argument ``No`` is present, the task must not be 4506optimized. GNAT does not attempt to optimize any tasks in this manner 4507(since protected objects are available in place of passive tasks). 4508 4509For more information on the subject of passive tasks, see the section 4510'Passive Task Optimization' in the GNAT Users Guide. 4511 4512.. _Pragma-Persistent_BSS: 4513 4514Pragma Persistent_BSS 4515===================== 4516 4517Syntax: 4518 4519 4520:: 4521 4522 pragma Persistent_BSS [(LOCAL_NAME)] 4523 4524 4525This pragma allows selected objects to be placed in the ``.persistent_bss`` 4526section. On some targets the linker and loader provide for special 4527treatment of this section, allowing a program to be reloaded without 4528affecting the contents of this data (hence the name persistent). 4529 4530There are two forms of usage. If an argument is given, it must be the 4531local name of a library-level object, with no explicit initialization 4532and whose type is potentially persistent. If no argument is given, then 4533the pragma is a configuration pragma, and applies to all library-level 4534objects with no explicit initialization of potentially persistent types. 4535 4536A potentially persistent type is a scalar type, or an untagged, 4537non-discriminated record, all of whose components have no explicit 4538initialization and are themselves of a potentially persistent type, 4539or an array, all of whose constraints are static, and whose component 4540type is potentially persistent. 4541 4542If this pragma is used on a target where this feature is not supported, 4543then the pragma will be ignored. See also ``pragma Linker_Section``. 4544 4545Pragma Post 4546=========== 4547.. index:: Post 4548 4549.. index:: Checks, postconditions 4550 4551 4552Syntax: 4553 4554 4555.. code-block:: ada 4556 4557 pragma Post (Boolean_Expression); 4558 4559 4560The ``Post`` pragma is intended to be an exact replacement for 4561the language-defined 4562``Post`` aspect, and shares its restrictions and semantics. 4563It must appear either immediately following the corresponding 4564subprogram declaration (only other pragmas may intervene), or 4565if there is no separate subprogram declaration, then it can 4566appear at the start of the declarations in a subprogram body 4567(preceded only by other pragmas). 4568 4569Pragma Postcondition 4570==================== 4571.. index:: Postcondition 4572 4573.. index:: Checks, postconditions 4574 4575 4576Syntax: 4577 4578 4579:: 4580 4581 pragma Postcondition ( 4582 [Check =>] Boolean_Expression 4583 [,[Message =>] String_Expression]); 4584 4585 4586The ``Postcondition`` pragma allows specification of automatic 4587postcondition checks for subprograms. These checks are similar to 4588assertions, but are automatically inserted just prior to the return 4589statements of the subprogram with which they are associated (including 4590implicit returns at the end of procedure bodies and associated 4591exception handlers). 4592 4593In addition, the boolean expression which is the condition which 4594must be true may contain references to function'Result in the case 4595of a function to refer to the returned value. 4596 4597``Postcondition`` pragmas may appear either immediately following the 4598(separate) declaration of a subprogram, or at the start of the 4599declarations of a subprogram body. Only other pragmas may intervene 4600(that is appear between the subprogram declaration and its 4601postconditions, or appear before the postcondition in the 4602declaration sequence in a subprogram body). In the case of a 4603postcondition appearing after a subprogram declaration, the 4604formal arguments of the subprogram are visible, and can be 4605referenced in the postcondition expressions. 4606 4607The postconditions are collected and automatically tested just 4608before any return (implicit or explicit) in the subprogram body. 4609A postcondition is only recognized if postconditions are active 4610at the time the pragma is encountered. The compiler switch *gnata* 4611turns on all postconditions by default, and pragma ``Check_Policy`` 4612with an identifier of ``Postcondition`` can also be used to 4613control whether postconditions are active. 4614 4615The general approach is that postconditions are placed in the spec 4616if they represent functional aspects which make sense to the client. 4617For example we might have: 4618 4619 4620.. code-block:: ada 4621 4622 function Direction return Integer; 4623 pragma Postcondition 4624 (Direction'Result = +1 4625 or else 4626 Direction'Result = -1); 4627 4628 4629which serves to document that the result must be +1 or -1, and 4630will test that this is the case at run time if postcondition 4631checking is active. 4632 4633Postconditions within the subprogram body can be used to 4634check that some internal aspect of the implementation, 4635not visible to the client, is operating as expected. 4636For instance if a square root routine keeps an internal 4637counter of the number of times it is called, then we 4638might have the following postcondition: 4639 4640 4641.. code-block:: ada 4642 4643 Sqrt_Calls : Natural := 0; 4644 4645 function Sqrt (Arg : Float) return Float is 4646 pragma Postcondition 4647 (Sqrt_Calls = Sqrt_Calls'Old + 1); 4648 ... 4649 end Sqrt 4650 4651 4652As this example, shows, the use of the ``Old`` attribute 4653is often useful in postconditions to refer to the state on 4654entry to the subprogram. 4655 4656Note that postconditions are only checked on normal returns 4657from the subprogram. If an abnormal return results from 4658raising an exception, then the postconditions are not checked. 4659 4660If a postcondition fails, then the exception 4661``System.Assertions.Assert_Failure`` is raised. If 4662a message argument was supplied, then the given string 4663will be used as the exception message. If no message 4664argument was supplied, then the default message has 4665the form "Postcondition failed at file_name:line". The 4666exception is raised in the context of the subprogram 4667body, so it is possible to catch postcondition failures 4668within the subprogram body itself. 4669 4670Within a package spec, normal visibility rules 4671in Ada would prevent forward references within a 4672postcondition pragma to functions defined later in 4673the same package. This would introduce undesirable 4674ordering constraints. To avoid this problem, all 4675postcondition pragmas are analyzed at the end of 4676the package spec, allowing forward references. 4677 4678The following example shows that this even allows 4679mutually recursive postconditions as in: 4680 4681 4682.. code-block:: ada 4683 4684 package Parity_Functions is 4685 function Odd (X : Natural) return Boolean; 4686 pragma Postcondition 4687 (Odd'Result = 4688 (x = 1 4689 or else 4690 (x /= 0 and then Even (X - 1)))); 4691 4692 function Even (X : Natural) return Boolean; 4693 pragma Postcondition 4694 (Even'Result = 4695 (x = 0 4696 or else 4697 (x /= 1 and then Odd (X - 1)))); 4698 4699 end Parity_Functions; 4700 4701 4702There are no restrictions on the complexity or form of 4703conditions used within ``Postcondition`` pragmas. 4704The following example shows that it is even possible 4705to verify performance behavior. 4706 4707 4708.. code-block:: ada 4709 4710 package Sort is 4711 4712 Performance : constant Float; 4713 -- Performance constant set by implementation 4714 -- to match target architecture behavior. 4715 4716 procedure Treesort (Arg : String); 4717 -- Sorts characters of argument using N*logN sort 4718 pragma Postcondition 4719 (Float (Clock - Clock'Old) <= 4720 Float (Arg'Length) * 4721 log (Float (Arg'Length)) * 4722 Performance); 4723 end Sort; 4724 4725 4726Note: postcondition pragmas associated with subprograms that are 4727marked as Inline_Always, or those marked as Inline with front-end 4728inlining (-gnatN option set) are accepted and legality-checked 4729by the compiler, but are ignored at run-time even if postcondition 4730checking is enabled. 4731 4732Note that pragma ``Postcondition`` differs from the language-defined 4733``Post`` aspect (and corresponding ``Post`` pragma) in allowing 4734multiple occurrences, allowing occurences in the body even if there 4735is a separate spec, and allowing a second string parameter, and the 4736use of the pragma identifier ``Check``. Historically, pragma 4737``Postcondition`` was implemented prior to the development of 4738Ada 2012, and has been retained in its original form for 4739compatibility purposes. 4740 4741Pragma Post_Class 4742================= 4743.. index:: Post 4744 4745.. index:: Checks, postconditions 4746 4747 4748Syntax: 4749 4750 4751.. code-block:: ada 4752 4753 pragma Post_Class (Boolean_Expression); 4754 4755 4756The ``Post_Class`` pragma is intended to be an exact replacement for 4757the language-defined 4758``Post'Class`` aspect, and shares its restrictions and semantics. 4759It must appear either immediately following the corresponding 4760subprogram declaration (only other pragmas may intervene), or 4761if there is no separate subprogram declaration, then it can 4762appear at the start of the declarations in a subprogram body 4763(preceded only by other pragmas). 4764 4765Note: This pragma is called ``Post_Class`` rather than 4766``Post'Class`` because the latter would not be strictly 4767conforming to the allowed syntax for pragmas. The motivation 4768for provinding pragmas equivalent to the aspects is to allow a program 4769to be written using the pragmas, and then compiled if necessary 4770using an Ada compiler that does not recognize the pragmas or 4771aspects, but is prepared to ignore the pragmas. The assertion 4772policy that controls this pragma is ``Post'Class``, not 4773``Post_Class``. 4774 4775Pragma Rename_Pragma 4776============================ 4777.. index:: Pragmas, synonyms 4778 4779Syntax: 4780 4781 4782:: 4783 4784 pragma Rename_Pragma ( 4785 [New_Name =>] IDENTIFIER, 4786 [Renamed =>] pragma_IDENTIFIER); 4787 4788This pragma provides a mechanism for supplying new names for existing 4789pragmas. The ``New_Name`` identifier can subsequently be used as a synonym for 4790the Renamed pragma. For example, suppose you have code that was originally 4791developed on a compiler that supports Inline_Only as an implementation defined 4792pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 4793least very similar to) the GNAT implementation defined pragma 4794Inline_Always. You could globally replace Inline_Only with Inline_Always. 4795 4796However, to avoid that source modification, you could instead add a 4797configuration pragma: 4798 4799.. code-block:: ada 4800 4801 pragma Rename_Pragma ( 4802 New_Name => Inline_Only, 4803 Renamed => Inline_Always); 4804 4805 4806Then GNAT will treat "pragma Inline_Only ..." as if you had written 4807"pragma Inline_Always ...". 4808 4809Pragma Inline_Only will not necessarily mean the same thing as the other Ada 4810compiler; it's up to you to make sure the semantics are close enough. 4811 4812Pragma Pre 4813========== 4814.. index:: Pre 4815 4816.. index:: Checks, preconditions 4817 4818 4819Syntax: 4820 4821 4822.. code-block:: ada 4823 4824 pragma Pre (Boolean_Expression); 4825 4826 4827The ``Pre`` pragma is intended to be an exact replacement for 4828the language-defined 4829``Pre`` aspect, and shares its restrictions and semantics. 4830It must appear either immediately following the corresponding 4831subprogram declaration (only other pragmas may intervene), or 4832if there is no separate subprogram declaration, then it can 4833appear at the start of the declarations in a subprogram body 4834(preceded only by other pragmas). 4835 4836Pragma Precondition 4837=================== 4838.. index:: Preconditions 4839 4840.. index:: Checks, preconditions 4841 4842 4843Syntax: 4844 4845 4846:: 4847 4848 pragma Precondition ( 4849 [Check =>] Boolean_Expression 4850 [,[Message =>] String_Expression]); 4851 4852 4853The ``Precondition`` pragma is similar to ``Postcondition`` 4854except that the corresponding checks take place immediately upon 4855entry to the subprogram, and if a precondition fails, the exception 4856is raised in the context of the caller, and the attribute 'Result 4857cannot be used within the precondition expression. 4858 4859Otherwise, the placement and visibility rules are identical to those 4860described for postconditions. The following is an example of use 4861within a package spec: 4862 4863 4864.. code-block:: ada 4865 4866 package Math_Functions is 4867 ... 4868 function Sqrt (Arg : Float) return Float; 4869 pragma Precondition (Arg >= 0.0) 4870 ... 4871 end Math_Functions; 4872 4873 4874``Precondition`` pragmas may appear either immediately following the 4875(separate) declaration of a subprogram, or at the start of the 4876declarations of a subprogram body. Only other pragmas may intervene 4877(that is appear between the subprogram declaration and its 4878postconditions, or appear before the postcondition in the 4879declaration sequence in a subprogram body). 4880 4881Note: precondition pragmas associated with subprograms that are 4882marked as Inline_Always, or those marked as Inline with front-end 4883inlining (-gnatN option set) are accepted and legality-checked 4884by the compiler, but are ignored at run-time even if precondition 4885checking is enabled. 4886 4887Note that pragma ``Precondition`` differs from the language-defined 4888``Pre`` aspect (and corresponding ``Pre`` pragma) in allowing 4889multiple occurrences, allowing occurences in the body even if there 4890is a separate spec, and allowing a second string parameter, and the 4891use of the pragma identifier ``Check``. Historically, pragma 4892``Precondition`` was implemented prior to the development of 4893Ada 2012, and has been retained in its original form for 4894compatibility purposes. 4895 4896.. _Pragma-Predicate: 4897 4898Pragma Predicate 4899================ 4900 4901Syntax: 4902 4903 4904:: 4905 4906 pragma Predicate 4907 ([Entity =>] type_LOCAL_NAME, 4908 [Check =>] EXPRESSION); 4909 4910 4911This pragma (available in all versions of Ada in GNAT) encompasses both 4912the ``Static_Predicate`` and ``Dynamic_Predicate`` aspects in 4913Ada 2012. A predicate is regarded as static if it has an allowed form 4914for ``Static_Predicate`` and is otherwise treated as a 4915``Dynamic_Predicate``. Otherwise, predicates specified by this 4916pragma behave exactly as described in the Ada 2012 reference manual. 4917For example, if we have 4918 4919 4920.. code-block:: ada 4921 4922 type R is range 1 .. 10; 4923 subtype S is R; 4924 pragma Predicate (Entity => S, Check => S not in 4 .. 6); 4925 subtype Q is R 4926 pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 4927 4928 4929the effect is identical to the following Ada 2012 code: 4930 4931 4932.. code-block:: ada 4933 4934 type R is range 1 .. 10; 4935 subtype S is R with 4936 Static_Predicate => S not in 4 .. 6; 4937 subtype Q is R with 4938 Dynamic_Predicate => F(Q) or G(Q); 4939 4940 4941Note that there are no pragmas ``Dynamic_Predicate`` 4942or ``Static_Predicate``. That is 4943because these pragmas would affect legality and semantics of 4944the program and thus do not have a neutral effect if ignored. 4945The motivation behind providing pragmas equivalent to 4946corresponding aspects is to allow a program to be written 4947using the pragmas, and then compiled with a compiler that 4948will ignore the pragmas. That doesn't work in the case of 4949static and dynamic predicates, since if the corresponding 4950pragmas are ignored, then the behavior of the program is 4951fundamentally changed (for example a membership test 4952``A in B`` would not take into account a predicate 4953defined for subtype B). When following this approach, the 4954use of predicates should be avoided. 4955 4956Pragma Predicate_Failure 4957======================== 4958 4959Syntax: 4960 4961 4962:: 4963 4964 pragma Predicate_Failure 4965 ([Entity =>] type_LOCAL_NAME, 4966 [Message =>] String_Expression); 4967 4968 4969The ``Predicate_Failure`` pragma is intended to be an exact replacement for 4970the language-defined 4971``Predicate_Failure`` aspect, and shares its restrictions and semantics. 4972 4973Pragma Preelaborable_Initialization 4974=================================== 4975 4976Syntax: 4977 4978 4979.. code-block:: ada 4980 4981 pragma Preelaborable_Initialization (DIRECT_NAME); 4982 4983 4984This pragma is standard in Ada 2005, but is available in all earlier 4985versions of Ada as an implementation-defined pragma. 4986See Ada 2012 Reference Manual for details. 4987 4988Pragma Prefix_Exception_Messages 4989================================ 4990.. index:: Prefix_Exception_Messages 4991 4992.. index:: exception 4993 4994.. index:: Exception_Message 4995 4996 4997Syntax: 4998 4999 5000.. code-block:: ada 5001 5002 pragma Prefix_Exception_Messages; 5003 5004 5005This is an implementation-defined configuration pragma that affects the 5006behavior of raise statements with a message given as a static string 5007constant (typically a string literal). In such cases, the string will 5008be automatically prefixed by the name of the enclosing entity (giving 5009the package and subprogram containing the raise statement). This helps 5010to identify where messages are coming from, and this mode is automatic 5011for the run-time library. 5012 5013The pragma has no effect if the message is computed with an expression other 5014than a static string constant, since the assumption in this case is that 5015the program computes exactly the string it wants. If you still want the 5016prefixing in this case, you can always call 5017``GNAT.Source_Info.Enclosing_Entity`` and prepend the string manually. 5018 5019Pragma Pre_Class 5020================ 5021.. index:: Pre_Class 5022 5023.. index:: Checks, preconditions 5024 5025 5026Syntax: 5027 5028 5029.. code-block:: ada 5030 5031 pragma Pre_Class (Boolean_Expression); 5032 5033 5034The ``Pre_Class`` pragma is intended to be an exact replacement for 5035the language-defined 5036``Pre'Class`` aspect, and shares its restrictions and semantics. 5037It must appear either immediately following the corresponding 5038subprogram declaration (only other pragmas may intervene), or 5039if there is no separate subprogram declaration, then it can 5040appear at the start of the declarations in a subprogram body 5041(preceded only by other pragmas). 5042 5043Note: This pragma is called ``Pre_Class`` rather than 5044``Pre'Class`` because the latter would not be strictly 5045conforming to the allowed syntax for pragmas. The motivation 5046for providing pragmas equivalent to the aspects is to allow a program 5047to be written using the pragmas, and then compiled if necessary 5048using an Ada compiler that does not recognize the pragmas or 5049aspects, but is prepared to ignore the pragmas. The assertion 5050policy that controls this pragma is ``Pre'Class``, not 5051``Pre_Class``. 5052 5053Pragma Priority_Specific_Dispatching 5054==================================== 5055 5056Syntax: 5057 5058 5059:: 5060 5061 pragma Priority_Specific_Dispatching ( 5062 POLICY_IDENTIFIER, 5063 first_priority_EXPRESSION, 5064 last_priority_EXPRESSION) 5065 5066 POLICY_IDENTIFIER ::= 5067 EDF_Across_Priorities | 5068 FIFO_Within_Priorities | 5069 Non_Preemptive_Within_Priorities | 5070 Round_Robin_Within_Priorities 5071 5072 5073This pragma is standard in Ada 2005, but is available in all earlier 5074versions of Ada as an implementation-defined pragma. 5075See Ada 2012 Reference Manual for details. 5076 5077Pragma Profile 5078============== 5079 5080Syntax: 5081 5082 5083.. code-block:: ada 5084 5085 pragma Profile (Ravenscar | Restricted | Rational | Jorvik | 5086 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 5087 5088 5089This pragma is standard in Ada 2005, but is available in all earlier 5090versions of Ada as an implementation-defined pragma. This is a 5091configuration pragma that establishes a set of configuration pragmas 5092that depend on the argument. ``Ravenscar`` is standard in Ada 2005. 5093``Jorvik`` is standard in Ada 202x. 5094The other possibilities (``Restricted``, ``Rational``, 5095``GNAT_Extended_Ravenscar``, ``GNAT_Ravenscar_EDF``) 5096are implementation-defined. ``GNAT_Extended_Ravenscar`` is an alias for ``Jorvik``. 5097 5098The set of configuration pragmas is defined in the following sections. 5099 5100 5101* Pragma Profile (Ravenscar) 5102 5103 The ``Ravenscar`` profile is standard in Ada 2005, 5104 but is available in all earlier 5105 versions of Ada as an implementation-defined pragma. This profile 5106 establishes the following set of configuration pragmas: 5107 5108 * ``Task_Dispatching_Policy (FIFO_Within_Priorities)`` 5109 5110 [RM D.2.2] Tasks are dispatched following a preemptive 5111 priority-ordered scheduling policy. 5112 5113 5114 * ``Locking_Policy (Ceiling_Locking)`` 5115 5116 [RM D.3] While tasks and interrupts execute a protected action, they inherit 5117 the ceiling priority of the corresponding protected object. 5118 5119 5120 * ``Detect_Blocking`` 5121 5122 This pragma forces the detection of potentially blocking operations within a 5123 protected operation, and to raise Program_Error if that happens. 5124 5125 plus the following set of restrictions: 5126 5127 * ``Max_Entry_Queue_Length => 1`` 5128 5129 No task can be queued on a protected entry. 5130 5131 * ``Max_Protected_Entries => 1`` 5132 5133 * ``Max_Task_Entries => 0`` 5134 5135 No rendezvous statements are allowed. 5136 5137 * ``No_Abort_Statements`` 5138 5139 * ``No_Dynamic_Attachment`` 5140 5141 * ``No_Dynamic_Priorities`` 5142 5143 * ``No_Implicit_Heap_Allocations`` 5144 5145 * ``No_Local_Protected_Objects`` 5146 5147 * ``No_Local_Timing_Events`` 5148 5149 * ``No_Protected_Type_Allocators`` 5150 5151 * ``No_Relative_Delay`` 5152 5153 * ``No_Requeue_Statements`` 5154 5155 * ``No_Select_Statements`` 5156 5157 * ``No_Specific_Termination_Handlers`` 5158 5159 * ``No_Task_Allocators`` 5160 5161 * ``No_Task_Hierarchy`` 5162 5163 * ``No_Task_Termination`` 5164 5165 * ``Simple_Barriers`` 5166 5167 The Ravenscar profile also includes the following restrictions that specify 5168 that there are no semantic dependencies on the corresponding predefined 5169 packages: 5170 5171 * ``No_Dependence => Ada.Asynchronous_Task_Control`` 5172 5173 * ``No_Dependence => Ada.Calendar`` 5174 5175 * ``No_Dependence => Ada.Execution_Time.Group_Budget`` 5176 5177 * ``No_Dependence => Ada.Execution_Time.Timers`` 5178 5179 * ``No_Dependence => Ada.Task_Attributes`` 5180 5181 * ``No_Dependence => System.Multiprocessors.Dispatching_Domains`` 5182 5183 This set of configuration pragmas and restrictions correspond to the 5184 definition of the 'Ravenscar Profile' for limited tasking, devised and 5185 published by the :title:`International Real-Time Ada Workshop, 1997`. 5186 A description is also available at 5187 `http://www-users.cs.york.ac.uk/~burns/ravenscar.ps <http://www-users.cs.york.ac.uk/~burns/ravenscar.ps>`_. 5188 5189 The original definition of the profile was revised at subsequent IRTAW 5190 meetings. It has been included in the ISO 5191 :title:`Guide for the Use of the Ada Programming Language in High Integrity Systems`, 5192 and was made part of the Ada 2005 standard. 5193 The formal definition given by 5194 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 5195 AI-305) available at 5196 `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt>`_ and 5197 `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt>`_. 5198 5199 The above set is a superset of the restrictions provided by pragma 5200 ``Profile (Restricted)``, it includes six additional restrictions 5201 (``Simple_Barriers``, ``No_Select_Statements``, 5202 ``No_Calendar``, ``No_Implicit_Heap_Allocations``, 5203 ``No_Relative_Delay`` and ``No_Task_Termination``). This means 5204 that pragma ``Profile (Ravenscar)``, like the pragma 5205 ``Profile (Restricted)``, 5206 automatically causes the use of a simplified, 5207 more efficient version of the tasking run-time library. 5208 5209* Pragma Profile (Jorvik) 5210 5211 ``Jorvik`` is the new profile added to the Ada 202x draft standard, 5212 previously implemented under the name ``GNAT_Extended_Ravenscar``. 5213 5214 The ``No_Implicit_Heap_Allocations`` restriction has been replaced 5215 by ``No_Implicit_Task_Allocations`` and 5216 ``No_Implicit_Protected_Object_Allocations``. 5217 5218 The ``Simple_Barriers`` restriction has been replaced by 5219 ``Pure_Barriers``. 5220 5221 The ``Max_Protected_Entries``, ``Max_Entry_Queue_Length``, and 5222 ``No_Relative_Delay`` restrictions have been removed. 5223 5224 Details on the rationale for ``Jorvik`` and implications for use may be 5225 found in :title:`A New Ravenscar-Based Profile` by P. Rogers, J. Ruiz, 5226 T. Gingold and P. Bernardi, in :title:`Reliable Software Technologies -- 5227 Ada Europe 2017`, Springer-Verlag Lecture Notes in Computer Science, 5228 Number 10300. 5229 5230 5231* Pragma Profile (GNAT_Ravenscar_EDF) 5232 5233 This profile corresponds to the Ravenscar profile but using 5234 EDF_Across_Priority as the Task_Scheduling_Policy. 5235 5236* Pragma Profile (Restricted) 5237 5238 This profile corresponds to the GNAT restricted run time. It 5239 establishes the following set of restrictions: 5240 5241 * ``No_Abort_Statements`` 5242 * ``No_Entry_Queue`` 5243 * ``No_Task_Hierarchy`` 5244 * ``No_Task_Allocators`` 5245 * ``No_Dynamic_Priorities`` 5246 * ``No_Terminate_Alternatives`` 5247 * ``No_Dynamic_Attachment`` 5248 * ``No_Protected_Type_Allocators`` 5249 * ``No_Local_Protected_Objects`` 5250 * ``No_Requeue_Statements`` 5251 * ``No_Task_Attributes_Package`` 5252 * ``Max_Asynchronous_Select_Nesting = 0`` 5253 * ``Max_Task_Entries = 0`` 5254 * ``Max_Protected_Entries = 1`` 5255 * ``Max_Select_Alternatives = 0`` 5256 5257 This set of restrictions causes the automatic selection of a simplified 5258 version of the run time that provides improved performance for the 5259 limited set of tasking functionality permitted by this set of restrictions. 5260 5261* Pragma Profile (Rational) 5262 5263 The Rational profile is intended to facilitate porting legacy code that 5264 compiles with the Rational APEX compiler, even when the code includes non- 5265 conforming Ada constructs. The profile enables the following three pragmas: 5266 5267 * ``pragma Implicit_Packing`` 5268 * ``pragma Overriding_Renamings`` 5269 * ``pragma Use_VADS_Size`` 5270 5271 5272Pragma Profile_Warnings 5273======================= 5274 5275Syntax: 5276 5277 5278.. code-block:: ada 5279 5280 pragma Profile_Warnings (Ravenscar | Restricted | Rational); 5281 5282 5283This is an implementation-defined pragma that is similar in 5284effect to ``pragma Profile`` except that instead of 5285generating ``Restrictions`` pragmas, it generates 5286``Restriction_Warnings`` pragmas. The result is that 5287violations of the profile generate warning messages instead 5288of error messages. 5289 5290Pragma Propagate_Exceptions 5291=========================== 5292.. index:: Interfacing to C++ 5293 5294 5295Syntax: 5296 5297 5298.. code-block:: ada 5299 5300 pragma Propagate_Exceptions; 5301 5302 5303This pragma is now obsolete and, other than generating a warning if warnings 5304on obsolescent features are enabled, is ignored. 5305It is retained for compatibility 5306purposes. It used to be used in connection with optimization of 5307a now-obsolete mechanism for implementation of exceptions. 5308 5309Pragma Provide_Shift_Operators 5310============================== 5311.. index:: Shift operators 5312 5313 5314Syntax: 5315 5316 5317.. code-block:: ada 5318 5319 pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 5320 5321 5322This pragma can be applied to a first subtype local name that specifies 5323either an unsigned or signed type. It has the effect of providing the 5324five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 5325Rotate_Left and Rotate_Right) for the given type. It is similar to 5326including the function declarations for these five operators, together 5327with the pragma Import (Intrinsic, ...) statements. 5328 5329Pragma Psect_Object 5330=================== 5331 5332Syntax: 5333 5334 5335:: 5336 5337 pragma Psect_Object ( 5338 [Internal =>] LOCAL_NAME, 5339 [, [External =>] EXTERNAL_SYMBOL] 5340 [, [Size =>] EXTERNAL_SYMBOL]); 5341 5342 EXTERNAL_SYMBOL ::= 5343 IDENTIFIER 5344 | static_string_EXPRESSION 5345 5346 5347This pragma is identical in effect to pragma ``Common_Object``. 5348 5349.. _Pragma-Pure_Function: 5350 5351Pragma Pure_Function 5352==================== 5353 5354Syntax: 5355 5356 5357:: 5358 5359 pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 5360 5361 5362This pragma appears in the same declarative part as a function 5363declaration (or a set of function declarations if more than one 5364overloaded declaration exists, in which case the pragma applies 5365to all entities). It specifies that the function ``Entity`` is 5366to be considered pure for the purposes of code generation. This means 5367that the compiler can assume that there are no side effects, and 5368in particular that two calls with identical arguments produce the 5369same result. It also means that the function can be used in an 5370address clause. 5371 5372Note that, quite deliberately, there are no static checks to try 5373to ensure that this promise is met, so ``Pure_Function`` can be used 5374with functions that are conceptually pure, even if they do modify 5375global variables. For example, a square root function that is 5376instrumented to count the number of times it is called is still 5377conceptually pure, and can still be optimized, even though it 5378modifies a global variable (the count). Memo functions are another 5379example (where a table of previous calls is kept and consulted to 5380avoid re-computation). 5381 5382Note also that the normal rules excluding optimization of subprograms 5383in pure units (when parameter types are descended from System.Address, 5384or when the full view of a parameter type is limited), do not apply 5385for the Pure_Function case. If you explicitly specify Pure_Function, 5386the compiler may optimize away calls with identical arguments, and 5387if that results in unexpected behavior, the proper action is not to 5388use the pragma for subprograms that are not (conceptually) pure. 5389 5390Note: Most functions in a ``Pure`` package are automatically pure, and 5391there is no need to use pragma ``Pure_Function`` for such functions. One 5392exception is any function that has at least one formal of type 5393``System.Address`` or a type derived from it. Such functions are not 5394considered pure by default, since the compiler assumes that the 5395``Address`` parameter may be functioning as a pointer and that the 5396referenced data may change even if the address value does not. 5397Similarly, imported functions are not considered to be pure by default, 5398since there is no way of checking that they are in fact pure. The use 5399of pragma ``Pure_Function`` for such a function will override these default 5400assumption, and cause the compiler to treat a designated subprogram as pure 5401in these cases. 5402 5403Note: If pragma ``Pure_Function`` is applied to a renamed function, it 5404applies to the underlying renamed function. This can be used to 5405disambiguate cases of overloading where some but not all functions 5406in a set of overloaded functions are to be designated as pure. 5407 5408If pragma ``Pure_Function`` is applied to a library-level function, the 5409function is also considered pure from an optimization point of view, but the 5410unit is not a Pure unit in the categorization sense. So for example, a function 5411thus marked is free to ``with`` non-pure units. 5412 5413Pragma Rational 5414=============== 5415 5416Syntax: 5417 5418 5419.. code-block:: ada 5420 5421 pragma Rational; 5422 5423 5424This pragma is considered obsolescent, but is retained for 5425compatibility purposes. It is equivalent to: 5426 5427 5428.. code-block:: ada 5429 5430 pragma Profile (Rational); 5431 5432 5433Pragma Ravenscar 5434================ 5435 5436Syntax: 5437 5438 5439.. code-block:: ada 5440 5441 pragma Ravenscar; 5442 5443 5444This pragma is considered obsolescent, but is retained for 5445compatibility purposes. It is equivalent to: 5446 5447 5448.. code-block:: ada 5449 5450 pragma Profile (Ravenscar); 5451 5452 5453which is the preferred method of setting the ``Ravenscar`` profile. 5454 5455.. _Pragma-Refined_Depends: 5456 5457Pragma Refined_Depends 5458====================== 5459 5460Syntax: 5461 5462.. code-block:: ada 5463 5464 pragma Refined_Depends (DEPENDENCY_RELATION); 5465 5466 DEPENDENCY_RELATION ::= 5467 null 5468 | (DEPENDENCY_CLAUSE {, DEPENDENCY_CLAUSE}) 5469 5470 DEPENDENCY_CLAUSE ::= 5471 OUTPUT_LIST =>[+] INPUT_LIST 5472 | NULL_DEPENDENCY_CLAUSE 5473 5474 NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 5475 5476 OUTPUT_LIST ::= OUTPUT | (OUTPUT {, OUTPUT}) 5477 5478 INPUT_LIST ::= null | INPUT | (INPUT {, INPUT}) 5479 5480 OUTPUT ::= NAME | FUNCTION_RESULT 5481 INPUT ::= NAME 5482 5483 where FUNCTION_RESULT is a function Result attribute_reference 5484 5485For the semantics of this pragma, see the entry for aspect ``Refined_Depends`` in 5486the SPARK 2014 Reference Manual, section 6.1.5. 5487 5488.. _Pragma-Refined_Global: 5489 5490Pragma Refined_Global 5491===================== 5492 5493Syntax: 5494 5495.. code-block:: ada 5496 5497 pragma Refined_Global (GLOBAL_SPECIFICATION); 5498 5499 GLOBAL_SPECIFICATION ::= 5500 null 5501 | (GLOBAL_LIST) 5502 | (MODED_GLOBAL_LIST {, MODED_GLOBAL_LIST}) 5503 5504 MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 5505 5506 MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 5507 GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM}) 5508 GLOBAL_ITEM ::= NAME 5509 5510For the semantics of this pragma, see the entry for aspect ``Refined_Global`` in 5511the SPARK 2014 Reference Manual, section 6.1.4. 5512 5513.. _Pragma-Refined_Post: 5514 5515Pragma Refined_Post 5516=================== 5517 5518Syntax: 5519 5520.. code-block:: ada 5521 5522 pragma Refined_Post (boolean_EXPRESSION); 5523 5524For the semantics of this pragma, see the entry for aspect ``Refined_Post`` in 5525the SPARK 2014 Reference Manual, section 7.2.7. 5526 5527.. _Pragma-Refined_State: 5528 5529Pragma Refined_State 5530==================== 5531 5532Syntax: 5533 5534.. code-block:: ada 5535 5536 pragma Refined_State (REFINEMENT_LIST); 5537 5538 REFINEMENT_LIST ::= 5539 (REFINEMENT_CLAUSE {, REFINEMENT_CLAUSE}) 5540 5541 REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 5542 5543 CONSTITUENT_LIST ::= 5544 null 5545 | CONSTITUENT 5546 | (CONSTITUENT {, CONSTITUENT}) 5547 5548 CONSTITUENT ::= object_NAME | state_NAME 5549 5550For the semantics of this pragma, see the entry for aspect ``Refined_State`` in 5551the SPARK 2014 Reference Manual, section 7.2.2. 5552 5553Pragma Relative_Deadline 5554======================== 5555 5556Syntax: 5557 5558 5559.. code-block:: ada 5560 5561 pragma Relative_Deadline (time_span_EXPRESSION); 5562 5563 5564This pragma is standard in Ada 2005, but is available in all earlier 5565versions of Ada as an implementation-defined pragma. 5566See Ada 2012 Reference Manual for details. 5567 5568.. _Pragma-Remote_Access_Type: 5569 5570Pragma Remote_Access_Type 5571========================= 5572 5573Syntax: 5574 5575 5576:: 5577 5578 pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 5579 5580 5581This pragma appears in the formal part of a generic declaration. 5582It specifies an exception to the RM rule from E.2.2(17/2), which forbids 5583the use of a remote access to class-wide type as actual for a formal 5584access type. 5585 5586When this pragma applies to a formal access type ``Entity``, that 5587type is treated as a remote access to class-wide type in the generic. 5588It must be a formal general access type, and its designated type must 5589be the class-wide type of a formal tagged limited private type from the 5590same generic declaration. 5591 5592In the generic unit, the formal type is subject to all restrictions 5593pertaining to remote access to class-wide types. At instantiation, the 5594actual type must be a remote access to class-wide type. 5595 5596Pragma Restricted_Run_Time 5597========================== 5598 5599Syntax: 5600 5601 5602.. code-block:: ada 5603 5604 pragma Restricted_Run_Time; 5605 5606 5607This pragma is considered obsolescent, but is retained for 5608compatibility purposes. It is equivalent to: 5609 5610 5611.. code-block:: ada 5612 5613 pragma Profile (Restricted); 5614 5615 5616which is the preferred method of setting the restricted run time 5617profile. 5618 5619Pragma Restriction_Warnings 5620=========================== 5621 5622Syntax: 5623 5624 5625:: 5626 5627 pragma Restriction_Warnings 5628 (restriction_IDENTIFIER {, restriction_IDENTIFIER}); 5629 5630 5631This pragma allows a series of restriction identifiers to be 5632specified (the list of allowed identifiers is the same as for 5633pragma ``Restrictions``). For each of these identifiers 5634the compiler checks for violations of the restriction, but 5635generates a warning message rather than an error message 5636if the restriction is violated. 5637 5638One use of this is in situations where you want to know 5639about violations of a restriction, but you want to ignore some of 5640these violations. Consider this example, where you want to set 5641Ada_95 mode and enable style checks, but you want to know about 5642any other use of implementation pragmas: 5643 5644 5645.. code-block:: ada 5646 5647 pragma Restriction_Warnings (No_Implementation_Pragmas); 5648 pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 5649 pragma Ada_95; 5650 pragma Style_Checks ("2bfhkM160"); 5651 pragma Warnings (On, "violation of No_Implementation_Pragmas"); 5652 5653 5654By including the above lines in a configuration pragmas file, 5655the Ada_95 and Style_Checks pragmas are accepted without 5656generating a warning, but any other use of implementation 5657defined pragmas will cause a warning to be generated. 5658 5659Pragma Reviewable 5660================= 5661 5662Syntax: 5663 5664 5665.. code-block:: ada 5666 5667 pragma Reviewable; 5668 5669 5670This pragma is an RM-defined standard pragma, but has no effect on the 5671program being compiled, or on the code generated for the program. 5672 5673To obtain the required output specified in RM H.3.1, the compiler must be 5674run with various special switches as follows: 5675 5676* *Where compiler-generated run-time checks remain* 5677 5678 The switch *-gnatGL* 5679 may be used to list the expanded code in pseudo-Ada form. 5680 Runtime checks show up in the listing either as explicit 5681 checks or operators marked with {} to indicate a check is present. 5682 5683 5684* *An identification of known exceptions at compile time* 5685 5686 If the program is compiled with *-gnatwa*, 5687 the compiler warning messages will indicate all cases where the compiler 5688 detects that an exception is certain to occur at run time. 5689 5690 5691* *Possible reads of uninitialized variables* 5692 5693 The compiler warns of many such cases, but its output is incomplete. 5694 5695.. only:: PRO or GPL 5696 5697 The CodePeer analysis tool 5698 may be used to obtain a comprehensive list of all 5699 possible points at which uninitialized data may be read. 5700 5701.. only:: FSF 5702 5703 A supplemental static analysis tool 5704 may be used to obtain a comprehensive list of all 5705 possible points at which uninitialized data may be read. 5706 5707 5708* *Where run-time support routines are implicitly invoked* 5709 5710 In the output from *-gnatGL*, 5711 run-time calls are explicitly listed as calls to the relevant 5712 run-time routine. 5713 5714 5715* *Object code listing* 5716 5717 This may be obtained either by using the *-S* switch, 5718 or the objdump utility. 5719 5720 5721* *Constructs known to be erroneous at compile time* 5722 5723 These are identified by warnings issued by the compiler (use *-gnatwa*). 5724 5725 5726* *Stack usage information* 5727 5728 Static stack usage data (maximum per-subprogram) can be obtained via the 5729 *-fstack-usage* switch to the compiler. 5730 Dynamic stack usage data (per task) can be obtained via the *-u* switch 5731 to gnatbind 5732 5733.. only:: PRO or GPL 5734 5735 The gnatstack utility 5736 can be used to provide additional information on stack usage. 5737 5738 5739* *Object code listing of entire partition* 5740 5741 This can be obtained by compiling the partition with *-S*, 5742 or by applying objdump 5743 to all the object files that are part of the partition. 5744 5745 5746* *A description of the run-time model* 5747 5748 The full sources of the run-time are available, and the documentation of 5749 these routines describes how these run-time routines interface to the 5750 underlying operating system facilities. 5751 5752 5753* *Control and data-flow information* 5754 5755.. only:: PRO or GPL 5756 5757 The CodePeer tool 5758 may be used to obtain complete control and data-flow information, as well as 5759 comprehensive messages identifying possible problems based on this 5760 information. 5761 5762.. only:: FSF 5763 5764 A supplemental static analysis tool 5765 may be used to obtain complete control and data-flow information, as well as 5766 comprehensive messages identifying possible problems based on this 5767 information. 5768 5769.. _Pragma-Secondary_Stack_Size: 5770 5771Pragma Secondary_Stack_Size 5772=========================== 5773 5774Syntax: 5775 5776.. code-block:: ada 5777 5778 pragma Secondary_Stack_Size (integer_EXPRESSION); 5779 5780This pragma appears within the task definition of a single task declaration 5781or a task type declaration (like pragma ``Storage_Size``) and applies to all 5782task objects of that type. The argument specifies the size of the secondary 5783stack to be used by these task objects, and must be of an integer type. The 5784secondary stack is used to handle functions that return a variable-sized 5785result, for example a function returning an unconstrained String. 5786 5787Note this pragma only applies to targets using fixed secondary stacks, like 5788VxWorks 653 and bare board targets, where a fixed block for the 5789secondary stack is allocated from the primary stack of the task. By default, 5790these targets assign a percentage of the primary stack for the secondary stack, 5791as defined by ``System.Parameter.Sec_Stack_Percentage``. With this pragma, 5792an ``integer_EXPRESSION`` of bytes is assigned from the primary stack instead. 5793 5794For most targets, the pragma does not apply as the secondary stack grows on 5795demand: allocated as a chain of blocks in the heap. The default size of these 5796blocks can be modified via the :switch:`-D` binder option as described in 5797:title:`GNAT User's Guide`. 5798 5799Note that no check is made to see if the secondary stack can fit inside the 5800primary stack. 5801 5802Note the pragma cannot appear when the restriction ``No_Secondary_Stack`` 5803is in effect. 5804 5805Pragma Share_Generic 5806==================== 5807 5808Syntax: 5809 5810 5811:: 5812 5813 pragma Share_Generic (GNAME {, GNAME}); 5814 5815 GNAME ::= generic_unit_NAME | generic_instance_NAME 5816 5817 5818This pragma is provided for compatibility with Dec Ada 83. It has 5819no effect in GNAT (which does not implement shared generics), other 5820than to check that the given names are all names of generic units or 5821generic instances. 5822 5823.. _Pragma-Shared: 5824 5825Pragma Shared 5826============= 5827 5828This pragma is provided for compatibility with Ada 83. The syntax and 5829semantics are identical to pragma Atomic. 5830 5831Pragma Short_Circuit_And_Or 5832=========================== 5833 5834Syntax: 5835 5836 5837.. code-block:: ada 5838 5839 pragma Short_Circuit_And_Or; 5840 5841 5842This configuration pragma causes any occurrence of the AND operator applied to 5843operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 5844is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 5845may be useful in the context of certification protocols requiring the use of 5846short-circuited logical operators. If this configuration pragma occurs locally 5847within the file being compiled, it applies only to the file being compiled. 5848There is no requirement that all units in a partition use this option. 5849 5850Pragma Short_Descriptors 5851======================== 5852 5853Syntax: 5854 5855 5856.. code-block:: ada 5857 5858 pragma Short_Descriptors 5859 5860 5861This pragma is provided for compatibility with other Ada implementations. It 5862is recognized but ignored by all current versions of GNAT. 5863 5864.. _Pragma-Simple_Storage_Pool_Type: 5865 5866Pragma Simple_Storage_Pool_Type 5867=============================== 5868.. index:: Storage pool, simple 5869 5870.. index:: Simple storage pool 5871 5872Syntax: 5873 5874 5875.. code-block:: ada 5876 5877 pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 5878 5879 5880A type can be established as a 'simple storage pool type' by applying 5881the representation pragma ``Simple_Storage_Pool_Type`` to the type. 5882A type named in the pragma must be a library-level immutably limited record 5883type or limited tagged type declared immediately within a package declaration. 5884The type can also be a limited private type whose full type is allowed as 5885a simple storage pool type. 5886 5887For a simple storage pool type ``SSP``, nonabstract primitive subprograms 5888``Allocate``, ``Deallocate``, and ``Storage_Size`` can be declared that 5889are subtype conformant with the following subprogram declarations: 5890 5891 5892.. code-block:: ada 5893 5894 procedure Allocate 5895 (Pool : in out SSP; 5896 Storage_Address : out System.Address; 5897 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 5898 Alignment : System.Storage_Elements.Storage_Count); 5899 5900 procedure Deallocate 5901 (Pool : in out SSP; 5902 Storage_Address : System.Address; 5903 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 5904 Alignment : System.Storage_Elements.Storage_Count); 5905 5906 function Storage_Size (Pool : SSP) 5907 return System.Storage_Elements.Storage_Count; 5908 5909 5910Procedure ``Allocate`` must be declared, whereas ``Deallocate`` and 5911``Storage_Size`` are optional. If ``Deallocate`` is not declared, then 5912applying an unchecked deallocation has no effect other than to set its actual 5913parameter to null. If ``Storage_Size`` is not declared, then the 5914``Storage_Size`` attribute applied to an access type associated with 5915a pool object of type SSP returns zero. Additional operations can be declared 5916for a simple storage pool type (such as for supporting a mark/release 5917storage-management discipline). 5918 5919An object of a simple storage pool type can be associated with an access 5920type by specifying the attribute 5921:ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>`. For example: 5922 5923 5924.. code-block:: ada 5925 5926 My_Pool : My_Simple_Storage_Pool_Type; 5927 5928 type Acc is access My_Data_Type; 5929 5930 for Acc'Simple_Storage_Pool use My_Pool; 5931 5932 5933 5934See attribute :ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>` 5935for further details. 5936 5937.. _Pragma_Source_File_Name: 5938 5939Pragma Source_File_Name 5940======================= 5941 5942Syntax: 5943 5944 5945:: 5946 5947 pragma Source_File_Name ( 5948 [Unit_Name =>] unit_NAME, 5949 Spec_File_Name => STRING_LITERAL, 5950 [Index => INTEGER_LITERAL]); 5951 5952 pragma Source_File_Name ( 5953 [Unit_Name =>] unit_NAME, 5954 Body_File_Name => STRING_LITERAL, 5955 [Index => INTEGER_LITERAL]); 5956 5957 5958Use this to override the normal naming convention. It is a configuration 5959pragma, and so has the usual applicability of configuration pragmas 5960(i.e., it applies to either an entire partition, or to all units in a 5961compilation, or to a single unit, depending on how it is used. 5962``unit_name`` is mapped to ``file_name_literal``. The identifier for 5963the second argument is required, and indicates whether this is the file 5964name for the spec or for the body. 5965 5966The optional Index argument should be used when a file contains multiple 5967units, and when you do not want to use ``gnatchop`` to separate then 5968into multiple files (which is the recommended procedure to limit the 5969number of recompilations that are needed when some sources change). 5970For instance, if the source file :file:`source.ada` contains 5971 5972 5973.. code-block:: ada 5974 5975 package B is 5976 ... 5977 end B; 5978 5979 with B; 5980 procedure A is 5981 begin 5982 .. 5983 end A; 5984 5985 5986you could use the following configuration pragmas: 5987 5988 5989.. code-block:: ada 5990 5991 pragma Source_File_Name 5992 (B, Spec_File_Name => "source.ada", Index => 1); 5993 pragma Source_File_Name 5994 (A, Body_File_Name => "source.ada", Index => 2); 5995 5996 5997Note that the ``gnatname`` utility can also be used to generate those 5998configuration pragmas. 5999 6000Another form of the ``Source_File_Name`` pragma allows 6001the specification of patterns defining alternative file naming schemes 6002to apply to all files. 6003 6004 6005:: 6006 6007 pragma Source_File_Name 6008 ( [Spec_File_Name =>] STRING_LITERAL 6009 [,[Casing =>] CASING_SPEC] 6010 [,[Dot_Replacement =>] STRING_LITERAL]); 6011 6012 pragma Source_File_Name 6013 ( [Body_File_Name =>] STRING_LITERAL 6014 [,[Casing =>] CASING_SPEC] 6015 [,[Dot_Replacement =>] STRING_LITERAL]); 6016 6017 pragma Source_File_Name 6018 ( [Subunit_File_Name =>] STRING_LITERAL 6019 [,[Casing =>] CASING_SPEC] 6020 [,[Dot_Replacement =>] STRING_LITERAL]); 6021 6022 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 6023 6024 6025The first argument is a pattern that contains a single asterisk indicating 6026the point at which the unit name is to be inserted in the pattern string 6027to form the file name. The second argument is optional. If present it 6028specifies the casing of the unit name in the resulting file name string. 6029The default is lower case. Finally the third argument allows for systematic 6030replacement of any dots in the unit name by the specified string literal. 6031 6032Note that Source_File_Name pragmas should not be used if you are using 6033project files. The reason for this rule is that the project manager is not 6034aware of these pragmas, and so other tools that use the projet file would not 6035be aware of the intended naming conventions. If you are using project files, 6036file naming is controlled by Source_File_Name_Project pragmas, which are 6037usually supplied automatically by the project manager. A pragma 6038Source_File_Name cannot appear after a :ref:`Pragma_Source_File_Name_Project`. 6039 6040For more details on the use of the ``Source_File_Name`` pragma, see the 6041sections on `Using Other File Names` and `Alternative File Naming Schemes` 6042in the :title:`GNAT User's Guide`. 6043 6044.. _Pragma_Source_File_Name_Project: 6045 6046Pragma Source_File_Name_Project 6047=============================== 6048 6049This pragma has the same syntax and semantics as pragma Source_File_Name. 6050It is only allowed as a stand-alone configuration pragma. 6051It cannot appear after a :ref:`Pragma_Source_File_Name`, and 6052most importantly, once pragma Source_File_Name_Project appears, 6053no further Source_File_Name pragmas are allowed. 6054 6055The intention is that Source_File_Name_Project pragmas are always 6056generated by the Project Manager in a manner consistent with the naming 6057specified in a project file, and when naming is controlled in this manner, 6058it is not permissible to attempt to modify this naming scheme using 6059Source_File_Name or Source_File_Name_Project pragmas (which would not be 6060known to the project manager). 6061 6062Pragma Source_Reference 6063======================= 6064 6065Syntax: 6066 6067 6068.. code-block:: ada 6069 6070 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 6071 6072 6073This pragma must appear as the first line of a source file. 6074``integer_literal`` is the logical line number of the line following 6075the pragma line (for use in error messages and debugging 6076information). ``string_literal`` is a static string constant that 6077specifies the file name to be used in error messages and debugging 6078information. This is most notably used for the output of ``gnatchop`` 6079with the *-r* switch, to make sure that the original unchopped 6080source file is the one referred to. 6081 6082The second argument must be a string literal, it cannot be a static 6083string expression other than a string literal. This is because its value 6084is needed for error messages issued by all phases of the compiler. 6085 6086.. _Pragma-SPARK_Mode: 6087 6088Pragma SPARK_Mode 6089================= 6090 6091Syntax: 6092 6093 6094:: 6095 6096 pragma SPARK_Mode [(On | Off)] ; 6097 6098 6099In general a program can have some parts that are in SPARK 2014 (and 6100follow all the rules in the SPARK Reference Manual), and some parts 6101that are full Ada 2012. 6102 6103The SPARK_Mode pragma is used to identify which parts are in SPARK 61042014 (by default programs are in full Ada). The SPARK_Mode pragma can 6105be used in the following places: 6106 6107 6108* 6109 As a configuration pragma, in which case it sets the default mode for 6110 all units compiled with this pragma. 6111 6112* 6113 Immediately following a library-level subprogram spec 6114 6115* 6116 Immediately within a library-level package body 6117 6118* 6119 Immediately following the ``private`` keyword of a library-level 6120 package spec 6121 6122* 6123 Immediately following the ``begin`` keyword of a library-level 6124 package body 6125 6126* 6127 Immediately within a library-level subprogram body 6128 6129 6130Normally a subprogram or package spec/body inherits the current mode 6131that is active at the point it is declared. But this can be overridden 6132by pragma within the spec or body as above. 6133 6134The basic consistency rule is that you can't turn SPARK_Mode back 6135``On``, once you have explicitly (with a pragma) turned if 6136``Off``. So the following rules apply: 6137 6138If a subprogram spec has SPARK_Mode ``Off``, then the body must 6139also have SPARK_Mode ``Off``. 6140 6141For a package, we have four parts: 6142 6143* 6144 the package public declarations 6145* 6146 the package private part 6147* 6148 the body of the package 6149* 6150 the elaboration code after ``begin`` 6151 6152For a package, the rule is that if you explicitly turn SPARK_Mode 6153``Off`` for any part, then all the following parts must have 6154SPARK_Mode ``Off``. Note that this may require repeating a pragma 6155SPARK_Mode (``Off``) in the body. For example, if we have a 6156configuration pragma SPARK_Mode (``On``) that turns the mode on by 6157default everywhere, and one particular package spec has pragma 6158SPARK_Mode (``Off``), then that pragma will need to be repeated in 6159the package body. 6160 6161Pragma Static_Elaboration_Desired 6162================================= 6163 6164Syntax: 6165 6166 6167.. code-block:: ada 6168 6169 pragma Static_Elaboration_Desired; 6170 6171 6172This pragma is used to indicate that the compiler should attempt to initialize 6173statically the objects declared in the library unit to which the pragma applies, 6174when these objects are initialized (explicitly or implicitly) by an aggregate. 6175In the absence of this pragma, aggregates in object declarations are expanded 6176into assignments and loops, even when the aggregate components are static 6177constants. When the aggregate is present the compiler builds a static expression 6178that requires no run-time code, so that the initialized object can be placed in 6179read-only data space. If the components are not static, or the aggregate has 6180more that 100 components, the compiler emits a warning that the pragma cannot 6181be obeyed. (See also the restriction No_Implicit_Loops, which supports static 6182construction of larger aggregates with static components that include an others 6183choice.) 6184 6185Pragma Stream_Convert 6186===================== 6187 6188Syntax: 6189 6190 6191:: 6192 6193 pragma Stream_Convert ( 6194 [Entity =>] type_LOCAL_NAME, 6195 [Read =>] function_NAME, 6196 [Write =>] function_NAME); 6197 6198 6199This pragma provides an efficient way of providing user-defined stream 6200attributes. Not only is it simpler to use than specifying the attributes 6201directly, but more importantly, it allows the specification to be made in such 6202a way that the predefined unit Ada.Streams is not loaded unless it is actually 6203needed (i.e. unless the stream attributes are actually used); the use of 6204the Stream_Convert pragma adds no overhead at all, unless the stream 6205attributes are actually used on the designated type. 6206 6207The first argument specifies the type for which stream functions are 6208provided. The second parameter provides a function used to read values 6209of this type. It must name a function whose argument type may be any 6210subtype, and whose returned type must be the type given as the first 6211argument to the pragma. 6212 6213The meaning of the ``Read`` parameter is that if a stream attribute directly 6214or indirectly specifies reading of the type given as the first parameter, 6215then a value of the type given as the argument to the Read function is 6216read from the stream, and then the Read function is used to convert this 6217to the required target type. 6218 6219Similarly the ``Write`` parameter specifies how to treat write attributes 6220that directly or indirectly apply to the type given as the first parameter. 6221It must have an input parameter of the type specified by the first parameter, 6222and the return type must be the same as the input type of the Read function. 6223The effect is to first call the Write function to convert to the given stream 6224type, and then write the result type to the stream. 6225 6226The Read and Write functions must not be overloaded subprograms. If necessary 6227renamings can be supplied to meet this requirement. 6228The usage of this attribute is best illustrated by a simple example, taken 6229from the GNAT implementation of package Ada.Strings.Unbounded: 6230 6231 6232.. code-block:: ada 6233 6234 function To_Unbounded (S : String) return Unbounded_String 6235 renames To_Unbounded_String; 6236 6237 pragma Stream_Convert 6238 (Unbounded_String, To_Unbounded, To_String); 6239 6240 6241The specifications of the referenced functions, as given in the Ada 6242Reference Manual are: 6243 6244 6245.. code-block:: ada 6246 6247 function To_Unbounded_String (Source : String) 6248 return Unbounded_String; 6249 6250 function To_String (Source : Unbounded_String) 6251 return String; 6252 6253 6254The effect is that if the value of an unbounded string is written to a stream, 6255then the representation of the item in the stream is in the same format that 6256would be used for ``Standard.String'Output``, and this same representation 6257is expected when a value of this type is read from the stream. Note that the 6258value written always includes the bounds, even for Unbounded_String'Write, 6259since Unbounded_String is not an array type. 6260 6261Note that the ``Stream_Convert`` pragma is not effective in the case of 6262a derived type of a non-limited tagged type. If such a type is specified then 6263the pragma is silently ignored, and the default implementation of the stream 6264attributes is used instead. 6265 6266Pragma Style_Checks 6267=================== 6268 6269Syntax: 6270 6271 6272:: 6273 6274 pragma Style_Checks (string_LITERAL | ALL_CHECKS | 6275 On | Off [, LOCAL_NAME]); 6276 6277 6278This pragma is used in conjunction with compiler switches to control the 6279built in style checking provided by GNAT. The compiler switches, if set, 6280provide an initial setting for the switches, and this pragma may be used 6281to modify these settings, or the settings may be provided entirely by 6282the use of the pragma. This pragma can be used anywhere that a pragma 6283is legal, including use as a configuration pragma (including use in 6284the :file:`gnat.adc` file). 6285 6286The form with a string literal specifies which style options are to be 6287activated. These are additive, so they apply in addition to any previously 6288set style check options. The codes for the options are the same as those 6289used in the *-gnaty* switch to *gcc* or *gnatmake*. 6290For example the following two methods can be used to enable 6291layout checking: 6292 6293* 6294 6295 :: 6296 6297 pragma Style_Checks ("l"); 6298 6299 6300* 6301 6302 :: 6303 6304 gcc -c -gnatyl ... 6305 6306 6307The form ``ALL_CHECKS`` activates all standard checks (its use is equivalent 6308to the use of the :switch:`gnaty` switch with no options. 6309See the :title:`GNAT User's Guide` for details.) 6310 6311Note: the behavior is slightly different in GNAT mode (:switch:`-gnatg` used). 6312In this case, ``ALL_CHECKS`` implies the standard set of GNAT mode style check 6313options (i.e. equivalent to :switch:`-gnatyg`). 6314 6315The forms with ``Off`` and ``On`` 6316can be used to temporarily disable style checks 6317as shown in the following example: 6318 6319 6320.. code-block:: ada 6321 6322 pragma Style_Checks ("k"); -- requires keywords in lower case 6323 pragma Style_Checks (Off); -- turn off style checks 6324 NULL; -- this will not generate an error message 6325 pragma Style_Checks (On); -- turn style checks back on 6326 NULL; -- this will generate an error message 6327 6328 6329Finally the two argument form is allowed only if the first argument is 6330``On`` or ``Off``. The effect is to turn of semantic style checks 6331for the specified entity, as shown in the following example: 6332 6333 6334.. code-block:: ada 6335 6336 pragma Style_Checks ("r"); -- require consistency of identifier casing 6337 Arg : Integer; 6338 Rf1 : Integer := ARG; -- incorrect, wrong case 6339 pragma Style_Checks (Off, Arg); 6340 Rf2 : Integer := ARG; -- OK, no error 6341 6342 6343Pragma Subtitle 6344=============== 6345 6346Syntax: 6347 6348 6349:: 6350 6351 pragma Subtitle ([Subtitle =>] STRING_LITERAL); 6352 6353 6354This pragma is recognized for compatibility with other Ada compilers 6355but is ignored by GNAT. 6356 6357Pragma Suppress 6358=============== 6359 6360Syntax: 6361 6362 6363:: 6364 6365 pragma Suppress (Identifier [, [On =>] Name]); 6366 6367 6368This is a standard pragma, and supports all the check names required in 6369the RM. It is included here because GNAT recognizes some additional check 6370names that are implementation defined (as permitted by the RM): 6371 6372 6373* 6374 ``Alignment_Check`` can be used to suppress alignment checks 6375 on addresses used in address clauses. Such checks can also be suppressed 6376 by suppressing range checks, but the specific use of ``Alignment_Check`` 6377 allows suppression of alignment checks without suppressing other range checks. 6378 Note that ``Alignment_Check`` is suppressed by default on machines (such as 6379 the x86) with non-strict alignment. 6380 6381* 6382 ``Atomic_Synchronization`` can be used to suppress the special memory 6383 synchronization instructions that are normally generated for access to 6384 ``Atomic`` variables to ensure correct synchronization between tasks 6385 that use such variables for synchronization purposes. 6386 6387* 6388 ``Duplicated_Tag_Check`` Can be used to suppress the check that is generated 6389 for a duplicated tag value when a tagged type is declared. 6390 6391* 6392 ``Container_Checks`` Can be used to suppress all checks within Ada.Containers 6393 and instances of its children, including Tampering_Check. 6394 6395* 6396 ``Tampering_Check`` Can be used to suppress tampering check in the containers. 6397 6398* 6399 ``Predicate_Check`` can be used to control whether predicate checks are 6400 active. It is applicable only to predicates for which the policy is 6401 ``Check``. Unlike ``Assertion_Policy``, which determines if a given 6402 predicate is ignored or checked for the whole program, the use of 6403 ``Suppress`` and ``Unsuppress`` with this check name allows a given 6404 predicate to be turned on and off at specific points in the program. 6405 6406* 6407 ``Validity_Check`` can be used specifically to control validity checks. 6408 If ``Suppress`` is used to suppress validity checks, then no validity 6409 checks are performed, including those specified by the appropriate compiler 6410 switch or the ``Validity_Checks`` pragma. 6411 6412* 6413 Additional check names previously introduced by use of the ``Check_Name`` 6414 pragma are also allowed. 6415 6416 6417Note that pragma Suppress gives the compiler permission to omit 6418checks, but does not require the compiler to omit checks. The compiler 6419will generate checks if they are essentially free, even when they are 6420suppressed. In particular, if the compiler can prove that a certain 6421check will necessarily fail, it will generate code to do an 6422unconditional 'raise', even if checks are suppressed. The compiler 6423warns in this case. 6424 6425Of course, run-time checks are omitted whenever the compiler can prove 6426that they will not fail, whether or not checks are suppressed. 6427 6428Pragma Suppress_All 6429=================== 6430 6431Syntax: 6432 6433 6434.. code-block:: ada 6435 6436 pragma Suppress_All; 6437 6438 6439This pragma can appear anywhere within a unit. 6440The effect is to apply ``Suppress (All_Checks)`` to the unit 6441in which it appears. This pragma is implemented for compatibility with DEC 6442Ada 83 usage where it appears at the end of a unit, and for compatibility 6443with Rational Ada, where it appears as a program unit pragma. 6444The use of the standard Ada pragma ``Suppress (All_Checks)`` 6445as a normal configuration pragma is the preferred usage in GNAT. 6446 6447.. _Pragma-Suppress_Debug_Info: 6448 6449Pragma Suppress_Debug_Info 6450========================== 6451 6452Syntax: 6453 6454 6455:: 6456 6457 pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 6458 6459 6460This pragma can be used to suppress generation of debug information 6461for the specified entity. It is intended primarily for use in debugging 6462the debugger, and navigating around debugger problems. 6463 6464Pragma Suppress_Exception_Locations 6465=================================== 6466 6467Syntax: 6468 6469 6470.. code-block:: ada 6471 6472 pragma Suppress_Exception_Locations; 6473 6474 6475In normal mode, a raise statement for an exception by default generates 6476an exception message giving the file name and line number for the location 6477of the raise. This is useful for debugging and logging purposes, but this 6478entails extra space for the strings for the messages. The configuration 6479pragma ``Suppress_Exception_Locations`` can be used to suppress the 6480generation of these strings, with the result that space is saved, but the 6481exception message for such raises is null. This configuration pragma may 6482appear in a global configuration pragma file, or in a specific unit as 6483usual. It is not required that this pragma be used consistently within 6484a partition, so it is fine to have some units within a partition compiled 6485with this pragma and others compiled in normal mode without it. 6486 6487.. _Pragma-Suppress_Initialization: 6488 6489Pragma Suppress_Initialization 6490============================== 6491.. index:: Suppressing initialization 6492 6493.. index:: Initialization, suppression of 6494 6495Syntax: 6496 6497 6498:: 6499 6500 pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 6501 6502 6503Here variable_or_subtype_Name is the name introduced by a type declaration 6504or subtype declaration or the name of a variable introduced by an 6505object declaration. 6506 6507In the case of a type or subtype 6508this pragma suppresses any implicit or explicit initialization 6509for all variables of the given type or subtype, 6510including initialization resulting from the use of pragmas 6511Normalize_Scalars or Initialize_Scalars. 6512 6513This is considered a representation item, so it cannot be given after 6514the type is frozen. It applies to all subsequent object declarations, 6515and also any allocator that creates objects of the type. 6516 6517If the pragma is given for the first subtype, then it is considered 6518to apply to the base type and all its subtypes. If the pragma is given 6519for other than a first subtype, then it applies only to the given subtype. 6520The pragma may not be given after the type is frozen. 6521 6522Note that this includes eliminating initialization of discriminants 6523for discriminated types, and tags for tagged types. In these cases, 6524you will have to use some non-portable mechanism (e.g. address 6525overlays or unchecked conversion) to achieve required initialization 6526of these fields before accessing any object of the corresponding type. 6527 6528For the variable case, implicit initialization for the named variable 6529is suppressed, just as though its subtype had been given in a pragma 6530Suppress_Initialization, as described above. 6531 6532Pragma Task_Name 6533================ 6534 6535Syntax 6536 6537 6538.. code-block:: ada 6539 6540 pragma Task_Name (string_EXPRESSION); 6541 6542 6543This pragma appears within a task definition (like pragma 6544``Priority``) and applies to the task in which it appears. The 6545argument must be of type String, and provides a name to be used for 6546the task instance when the task is created. Note that this expression 6547is not required to be static, and in particular, it can contain 6548references to task discriminants. This facility can be used to 6549provide different names for different tasks as they are created, 6550as illustrated in the example below. 6551 6552The task name is recorded internally in the run-time structures 6553and is accessible to tools like the debugger. In addition the 6554routine ``Ada.Task_Identification.Image`` will return this 6555string, with a unique task address appended. 6556 6557 6558.. code-block:: ada 6559 6560 -- Example of the use of pragma Task_Name 6561 6562 with Ada.Task_Identification; 6563 use Ada.Task_Identification; 6564 with Text_IO; use Text_IO; 6565 procedure t3 is 6566 6567 type Astring is access String; 6568 6569 task type Task_Typ (Name : access String) is 6570 pragma Task_Name (Name.all); 6571 end Task_Typ; 6572 6573 task body Task_Typ is 6574 Nam : constant String := Image (Current_Task); 6575 begin 6576 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 6577 end Task_Typ; 6578 6579 type Ptr_Task is access Task_Typ; 6580 Task_Var : Ptr_Task; 6581 6582 begin 6583 Task_Var := 6584 new Task_Typ (new String'("This is task 1")); 6585 Task_Var := 6586 new Task_Typ (new String'("This is task 2")); 6587 end; 6588 6589 6590Pragma Task_Storage 6591=================== 6592Syntax: 6593 6594 6595:: 6596 6597 pragma Task_Storage ( 6598 [Task_Type =>] LOCAL_NAME, 6599 [Top_Guard =>] static_integer_EXPRESSION); 6600 6601 6602This pragma specifies the length of the guard area for tasks. The guard 6603area is an additional storage area allocated to a task. A value of zero 6604means that either no guard area is created or a minimal guard area is 6605created, depending on the target. This pragma can appear anywhere a 6606``Storage_Size`` attribute definition clause is allowed for a task 6607type. 6608 6609.. _Pragma-Test_Case: 6610 6611Pragma Test_Case 6612================ 6613.. index:: Test cases 6614 6615 6616Syntax: 6617 6618 6619:: 6620 6621 pragma Test_Case ( 6622 [Name =>] static_string_Expression 6623 ,[Mode =>] (Nominal | Robustness) 6624 [, Requires => Boolean_Expression] 6625 [, Ensures => Boolean_Expression]); 6626 6627 6628The ``Test_Case`` pragma allows defining fine-grain specifications 6629for use by testing tools. 6630The compiler checks the validity of the ``Test_Case`` pragma, but its 6631presence does not lead to any modification of the code generated by the 6632compiler. 6633 6634``Test_Case`` pragmas may only appear immediately following the 6635(separate) declaration of a subprogram in a package declaration, inside 6636a package spec unit. Only other pragmas may intervene (that is appear 6637between the subprogram declaration and a test case). 6638 6639The compiler checks that boolean expressions given in ``Requires`` and 6640``Ensures`` are valid, where the rules for ``Requires`` are the 6641same as the rule for an expression in ``Precondition`` and the rules 6642for ``Ensures`` are the same as the rule for an expression in 6643``Postcondition``. In particular, attributes ``'Old`` and 6644``'Result`` can only be used within the ``Ensures`` 6645expression. The following is an example of use within a package spec: 6646 6647 6648.. code-block:: ada 6649 6650 package Math_Functions is 6651 ... 6652 function Sqrt (Arg : Float) return Float; 6653 pragma Test_Case (Name => "Test 1", 6654 Mode => Nominal, 6655 Requires => Arg < 10000.0, 6656 Ensures => Sqrt'Result < 10.0); 6657 ... 6658 end Math_Functions; 6659 6660 6661The meaning of a test case is that there is at least one context where 6662``Requires`` holds such that, if the associated subprogram is executed in 6663that context, then ``Ensures`` holds when the subprogram returns. 6664Mode ``Nominal`` indicates that the input context should also satisfy the 6665precondition of the subprogram, and the output context should also satisfy its 6666postcondition. Mode ``Robustness`` indicates that the precondition and 6667postcondition of the subprogram should be ignored for this test case. 6668 6669.. _Pragma-Thread_Local_Storage: 6670 6671Pragma Thread_Local_Storage 6672=========================== 6673.. index:: Task specific storage 6674 6675.. index:: TLS (Thread Local Storage) 6676 6677.. index:: Task_Attributes 6678 6679Syntax: 6680 6681 6682:: 6683 6684 pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 6685 6686 6687This pragma specifies that the specified entity, which must be 6688a variable declared in a library-level package, is to be marked as 6689"Thread Local Storage" (``TLS``). On systems supporting this (which 6690include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each 6691thread (and hence each Ada task) to see a distinct copy of the variable. 6692 6693The variable must not have default initialization, and if there is 6694an explicit initialization, it must be either ``null`` for an 6695access variable, a static expression for a scalar variable, or a fully 6696static aggregate for a composite type, that is to say, an aggregate all 6697of whose components are static, and which does not include packed or 6698discriminated components. 6699 6700This provides a low-level mechanism similar to that provided by 6701the ``Ada.Task_Attributes`` package, but much more efficient 6702and is also useful in writing interface code that will interact 6703with foreign threads. 6704 6705If this pragma is used on a system where ``TLS`` is not supported, 6706then an error message will be generated and the program will be rejected. 6707 6708Pragma Time_Slice 6709================= 6710 6711Syntax: 6712 6713 6714.. code-block:: ada 6715 6716 pragma Time_Slice (static_duration_EXPRESSION); 6717 6718 6719For implementations of GNAT on operating systems where it is possible 6720to supply a time slice value, this pragma may be used for this purpose. 6721It is ignored if it is used in a system that does not allow this control, 6722or if it appears in other than the main program unit. 6723 6724Pragma Title 6725============ 6726 6727Syntax: 6728 6729 6730:: 6731 6732 pragma Title (TITLING_OPTION [, TITLING OPTION]); 6733 6734 TITLING_OPTION ::= 6735 [Title =>] STRING_LITERAL, 6736 | [Subtitle =>] STRING_LITERAL 6737 6738 6739Syntax checked but otherwise ignored by GNAT. This is a listing control 6740pragma used in DEC Ada 83 implementations to provide a title and/or 6741subtitle for the program listing. The program listing generated by GNAT 6742does not have titles or subtitles. 6743 6744Unlike other pragmas, the full flexibility of named notation is allowed 6745for this pragma, i.e., the parameters may be given in any order if named 6746notation is used, and named and positional notation can be mixed 6747following the normal rules for procedure calls in Ada. 6748 6749Pragma Type_Invariant 6750===================== 6751 6752Syntax: 6753 6754 6755:: 6756 6757 pragma Type_Invariant 6758 ([Entity =>] type_LOCAL_NAME, 6759 [Check =>] EXPRESSION); 6760 6761 6762The ``Type_Invariant`` pragma is intended to be an exact 6763replacement for the language-defined ``Type_Invariant`` 6764aspect, and shares its restrictions and semantics. It differs 6765from the language defined ``Invariant`` pragma in that it 6766does not permit a string parameter, and it is 6767controlled by the assertion identifier ``Type_Invariant`` 6768rather than ``Invariant``. 6769 6770.. _Pragma-Type_Invariant_Class: 6771 6772Pragma Type_Invariant_Class 6773=========================== 6774 6775Syntax: 6776 6777 6778:: 6779 6780 pragma Type_Invariant_Class 6781 ([Entity =>] type_LOCAL_NAME, 6782 [Check =>] EXPRESSION); 6783 6784 6785The ``Type_Invariant_Class`` pragma is intended to be an exact 6786replacement for the language-defined ``Type_Invariant'Class`` 6787aspect, and shares its restrictions and semantics. 6788 6789Note: This pragma is called ``Type_Invariant_Class`` rather than 6790``Type_Invariant'Class`` because the latter would not be strictly 6791conforming to the allowed syntax for pragmas. The motivation 6792for providing pragmas equivalent to the aspects is to allow a program 6793to be written using the pragmas, and then compiled if necessary 6794using an Ada compiler that does not recognize the pragmas or 6795aspects, but is prepared to ignore the pragmas. The assertion 6796policy that controls this pragma is ``Type_Invariant'Class``, 6797not ``Type_Invariant_Class``. 6798 6799Pragma Unchecked_Union 6800====================== 6801.. index:: Unions in C 6802 6803 6804Syntax: 6805 6806 6807.. code-block:: ada 6808 6809 pragma Unchecked_Union (first_subtype_LOCAL_NAME); 6810 6811 6812This pragma is used to specify a representation of a record type that is 6813equivalent to a C union. It was introduced as a GNAT implementation defined 6814pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 6815pragma, making it language defined, and GNAT fully implements this extended 6816version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 6817details, consult the Ada 2012 Reference Manual, section B.3.3. 6818 6819Pragma Unevaluated_Use_Of_Old 6820============================= 6821.. index:: Attribute Old 6822 6823.. index:: Attribute Loop_Entry 6824 6825.. index:: Unevaluated_Use_Of_Old 6826 6827 6828Syntax: 6829 6830 6831.. code-block:: ada 6832 6833 pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 6834 6835 6836This pragma controls the processing of attributes Old and Loop_Entry. 6837If either of these attributes is used in a potentially unevaluated 6838expression (e.g. the then or else parts of an if expression), then 6839normally this usage is considered illegal if the prefix of the attribute 6840is other than an entity name. The language requires this 6841behavior for Old, and GNAT copies the same rule for Loop_Entry. 6842 6843The reason for this rule is that otherwise, we can have a situation 6844where we save the Old value, and this results in an exception, even 6845though we might not evaluate the attribute. Consider this example: 6846 6847 6848.. code-block:: ada 6849 6850 package UnevalOld is 6851 K : Character; 6852 procedure U (A : String; C : Boolean) -- ERROR 6853 with Post => (if C then A(1)'Old = K else True); 6854 end; 6855 6856 6857If procedure U is called with a string with a lower bound of 2, and 6858C false, then an exception would be raised trying to evaluate A(1) 6859on entry even though the value would not be actually used. 6860 6861Although the rule guarantees against this possibility, it is sometimes 6862too restrictive. For example if we know that the string has a lower 6863bound of 1, then we will never raise an exception. 6864The pragma ``Unevaluated_Use_Of_Old`` can be 6865used to modify this behavior. If the argument is ``Error`` then an 6866error is given (this is the default RM behavior). If the argument is 6867``Warn`` then the usage is allowed as legal but with a warning 6868that an exception might be raised. If the argument is ``Allow`` 6869then the usage is allowed as legal without generating a warning. 6870 6871This pragma may appear as a configuration pragma, or in a declarative 6872part or package specification. In the latter case it applies to 6873uses up to the end of the corresponding statement sequence or 6874sequence of package declarations. 6875 6876Pragma Unimplemented_Unit 6877========================= 6878 6879Syntax: 6880 6881 6882.. code-block:: ada 6883 6884 pragma Unimplemented_Unit; 6885 6886 6887If this pragma occurs in a unit that is processed by the compiler, GNAT 6888aborts with the message :samp:`xxx not implemented`, where 6889``xxx`` is the name of the current compilation unit. This pragma is 6890intended to allow the compiler to handle unimplemented library units in 6891a clean manner. 6892 6893The abort only happens if code is being generated. Thus you can use 6894specs of unimplemented packages in syntax or semantic checking mode. 6895 6896.. _Pragma-Universal_Aliasing: 6897 6898Pragma Universal_Aliasing 6899========================= 6900 6901Syntax: 6902 6903 6904:: 6905 6906 pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 6907 6908 6909``type_LOCAL_NAME`` must refer to a type declaration in the current 6910declarative part. The effect is to inhibit strict type-based aliasing 6911optimization for the given type. In other words, the effect is as though 6912access types designating this type were subject to pragma No_Strict_Aliasing. 6913For a detailed description of the strict aliasing optimization, and the 6914situations in which it must be suppressed, see the section on 6915``Optimization and Strict Aliasing`` in the :title:`GNAT User's Guide`. 6916 6917.. _Pragma-Universal_Data: 6918 6919Pragma Universal_Data 6920===================== 6921 6922Syntax: 6923 6924 6925:: 6926 6927 pragma Universal_Data [(library_unit_Name)]; 6928 6929 6930This pragma is supported only for the AAMP target and is ignored for 6931other targets. The pragma specifies that all library-level objects 6932(Counter 0 data) associated with the library unit are to be accessed 6933and updated using universal addressing (24-bit addresses for AAMP5) 6934rather than the default of 16-bit Data Environment (DENV) addressing. 6935Use of this pragma will generally result in less efficient code for 6936references to global data associated with the library unit, but 6937allows such data to be located anywhere in memory. This pragma is 6938a library unit pragma, but can also be used as a configuration pragma 6939(including use in the :file:`gnat.adc` file). The functionality 6940of this pragma is also available by applying the -univ switch on the 6941compilations of units where universal addressing of the data is desired. 6942 6943.. _Pragma-Unmodified: 6944 6945Pragma Unmodified 6946================= 6947.. index:: Warnings, unmodified 6948 6949Syntax: 6950 6951 6952:: 6953 6954 pragma Unmodified (LOCAL_NAME {, LOCAL_NAME}); 6955 6956 6957This pragma signals that the assignable entities (variables, 6958``out`` parameters, ``in out`` parameters) whose names are listed are 6959deliberately not assigned in the current source unit. This 6960suppresses warnings about the 6961entities being referenced but not assigned, and in addition a warning will be 6962generated if one of these entities is in fact assigned in the 6963same unit as the pragma (or in the corresponding body, or one 6964of its subunits). 6965 6966This is particularly useful for clearly signaling that a particular 6967parameter is not modified, even though the spec suggests that it might 6968be. 6969 6970For the variable case, warnings are never given for unreferenced variables 6971whose name contains one of the substrings 6972``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names 6973are typically to be used in cases where such warnings are expected. 6974Thus it is never necessary to use ``pragma Unmodified`` for such 6975variables, though it is harmless to do so. 6976 6977.. _Pragma-Unreferenced: 6978 6979Pragma Unreferenced 6980=================== 6981.. index:: Warnings, unreferenced 6982 6983Syntax: 6984 6985 6986:: 6987 6988 pragma Unreferenced (LOCAL_NAME {, LOCAL_NAME}); 6989 pragma Unreferenced (library_unit_NAME {, library_unit_NAME}); 6990 6991 6992This pragma signals that the entities whose names are listed are 6993deliberately not referenced in the current source unit after the 6994occurrence of the pragma. This 6995suppresses warnings about the 6996entities being unreferenced, and in addition a warning will be 6997generated if one of these entities is in fact subsequently referenced in the 6998same unit as the pragma (or in the corresponding body, or one 6999of its subunits). 7000 7001This is particularly useful for clearly signaling that a particular 7002parameter is not referenced in some particular subprogram implementation 7003and that this is deliberate. It can also be useful in the case of 7004objects declared only for their initialization or finalization side 7005effects. 7006 7007If ``LOCAL_NAME`` identifies more than one matching homonym in the 7008current scope, then the entity most recently declared is the one to which 7009the pragma applies. Note that in the case of accept formals, the pragma 7010Unreferenced may appear immediately after the keyword ``do`` which 7011allows the indication of whether or not accept formals are referenced 7012or not to be given individually for each accept statement. 7013 7014The left hand side of an assignment does not count as a reference for the 7015purpose of this pragma. Thus it is fine to assign to an entity for which 7016pragma Unreferenced is given. 7017 7018Note that if a warning is desired for all calls to a given subprogram, 7019regardless of whether they occur in the same unit as the subprogram 7020declaration, then this pragma should not be used (calls from another 7021unit would not be flagged); pragma Obsolescent can be used instead 7022for this purpose, see :ref:`Pragma_Obsolescent`. 7023 7024The second form of pragma ``Unreferenced`` is used within a context 7025clause. In this case the arguments must be unit names of units previously 7026mentioned in ``with`` clauses (similar to the usage of pragma 7027``Elaborate_All``. The effect is to suppress warnings about unreferenced 7028units and unreferenced entities within these units. 7029 7030For the variable case, warnings are never given for unreferenced variables 7031whose name contains one of the substrings 7032``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names 7033are typically to be used in cases where such warnings are expected. 7034Thus it is never necessary to use ``pragma Unreferenced`` for such 7035variables, though it is harmless to do so. 7036 7037.. _Pragma-Unreferenced_Objects: 7038 7039Pragma Unreferenced_Objects 7040=========================== 7041.. index:: Warnings, unreferenced 7042 7043Syntax: 7044 7045 7046:: 7047 7048 pragma Unreferenced_Objects (local_subtype_NAME {, local_subtype_NAME}); 7049 7050 7051This pragma signals that for the types or subtypes whose names are 7052listed, objects which are declared with one of these types or subtypes may 7053not be referenced, and if no references appear, no warnings are given. 7054 7055This is particularly useful for objects which are declared solely for their 7056initialization and finalization effect. Such variables are sometimes referred 7057to as RAII variables (Resource Acquisition Is Initialization). Using this 7058pragma on the relevant type (most typically a limited controlled type), the 7059compiler will automatically suppress unwanted warnings about these variables 7060not being referenced. 7061 7062Pragma Unreserve_All_Interrupts 7063=============================== 7064 7065Syntax: 7066 7067 7068.. code-block:: ada 7069 7070 pragma Unreserve_All_Interrupts; 7071 7072 7073Normally certain interrupts are reserved to the implementation. Any attempt 7074to attach an interrupt causes Program_Error to be raised, as described in 7075RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in 7076many systems for a :kbd:`Ctrl-C` interrupt. Normally this interrupt is 7077reserved to the implementation, so that :kbd:`Ctrl-C` can be used to 7078interrupt execution. 7079 7080If the pragma ``Unreserve_All_Interrupts`` appears anywhere in any unit in 7081a program, then all such interrupts are unreserved. This allows the 7082program to handle these interrupts, but disables their standard 7083functions. For example, if this pragma is used, then pressing 7084:kbd:`Ctrl-C` will not automatically interrupt execution. However, 7085a program can then handle the ``SIGINT`` interrupt as it chooses. 7086 7087For a full list of the interrupts handled in a specific implementation, 7088see the source code for the spec of ``Ada.Interrupts.Names`` in 7089file :file:`a-intnam.ads`. This is a target dependent file that contains the 7090list of interrupts recognized for a given target. The documentation in 7091this file also specifies what interrupts are affected by the use of 7092the ``Unreserve_All_Interrupts`` pragma. 7093 7094For a more general facility for controlling what interrupts can be 7095handled, see pragma ``Interrupt_State``, which subsumes the functionality 7096of the ``Unreserve_All_Interrupts`` pragma. 7097 7098Pragma Unsuppress 7099================= 7100 7101Syntax: 7102 7103 7104:: 7105 7106 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 7107 7108 7109This pragma undoes the effect of a previous pragma ``Suppress``. If 7110there is no corresponding pragma ``Suppress`` in effect, it has no 7111effect. The range of the effect is the same as for pragma 7112``Suppress``. The meaning of the arguments is identical to that used 7113in pragma ``Suppress``. 7114 7115One important application is to ensure that checks are on in cases where 7116code depends on the checks for its correct functioning, so that the code 7117will compile correctly even if the compiler switches are set to suppress 7118checks. For example, in a program that depends on external names of tagged 7119types and wants to ensure that the duplicated tag check occurs even if all 7120run-time checks are suppressed by a compiler switch, the following 7121configuration pragma will ensure this test is not suppressed: 7122 7123 7124.. code-block:: ada 7125 7126 pragma Unsuppress (Duplicated_Tag_Check); 7127 7128 7129This pragma is standard in Ada 2005. It is available in all earlier versions 7130of Ada as an implementation-defined pragma. 7131 7132Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 7133number of implementation-defined check names. See the description of pragma 7134``Suppress`` for full details. 7135 7136Pragma Use_VADS_Size 7137==================== 7138.. index:: Size, VADS compatibility 7139 7140.. index:: Rational profile 7141 7142 7143Syntax: 7144 7145 7146.. code-block:: ada 7147 7148 pragma Use_VADS_Size; 7149 7150 7151This is a configuration pragma. In a unit to which it applies, any use 7152of the 'Size attribute is automatically interpreted as a use of the 7153'VADS_Size attribute. Note that this may result in incorrect semantic 7154processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 7155the handling of existing code which depends on the interpretation of Size 7156as implemented in the VADS compiler. See description of the VADS_Size 7157attribute for further details. 7158 7159.. _Pragma-Unused: 7160 7161Pragma Unused 7162============= 7163.. index:: Warnings, unused 7164 7165Syntax: 7166 7167 7168:: 7169 7170 pragma Unused (LOCAL_NAME {, LOCAL_NAME}); 7171 7172 7173This pragma signals that the assignable entities (variables, 7174``out`` parameters, and ``in out`` parameters) whose names are listed 7175deliberately do not get assigned or referenced in the current source unit 7176after the occurrence of the pragma in the current source unit. This 7177suppresses warnings about the entities that are unreferenced and/or not 7178assigned, and, in addition, a warning will be generated if one of these 7179entities gets assigned or subsequently referenced in the same unit as the 7180pragma (in the corresponding body or one of its subunits). 7181 7182This is particularly useful for clearly signaling that a particular 7183parameter is not modified or referenced, even though the spec suggests 7184that it might be. 7185 7186For the variable case, warnings are never given for unreferenced 7187variables whose name contains one of the substrings 7188``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names 7189are typically to be used in cases where such warnings are expected. 7190Thus it is never necessary to use ``pragma Unmodified`` for such 7191variables, though it is harmless to do so. 7192 7193Pragma Validity_Checks 7194====================== 7195 7196Syntax: 7197 7198 7199.. code-block:: ada 7200 7201 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 7202 7203 7204This pragma is used in conjunction with compiler switches to control the 7205built-in validity checking provided by GNAT. The compiler switches, if set 7206provide an initial setting for the switches, and this pragma may be used 7207to modify these settings, or the settings may be provided entirely by 7208the use of the pragma. This pragma can be used anywhere that a pragma 7209is legal, including use as a configuration pragma (including use in 7210the :file:`gnat.adc` file). 7211 7212The form with a string literal specifies which validity options are to be 7213activated. The validity checks are first set to include only the default 7214reference manual settings, and then a string of letters in the string 7215specifies the exact set of options required. The form of this string 7216is exactly as described for the *-gnatVx* compiler switch (see the 7217GNAT User's Guide for details). For example the following two 7218methods can be used to enable validity checking for mode ``in`` and 7219``in out`` subprogram parameters: 7220 7221* 7222 7223 .. code-block:: ada 7224 7225 pragma Validity_Checks ("im"); 7226 7227 7228* 7229 7230 .. code-block:: sh 7231 7232 $ gcc -c -gnatVim ... 7233 7234 7235The form ALL_CHECKS activates all standard checks (its use is equivalent 7236to the use of the :switch:`gnatVa` switch). 7237 7238The forms with ``Off`` and ``On`` can be used to temporarily disable 7239validity checks as shown in the following example: 7240 7241 7242.. code-block:: ada 7243 7244 pragma Validity_Checks ("c"); -- validity checks for copies 7245 pragma Validity_Checks (Off); -- turn off validity checks 7246 A := B; -- B will not be validity checked 7247 pragma Validity_Checks (On); -- turn validity checks back on 7248 A := C; -- C will be validity checked 7249 7250.. _Pragma-Volatile: 7251 7252Pragma Volatile 7253=============== 7254 7255Syntax: 7256 7257 7258.. code-block:: ada 7259 7260 pragma Volatile (LOCAL_NAME); 7261 7262 7263This pragma is defined by the Ada Reference Manual, and the GNAT 7264implementation is fully conformant with this definition. The reason it 7265is mentioned in this section is that a pragma of the same name was supplied 7266in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 7267implementation of pragma Volatile is upwards compatible with the 7268implementation in DEC Ada 83. 7269 7270.. _Pragma-Volatile_Full_Access: 7271 7272Pragma Volatile_Full_Access 7273=========================== 7274 7275Syntax: 7276 7277 7278.. code-block:: ada 7279 7280 pragma Volatile_Full_Access (LOCAL_NAME); 7281 7282 7283This is similar in effect to pragma Volatile, except that any reference to the 7284object is guaranteed to be done only with instructions that read or write all 7285the bits of the object. Furthermore, if the object is of a composite type, 7286then any reference to a subcomponent of the object is guaranteed to read 7287and/or write all the bits of the object. 7288 7289The intention is that this be suitable for use with memory-mapped I/O devices 7290on some machines. Note that there are two important respects in which this is 7291different from ``pragma Atomic``. First a reference to a ``Volatile_Full_Access`` 7292object is not a sequential action in the RM 9.10 sense and, therefore, does 7293not create a synchronization point. Second, in the case of ``pragma Atomic``, 7294there is no guarantee that all the bits will be accessed if the reference 7295is not to the whole object; the compiler is allowed (and generally will) 7296access only part of the object in this case. 7297 7298.. _Pragma-Volatile_Function: 7299 7300Pragma Volatile_Function 7301======================== 7302 7303Syntax: 7304 7305.. code-block:: ada 7306 7307 pragma Volatile_Function [ (boolean_EXPRESSION) ]; 7308 7309For the semantics of this pragma, see the entry for aspect ``Volatile_Function`` 7310in the SPARK 2014 Reference Manual, section 7.1.2. 7311 7312Pragma Warning_As_Error 7313======================= 7314 7315Syntax: 7316 7317 7318.. code-block:: ada 7319 7320 pragma Warning_As_Error (static_string_EXPRESSION); 7321 7322 7323This configuration pragma allows the programmer to specify a set 7324of warnings that will be treated as errors. Any warning that 7325matches the pattern given by the pragma argument will be treated 7326as an error. This gives more precise control than -gnatwe, 7327which treats warnings as errors. 7328 7329This pragma can apply to regular warnings (messages enabled by -gnatw) 7330and to style warnings (messages that start with "(style)", 7331enabled by -gnaty). 7332 7333The pattern may contain asterisks, which match zero or more characters 7334in the message. For example, you can use ``pragma Warning_As_Error 7335("bits of*unused")`` to treat the warning message ``warning: 960 bits of 7336"a" unused`` as an error. All characters other than asterisk are treated 7337as literal characters in the match. The match is case insensitive; for 7338example XYZ matches xyz. 7339 7340Note that the pattern matches if it occurs anywhere within the warning 7341message string (it is not necessary to put an asterisk at the start and 7342the end of the message, since this is implied). 7343 7344Another possibility for the static_string_EXPRESSION which works whether 7345or not error tags are enabled (*-gnatw.d*) is to use a single 7346*-gnatw* tag string, enclosed in brackets, 7347as shown in the example below, to treat one category of warnings as errors. 7348Note that if you want to treat multiple categories of warnings as errors, 7349you can use multiple pragma Warning_As_Error. 7350 7351The above use of patterns to match the message applies only to warning 7352messages generated by the front end. This pragma can also be applied to 7353warnings provided by the back end and mentioned in :ref:`Pragma_Warnings`. 7354By using a single full *-Wxxx* switch in the pragma, such warnings 7355can also be treated as errors. 7356 7357The pragma can appear either in a global configuration pragma file 7358(e.g. :file:`gnat.adc`), or at the start of a file. Given a global 7359configuration pragma file containing: 7360 7361 7362.. code-block:: ada 7363 7364 pragma Warning_As_Error ("[-gnatwj]"); 7365 7366 7367which will treat all obsolescent feature warnings as errors, the 7368following program compiles as shown (compile options here are 7369*-gnatwa.d -gnatl -gnatj55*). 7370 7371 7372:: 7373 7374 1. pragma Warning_As_Error ("*never assigned*"); 7375 2. function Warnerr return String is 7376 3. X : Integer; 7377 | 7378 >>> error: variable "X" is never read and 7379 never assigned [-gnatwv] [warning-as-error] 7380 7381 4. Y : Integer; 7382 | 7383 >>> warning: variable "Y" is assigned but 7384 never read [-gnatwu] 7385 7386 5. begin 7387 6. Y := 0; 7388 7. return %ABC%; 7389 | 7390 >>> error: use of "%" is an obsolescent 7391 feature (RM J.2(4)), use """ instead 7392 [-gnatwj] [warning-as-error] 7393 7394 8. end; 7395 7396 8 lines: No errors, 3 warnings (2 treated as errors) 7397 7398 7399Note that this pragma does not affect the set of warnings issued in 7400any way, it merely changes the effect of a matching warning if one 7401is produced as a result of other warnings options. As shown in this 7402example, if the pragma results in a warning being treated as an error, 7403the tag is changed from "warning:" to "error:" and the string 7404"[warning-as-error]" is appended to the end of the message. 7405 7406.. _Pragma_Warnings: 7407 7408Pragma Warnings 7409=============== 7410 7411Syntax: 7412 7413 7414.. code-block:: ada 7415 7416 pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 7417 7418 DETAILS ::= On | Off 7419 DETAILS ::= On | Off, local_NAME 7420 DETAILS ::= static_string_EXPRESSION 7421 DETAILS ::= On | Off, static_string_EXPRESSION 7422 7423 TOOL_NAME ::= GNAT | GNATprove 7424 7425 REASON ::= Reason => STRING_LITERAL {& STRING_LITERAL} 7426 7427Note: in Ada 83 mode, a string literal may be used in place of a static string 7428expression (which does not exist in Ada 83). 7429 7430Note if the second argument of ``DETAILS`` is a ``local_NAME`` then the 7431second form is always understood. If the intention is to use 7432the fourth form, then you can write ``NAME & ""`` to force the 7433intepretation as a *static_string_EXPRESSION*. 7434 7435Note: if the first argument is a valid ``TOOL_NAME``, it will be interpreted 7436that way. The use of the ``TOOL_NAME`` argument is relevant only to users 7437of SPARK and GNATprove, see last part of this section for details. 7438 7439Normally warnings are enabled, with the output being controlled by 7440the command line switch. Warnings (``Off``) turns off generation of 7441warnings until a Warnings (``On``) is encountered or the end of the 7442current unit. If generation of warnings is turned off using this 7443pragma, then some or all of the warning messages are suppressed, 7444regardless of the setting of the command line switches. 7445 7446The ``Reason`` parameter may optionally appear as the last argument 7447in any of the forms of this pragma. It is intended purely for the 7448purposes of documenting the reason for the ``Warnings`` pragma. 7449The compiler will check that the argument is a static string but 7450otherwise ignore this argument. Other tools may provide specialized 7451processing for this string. 7452 7453The form with a single argument (or two arguments if Reason present), 7454where the first argument is ``ON`` or ``OFF`` 7455may be used as a configuration pragma. 7456 7457If the ``LOCAL_NAME`` parameter is present, warnings are suppressed for 7458the specified entity. This suppression is effective from the point where 7459it occurs till the end of the extended scope of the variable (similar to 7460the scope of ``Suppress``). This form cannot be used as a configuration 7461pragma. 7462 7463In the case where the first argument is other than ``ON`` or 7464``OFF``, 7465the third form with a single static_string_EXPRESSION argument (and possible 7466reason) provides more precise 7467control over which warnings are active. The string is a list of letters 7468specifying which warnings are to be activated and which deactivated. The 7469code for these letters is the same as the string used in the command 7470line switch controlling warnings. For a brief summary, use the gnatmake 7471command with no arguments, which will generate usage information containing 7472the list of warnings switches supported. For 7473full details see the section on ``Warning Message Control`` in the 7474:title:`GNAT User's Guide`. 7475This form can also be used as a configuration pragma. 7476 7477The warnings controlled by the :switch:`-gnatw` switch are generated by the 7478front end of the compiler. The GCC back end can provide additional warnings 7479and they are controlled by the :switch:`-W` switch. Such warnings can be 7480identified by the appearance of a string of the form ``[-W{xxx}]`` in the 7481message which designates the :switch:`-W{xxx}` switch that controls the message. 7482The form with a single *static_string_EXPRESSION* argument also works for these 7483warnings, but the string must be a single full :switch:`-W{xxx}` switch in this 7484case. The above reference lists a few examples of these additional warnings. 7485 7486The specified warnings will be in effect until the end of the program 7487or another pragma ``Warnings`` is encountered. The effect of the pragma is 7488cumulative. Initially the set of warnings is the standard default set 7489as possibly modified by compiler switches. Then each pragma Warning 7490modifies this set of warnings as specified. This form of the pragma may 7491also be used as a configuration pragma. 7492 7493The fourth form, with an ``On|Off`` parameter and a string, is used to 7494control individual messages, based on their text. The string argument 7495is a pattern that is used to match against the text of individual 7496warning messages (not including the initial "warning: " tag). 7497 7498The pattern may contain asterisks, which match zero or more characters in 7499the message. For example, you can use 7500``pragma Warnings (Off, "bits of*unused")`` to suppress the warning 7501message ``warning: 960 bits of "a" unused``. No other regular 7502expression notations are permitted. All characters other than asterisk in 7503these three specific cases are treated as literal characters in the match. 7504The match is case insensitive, for example XYZ matches xyz. 7505 7506Note that the pattern matches if it occurs anywhere within the warning 7507message string (it is not necessary to put an asterisk at the start and 7508the end of the message, since this is implied). 7509 7510The above use of patterns to match the message applies only to warning 7511messages generated by the front end. This form of the pragma with a string 7512argument can also be used to control warnings provided by the back end and 7513mentioned above. By using a single full :switch:`-W{xxx}` switch in the pragma, 7514such warnings can be turned on and off. 7515 7516There are two ways to use the pragma in this form. The OFF form can be used 7517as a configuration pragma. The effect is to suppress all warnings (if any) 7518that match the pattern string throughout the compilation (or match the 7519-W switch in the back end case). 7520 7521The second usage is to suppress a warning locally, and in this case, two 7522pragmas must appear in sequence: 7523 7524 7525.. code-block:: ada 7526 7527 pragma Warnings (Off, Pattern); 7528 ... code where given warning is to be suppressed 7529 pragma Warnings (On, Pattern); 7530 7531 7532In this usage, the pattern string must match in the Off and On 7533pragmas, and (if *-gnatw.w* is given) at least one matching 7534warning must be suppressed. 7535 7536Note: if the ON form is not found, then the effect of the OFF form extends 7537until the end of the file (pragma Warnings is purely textual, so its effect 7538does not stop at the end of the enclosing scope). 7539 7540Note: to write a string that will match any warning, use the string 7541``"***"``. It will not work to use a single asterisk or two 7542asterisks since this looks like an operator name. This form with three 7543asterisks is similar in effect to specifying ``pragma Warnings (Off)`` except (if :switch:`-gnatw.w` is given) that a matching 7544``pragma Warnings (On, "***")`` will be required. This can be 7545helpful in avoiding forgetting to turn warnings back on. 7546 7547Note: the debug flag :switch:`-gnatd.i` can be 7548used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 7549be useful in checking whether obsolete pragmas in existing programs are hiding 7550real problems. 7551 7552Note: pragma Warnings does not affect the processing of style messages. See 7553separate entry for pragma Style_Checks for control of style messages. 7554 7555Users of the formal verification tool GNATprove for the SPARK subset of Ada may 7556use the version of the pragma with a ``TOOL_NAME`` parameter. 7557 7558If present, ``TOOL_NAME`` is the name of a tool, currently either ``GNAT`` for the 7559compiler or ``GNATprove`` for the formal verification tool. A given tool only 7560takes into account pragma Warnings that do not specify a tool name, or that 7561specify the matching tool name. This makes it possible to disable warnings 7562selectively for each tool, and as a consequence to detect useless pragma 7563Warnings with switch :switch:`-gnatw.w`. 7564 7565Pragma Weak_External 7566==================== 7567 7568Syntax: 7569 7570 7571.. code-block:: ada 7572 7573 pragma Weak_External ([Entity =>] LOCAL_NAME); 7574 7575 7576``LOCAL_NAME`` must refer to an object that is declared at the library 7577level. This pragma specifies that the given entity should be marked as a 7578weak symbol for the linker. It is equivalent to ``__attribute__((weak))`` 7579in GNU C and causes ``LOCAL_NAME`` to be emitted as a weak symbol instead 7580of a regular symbol, that is to say a symbol that does not have to be 7581resolved by the linker if used in conjunction with a pragma Import. 7582 7583When a weak symbol is not resolved by the linker, its address is set to 7584zero. This is useful in writing interfaces to external modules that may 7585or may not be linked in the final executable, for example depending on 7586configuration settings. 7587 7588If a program references at run time an entity to which this pragma has been 7589applied, and the corresponding symbol was not resolved at link time, then 7590the execution of the program is erroneous. It is not erroneous to take the 7591Address of such an entity, for example to guard potential references, 7592as shown in the example below. 7593 7594Some file formats do not support weak symbols so not all target machines 7595support this pragma. 7596 7597 7598.. code-block:: ada 7599 7600 -- Example of the use of pragma Weak_External 7601 7602 package External_Module is 7603 key : Integer; 7604 pragma Import (C, key); 7605 pragma Weak_External (key); 7606 function Present return boolean; 7607 end External_Module; 7608 7609 with System; use System; 7610 package body External_Module is 7611 function Present return boolean is 7612 begin 7613 return key'Address /= System.Null_Address; 7614 end Present; 7615 end External_Module; 7616 7617 7618Pragma Wide_Character_Encoding 7619============================== 7620 7621Syntax: 7622 7623 7624.. code-block:: ada 7625 7626 pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 7627 7628 7629This pragma specifies the wide character encoding to be used in program 7630source text appearing subsequently. It is a configuration pragma, but may 7631also be used at any point that a pragma is allowed, and it is permissible 7632to have more than one such pragma in a file, allowing multiple encodings 7633to appear within the same file. 7634 7635However, note that the pragma cannot immediately precede the relevant 7636wide character, because then the previous encoding will still be in 7637effect, causing "illegal character" errors. 7638 7639The argument can be an identifier or a character literal. In the identifier 7640case, it is one of ``HEX``, ``UPPER``, ``SHIFT_JIS``, 7641``EUC``, ``UTF8``, or ``BRACKETS``. In the character literal 7642case it is correspondingly one of the characters :kbd:`h`, :kbd:`u`, 7643:kbd:`s`, :kbd:`e`, :kbd:`8`, or :kbd:`b`. 7644 7645Note that when the pragma is used within a file, it affects only the 7646encoding within that file, and does not affect withed units, specs, 7647or subunits. 7648