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