OSDN Git Service

* doc/include/gcc-common.texi: Define DEVELOPMENT.
[pf3gnuchains/gcc-fork.git] / gcc / ada / gnat_rm.texi
1 \input texinfo   @c -*-texinfo-*-
2
3 @c %**start of header
4
5 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
6 @c                                                                            o
7 @c                           GNAT DOCUMENTATION                               o
8 @c                                                                            o
9 @c                              G N A T _ RM                                  o
10 @c                                                                            o
11 @c                            $Revision: 1.8 $
12 @c                                                                            o
13 @c              Copyright (C) 1995-2002 Free Software Foundation              o
14 @c                                                                            o
15 @c                                                                            o
16 @c  GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).    o
17 @c                                                                            o
18 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
19
20 @setfilename gnat_rm.info
21 @settitle GNAT Reference Manual
22 @setchapternewpage odd
23 @syncodeindex fn cp
24
25 @include gcc-common.texi
26
27 @dircategory GNU Ada tools
28 @direntry
29 * GNAT Reference Manual: (gnat_rm).  Reference Manual for GNU Ada tools.
30 @end direntry
31 @titlepage
32
33
34 @title GNAT Reference Manual
35 @subtitle GNAT, The GNU Ada 95 Compiler
36 @subtitle GNAT Version for GCC @value{version-GCC}
37 @author Ada Core Technologies, Inc.
38
39 @page
40 @vskip 0pt plus 1filll
41
42
43 Copyright @copyright{} 1995-2001, Free Software Foundation
44
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.1
47 or any later version published by the Free Software Foundation;
48 with the Invariant Sections being ``GNU Free Documentation License'', with the
49 Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover Texts.
50 A copy of the license is included in the section entitled ``GNU
51 Free Documentation License''.
52
53
54 @end titlepage
55 @ifnottex
56 @node Top, About This Guide, (dir), (dir)
57 @top GNAT Reference Manual
58
59
60 GNAT Reference Manual
61
62 GNAT, The GNU Ada 95 Compiler
63
64 GNAT Version for GCC @value{version-GCC}
65
66 Ada Core Technologies, Inc.
67
68
69 Copyright @copyright{} 1995-2001, Free Software Foundation
70
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.1
73 or any later version published by the Free Software Foundation;
74 with the Invariant Sections being ``GNU Free Documentation License'', with the
75 Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover Texts.
76 A copy of the license is included in the section entitled ``GNU
77 Free Documentation License''.
78
79
80 @menu
81 * About This Guide::            
82 * Implementation Defined Pragmas::  
83 * Implementation Defined Attributes::  
84 * Implementation Advice::       
85 * Implementation Defined Characteristics::  
86 * Intrinsic Subprograms::
87 * Representation Clauses and Pragmas::
88 * Standard Library Routines::   
89 * The Implementation of Standard I/O::  
90 * The GNAT Library::
91 * Interfacing to Other Languages::  
92 * Machine Code Insertions::
93 * GNAT Implementation of Tasking::
94 * Code generation for array aggregates::
95 * Specialized Needs Annexes::   
96 * Compatibility Guide::
97 * GNU Free Documentation License::
98 * Index::                       
99
100  --- The Detailed Node Listing ---
101
102 About This Guide
103
104 * What This Reference Manual Contains::  
105 * Related Information::         
106
107 The Implementation of Standard I/O
108
109 * Standard I/O Packages::       
110 * FORM Strings::                
111 * Direct_IO::                   
112 * Sequential_IO::               
113 * Text_IO::                     
114 * Wide_Text_IO::                
115 * Stream_IO::                   
116 * Shared Files::                
117 * Open Modes::                  
118 * Operations on C Streams::     
119 * Interfacing to C Streams::    
120
121 The GNAT Library
122
123 * Ada.Characters.Latin_9 (a-chlat9.ads)::
124 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
125 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
126 * Ada.Command_Line.Remove (a-colire.ads)::
127 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
128 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
129 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
130 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
131 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
132 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
133 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
134 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
135 * GNAT.AWK (g-awk.ads)::
136 * GNAT.Bubble_Sort_A (g-busora.ads)::
137 * GNAT.Bubble_Sort_G (g-busorg.ads)::
138 * GNAT.Calendar (g-calend.ads)::
139 * GNAT.Calendar.Time_IO (g-catiio.ads)::
140 * GNAT.Case_Util (g-casuti.ads)::
141 * GNAT.CGI (g-cgi.ads)::
142 * GNAT.CGI.Cookie (g-cgicoo.ads)::
143 * GNAT.CGI.Debug (g-cgideb.ads)::
144 * GNAT.Command_Line (g-comlin.ads)::
145 * GNAT.CRC32 (g-crc32.ads)::
146 * GNAT.Current_Exception (g-curexc.ads)::
147 * GNAT.Debug_Pools (g-debpoo.ads)::
148 * GNAT.Debug_Utilities (g-debuti.ads)::
149 * GNAT.Directory_Operations (g-dirope.ads)::
150 * GNAT.Dynamic_Tables (g-dyntab.ads)::
151 * GNAT.Exception_Traces (g-exctra.ads)::
152 * GNAT.Expect (g-expect.ads)::
153 * GNAT.Float_Control (g-flocon.ads)::
154 * GNAT.Heap_Sort_A (g-hesora.ads)::
155 * GNAT.Heap_Sort_G (g-hesorg.ads)::
156 * GNAT.HTable (g-htable.ads)::
157 * GNAT.IO (g-io.ads)::
158 * GNAT.IO_Aux (g-io_aux.ads)::
159 * GNAT.Lock_Files (g-locfil.ads)::
160 * GNAT.MD5 (g-md5.ads)::
161 * GNAT.Most_Recent_Exception (g-moreex.ads)::
162 * GNAT.OS_Lib (g-os_lib.ads)::
163 * GNAT.Regexp (g-regexp.ads)::
164 * GNAT.Registry (g-regist.ads)::
165 * GNAT.Regpat (g-regpat.ads)::
166 * GNAT.Sockets (g-socket.ads)::
167 * GNAT.Source_Info (g-souinf.ads)::
168 * GNAT.Spell_Checker (g-speche.ads)::
169 * GNAT.Spitbol.Patterns (g-spipat.ads)::
170 * GNAT.Spitbol (g-spitbo.ads)::
171 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
172 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
173 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
174 * GNAT.Table (g-table.ads)::
175 * GNAT.Task_Lock (g-tasloc.ads)::
176 * GNAT.Threads (g-thread.ads)::
177 * GNAT.Traceback (g-traceb.ads)::
178 * GNAT.Traceback.Symbolic (g-trasym.ads)::
179 * Interfaces.C.Extensions (i-cexten.ads)::
180 * Interfaces.C.Streams (i-cstrea.ads)::
181 * Interfaces.CPP (i-cpp.ads)::
182 * Interfaces.Os2lib (i-os2lib.ads)::
183 * Interfaces.Os2lib.Errors (i-os2err.ads)::
184 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
185 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
186 * Interfaces.Packed_Decimal (i-pacdec.ads)::
187 * Interfaces.VxWorks (i-vxwork.ads)::
188 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
189 * System.Address_Image (s-addima.ads)::
190 * System.Assertions (s-assert.ads)::
191 * System.Partition_Interface (s-parint.ads)::
192 * System.Task_Info (s-tasinf.ads)::
193 * System.Wch_Cnv (s-wchcnv.ads)::
194 * System.Wch_Con (s-wchcon.ads)::
195
196 Text_IO
197
198 * Text_IO Stream Pointer Positioning::  
199 * Text_IO Reading and Writing Non-Regular Files::  
200 * Get_Immediate::               
201 * Treating Text_IO Files as Streams::
202 * Text_IO Extensions::
203 * Text_IO Facilities for Unbounded Strings::
204
205 Wide_Text_IO
206
207 * Wide_Text_IO Stream Pointer Positioning::  
208 * Wide_Text_IO Reading and Writing Non-Regular Files::  
209
210 Interfacing to Other Languages
211
212 * Interfacing to C::
213 * Interfacing to C++::          
214 * Interfacing to COBOL::        
215 * Interfacing to Fortran::      
216 * Interfacing to non-GNAT Ada code::
217
218 GNAT Implementation of Tasking
219
220 * Mapping Ada Tasks onto the Underlying Kernel Threads::
221 * Ensuring Compliance with the Real-Time Annex::
222 @end menu
223
224 @end ifnottex
225
226 @node About This Guide
227 @unnumbered About This Guide
228
229 @noindent
230 This manual contains useful information in writing programs using the
231 GNAT compiler.  It includes information on implementation dependent
232 characteristics of GNAT, including all the information required by Annex
233 M of the standard.
234
235 Ada 95 is designed to be highly portable,and guarantees that, for most
236 programs, Ada 95 compilers behave in exactly the same manner on
237 different machines.  However, since Ada 95 is designed to be used in a
238 wide variety of applications, it also contains a number of system
239 dependent features to Functbe used in interfacing to the external world. 
240
241 @c Maybe put the following in platform-specific section
242 @ignore
243 @cindex ProDev Ada
244 This reference manual discusses how these features are implemented for
245 use in ProDev Ada running on the IRIX 5.3 or greater operating systems.
246 @end ignore
247
248 @cindex Implementation-dependent features
249 @cindex Portability
250 Note: Any program that makes use of implementation-dependent features
251 may be non-portable.  You should follow good programming practice and
252 isolate and clearly document any sections of your program that make use
253 of these features in a non-portable manner.
254
255 @menu
256 * What This Reference Manual Contains::  
257 * Conventions::
258 * Related Information::         
259 @end menu
260
261 @node What This Reference Manual Contains
262 @unnumberedsec What This Reference Manual Contains
263
264 This reference manual contains the following chapters:
265
266 @itemize @bullet
267 @item
268 @ref{Implementation Defined Pragmas} lists GNAT implementation-dependent
269 pragmas, which can be used to extend and enhance the functionality of the
270 compiler.
271
272 @item
273 @ref{Implementation Defined Attributes} lists GNAT
274 implementation-dependent attributes which can be used to extend and
275 enhance the functionality of the compiler.
276
277 @item
278 @ref{Implementation Advice} provides information on generally
279 desirable behavior which are not requirements that all compilers must
280 follow since it cannot be provided on all systems, or which may be
281 undesirable on some systems.
282
283 @item
284 @ref{Implementation Defined Characteristics} provides a guide to
285 minimizing implementation dependent features.
286
287 @item
288 @ref{Intrinsic Subprograms} describes the intrinsic subprograms
289 implemented by GNAT, and how they can be imported into user
290 application programs.
291
292 @item
293 @ref{Representation Clauses and Pragmas} describes in detail the
294 way that GNAT represents data, and in particular the exact set
295 of representation clauses and pragmas that is accepted.
296
297 @item
298 @ref{Standard Library Routines} provides a listing of packages and a
299 brief description of the functionality that is provided by Ada's
300 extensive set of standard library routines as implemented by GNAT@.
301
302 @item
303 @ref{The Implementation of Standard I/O} details how the GNAT
304 implementation of the input-output facilities.
305
306 @item
307 @ref{Interfacing to Other Languages} describes how programs
308 written in Ada using GNAT can be interfaced to other programming
309 languages.
310
311 @item
312 @ref{Specialized Needs Annexes} describes the GNAT implementation of all
313 of the special needs annexes.
314
315 @item
316 @ref{Compatibility Guide} includes sections on compatibility of GNAT with
317 other Ada 83 and Ada 95 compilation systems, to assist in porting code
318 from other environments.
319 @end itemize
320
321 @cindex Ada 95 ISO/ANSI Standard
322 This reference manual assumes that you are familiar with Ada 95
323 language, as described in the International Standard
324 ANSI/ISO/IEC-8652:1995, Jan 1995.
325
326 @node Conventions
327 @unnumberedsec Conventions
328 @cindex Conventions, typographical
329 @cindex Typographical conventions
330
331 @noindent
332 Following are examples of the typographical and graphic conventions used
333 in this guide:
334
335 @itemize @bullet
336 @item
337 @code{Functions}, @code{utility program names}, @code{standard names},
338 and @code{classes}.
339
340 @item
341 @code{Option flags}
342
343 @item
344 @file{File Names}, @samp{button names}, and @samp{field names}.
345
346 @item
347 @code{Variables}.
348
349 @item
350 @emph{Emphasis}.
351
352 @item
353 [optional information or parameters]
354
355 @item
356 Examples are described by text
357 @smallexample
358 and then shown this way.
359 @end smallexample
360 @end itemize
361
362 @noindent
363 Commands that are entered by the user are preceded in this manual by the
364 characters @samp{$ } (dollar sign followed by space).  If your system uses this
365 sequence as a prompt, then the commands will appear exactly as you see them
366 in the manual.  If your system uses some other prompt, then the command will
367 appear with the @samp{$} replaced by whatever prompt character you are using.
368
369 @node Related Information
370 @unnumberedsec Related Information
371 See the following documents for further information on GNAT:
372
373 @itemize @bullet
374 @item
375 @cite{GNAT User's Guide}, which provides information on how to use
376 the GNAT compiler system.
377
378 @item
379 @cite{Ada 95 Reference Manual}, which contains all reference
380 material for the Ada 95 programming language.
381
382 @item
383 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
384 of the standard reference manual cited above.  The annotations describe
385 detailed aspects of the design decision, and in particular contain useful
386 sections on Ada 83 compatibility.
387
388 @item
389 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
390 which contains specific information on compatibility between GNAT and
391 DEC Ada 83 systems.
392
393 @item
394 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
395 describes in detail the pragmas and attributes provided by the DEC Ada 83
396 compiler system.
397
398 @end itemize
399
400 @node Implementation Defined Pragmas
401 @chapter Implementation Defined Pragmas
402
403 @noindent
404 Ada 95 defines a set of pragmas that can be used to supply additional
405 information to the compiler.  These language defined pragmas are
406 implemented in GNAT and work as described in the Ada 95 Reference
407 Manual.
408
409 In addition, Ada 95 allows implementations to define additional pragmas
410 whose meaning is defined by the implementation.  GNAT provides a number
411 of these implementation-dependent pragmas which can be used to extend
412 and enhance the functionality of the compiler.  This section of the GNAT
413 Reference Manual describes these additional pragmas.
414
415 Note that any program using these pragmas may not be portable to other
416 compilers (although GNAT implements this set of pragmas on all
417 platforms).  Therefore if portability to other compilers is an important
418 consideration, the use of these pragmas should be minimized.
419
420 @table @code
421
422 @findex Abort_Defer
423 @cindex Deferring aborts
424 @item pragma Abort_Defer
425 @noindent
426 Syntax:
427
428 @smallexample
429 pragma Abort_Defer;
430 @end smallexample
431
432 @noindent
433 This pragma must appear at the start of the statement sequence of a
434 handled sequence of statements (right after the @code{begin}).  It has
435 the effect of deferring aborts for the sequence of statements (but not
436 for the declarations or handlers, if any, associated with this statement
437 sequence).
438
439 @item pragma Ada_83
440 @findex Ada_83
441 @noindent
442 Syntax:
443
444 @smallexample
445 pragma Ada_83;
446 @end smallexample
447
448 @noindent
449 A configuration pragma that establishes Ada 83 mode for the unit to
450 which it applies, regardless of the mode set by the command line
451 switches.  In Ada 83 mode, GNAT attempts to be as compatible with
452 the syntax and semantics of Ada 83, as defined in the original Ada
453 83 Reference Manual as possible.  In particular, the new Ada 95
454 keywords are not recognized, optional package bodies are allowed,
455 and generics may name types with unknown discriminants without using
456 the @code{(<>)} notation.  In addition, some but not all of the additional
457 restrictions of Ada 83 are enforced.
458
459 Ada 83 mode is intended for two purposes.  Firstly, it allows existing
460 legacy Ada 83 code to be compiled and adapted to GNAT with less effort.
461 Secondly, it aids in keeping code backwards compatible with Ada 83. 
462 However, there is no guarantee that code that is processed correctly
463 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
464 83 compiler, since GNAT does not enforce all the additional checks
465 required by Ada 83.
466
467 @findex Ada_95
468 @item pragma Ada_95
469 @noindent
470 Syntax:
471
472 @smallexample
473 pragma Ada_95;
474 @end smallexample
475
476 @noindent
477 A configuration pragma that establishes Ada 95 mode for the unit to which
478 it applies, regardless of the mode set by the command line switches.
479 This mode is set automatically for the @code{Ada} and @code{System}
480 packages and their children, so you need not specify it in these
481 contexts.  This pragma is useful when writing a reusable component that
482 itself uses Ada 95 features, but which is intended to be usable from
483 either Ada 83 or Ada 95 programs.
484
485 @findex Annotate
486 @item pragma Annotate
487 @noindent
488 Syntax:
489
490 @smallexample
491 pragma Annotate (IDENTIFIER @{, ARG@});
492
493 ARG ::= NAME | EXPRESSION
494 @end smallexample
495
496 @noindent
497 This pragma is used to annotate programs.  @var{identifier} identifies
498 the type of annotation.  GNAT verifies this is an identifier, but does
499 not otherwise analyze it.  The @var{arg} argument
500 can be either a string literal or an
501 expression.  String literals are assumed to be of type
502 @code{Standard.String}.  Names of entities are simply analyzed as entity
503 names.  All other expressions are analyzed as expressions, and must be
504 unambiguous.
505
506 The analyzed pragma is retained in the tree, but not otherwise processed
507 by any part of the GNAT compiler.  This pragma is intended for use by
508 external tools, including ASIS@.
509
510 @findex Assert
511 @item pragma Assert
512 @noindent
513 Syntax:
514
515 @smallexample
516 pragma Assert (
517   boolean_EXPRESSION
518   [, static_string_EXPRESSION])
519 @end smallexample
520
521 @noindent
522 The effect of this pragma depends on whether the corresponding command
523 line switch is set to activate assertions.  The pragma expands into code
524 equivalent to the following:
525
526 @smallexample
527 if assertions-enabled then
528    if not boolean_EXPRESSION then
529       System.Assertions.Raise_Assert_Failure
530         (string_EXPRESSION); 
531    end if;
532 end if;
533 @end smallexample
534
535 @noindent
536 The string argument, if given, is the message that will be associated
537 with the exception occurrence if the exception is raised.  If no second
538 argument is given, the default message is @samp{@var{file}:@var{nnn}},
539 where @var{file} is the name of the source file containing the assert,
540 and @var{nnn} is the line number of the assert.  A pragma is not a
541 statement, so if a statement sequence contains nothing but a pragma
542 assert, then a null statement is required in addition, as in:
543
544 @smallexample
545 @dots{}
546 if J > 3 then
547    pragma Assert (K > 3, "Bad value for K");
548    null;
549 end if;
550 @end smallexample
551
552 @noindent
553 Note that, as with the @code{if} statement to which it is equivalent, the
554 type of the expression is either @code{Standard.Boolean}, or any type derived
555 from this standard type.
556
557 If assertions are disabled (switch @code{-gnata} not used), then there
558 is no effect (and in particular, any side effects from the expression
559 are suppressed).  More precisely it is not quite true that the pragma
560 has no effect, since the expression is analyzed, and may cause types
561 to be frozen if they are mentioned here for the first time.
562
563 If assertions are enabled, then the given expression is tested, and if
564 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
565 which results in the raising of @code{Assert_Failure} with the given message.
566
567 If the boolean expression has side effects, these side effects will turn
568 on and off with the setting of the assertions mode, resulting in
569 assertions that have an effect on the program.  You should generally 
570 avoid side effects in the expression arguments of this pragma.  However,
571 the expressions are analyzed for semantic correctness whether or not
572 assertions are enabled, so turning assertions on and off cannot affect
573 the legality of a program.
574
575 @cindex OpenVMS
576 @findex Ast_Entry
577 @item pragma Ast_Entry
578 @noindent
579 Syntax:
580
581 @smallexample
582 pragma AST_Entry (entry_IDENTIFIER);
583 @end smallexample
584
585 @noindent
586 This pragma is implemented only in the OpenVMS implementation of GNAT@.  The
587 argument is the simple name of a single entry; at most one @code{AST_Entry}
588 pragma is allowed for any given entry.  This pragma must be used in 
589 conjunction with the @code{AST_Entry} attribute, and is only allowed after
590 the entry declaration and in the same task type specification or single task
591 as the entry to which it applies.  This pragma specifies that the given entry
592 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
593 resulting from an OpenVMS system service call.  The pragma does not affect
594 normal use of the entry.  For further details on this pragma, see the 
595 DEC Ada Language Reference Manual, section 9.12a.
596
597 @cindex Passing by copy
598 @findex C_Pass_By_Copy
599 @item pragma C_Pass_By_Copy
600 @noindent
601 Syntax:
602
603 @smallexample
604 pragma C_Pass_By_Copy
605   ([Max_Size =>] static_integer_EXPRESSION);
606 @end smallexample
607
608 @noindent
609 Normally the default mechanism for passing C convention records to C
610 convention subprograms is to pass them by reference, as suggested by RM
611 B.3(69).  Use the configuration pragma @code{C_Pass_By_Copy} to change
612 this default, by requiring that record formal parameters be passed by
613 copy if all of the following conditions are met:
614
615 @itemize @bullet
616 @item
617 The size of the record type does not exceed@*@var{static_integer_expression}.
618 @item
619 The record type has @code{Convention C}.
620 @item
621 The formal parameter has this record type, and the subprogram has a
622 foreign (non-Ada) convention.
623 @end itemize
624
625 @noindent
626 If these conditions are met the argument is passed by copy, i.e.@: in a
627 manner consistent with what C expects if the corresponding formal in the
628 C prototype is a struct (rather than a pointer to a struct).
629
630 You can also pass records by copy by specifying the convention
631 @code{C_Pass_By_Copy} for the record type, or by using the extended
632 @code{Import} and @code{Export} pragmas, which allow specification of
633 passing mechanisms on a parameter by parameter basis.
634
635 @findex Comment
636 @item pragma Comment
637 @noindent
638 Syntax:
639
640 @smallexample
641 pragma Comment (static_string_EXPRESSION);
642 @end smallexample
643
644 @noindent
645 This is almost identical in effect to pragma @code{Ident}.  It allows the
646 placement of a comment into the object file and hence into the
647 executable file if the operating system permits such usage.  The
648 difference is that @code{Comment}, unlike @code{Ident}, has no limit on the
649 length of the string argument, and no limitations on placement
650 of the pragma (it can be placed anywhere in the main source unit).
651
652 @findex Common_Object
653 @item pragma Common_Object
654 @noindent
655 Syntax:
656
657 @smallexample
658 pragma Common_Object (
659      [Internal =>] LOCAL_NAME,
660   [, [External =>] EXTERNAL_SYMBOL]
661   [, [Size     =>] EXTERNAL_SYMBOL] )
662
663 EXTERNAL_SYMBOL ::=
664   IDENTIFIER
665 | static_string_EXPRESSION
666 @end smallexample
667
668 @noindent
669 This pragma enables the shared use of variables stored in overlaid
670 linker areas corresponding to the use of @code{COMMON}
671 in Fortran.  The single
672 object @var{local_name} is assigned to the area designated by
673 the @var{External} argument.
674 You may define a record to correspond to a series
675 of fields.  The @var{size} argument
676 is syntax checked in GNAT, but otherwise ignored.
677
678 @code{Common_Object} is not supported on all platforms.  If no
679 support is available, then the code generator will issue a message
680 indicating that the necessary attribute for implementation of this
681 pragma is not available.
682
683 @findex Complex_Representation
684 @item pragma Complex_Representation
685 @noindent
686 Syntax:
687
688 @smallexample
689 pragma Complex_Representation
690         ([Entity =>] LOCAL_NAME);
691 @end smallexample
692
693 @noindent
694 The @var{Entity} argument must be the name of a record type which has
695 two fields of the same floating-point type.  The effect of this pragma is
696 to force gcc to use the special internal complex representation form for
697 this record, which may be more efficient.  Note that this may result in
698 the code for this type not conforming to standard ABI (application
699 binary interface) requirements for the handling of record types.  For
700 example, in some environments, there is a requirement for passing
701 records by pointer, and the use of this pragma may result in passing
702 this type in floating-point registers.
703
704 @cindex Alignments of components
705 @findex Component_Alignment
706 @item pragma Component_Alignment
707 @noindent
708 Syntax:
709
710 @smallexample
711 pragma Component_Alignment (
712      [Form =>] ALIGNMENT_CHOICE
713   [, [Name =>] type_LOCAL_NAME]);
714
715 ALIGNMENT_CHOICE ::=
716   Component_Size
717 | Component_Size_4
718 | Storage_Unit
719 | Default
720 @end smallexample
721
722 @noindent
723 Specifies the alignment of components in array or record types.
724 The meaning of the @var{Form} argument is as follows:
725
726 @table @code
727 @findex Component_Size
728 @item Component_Size
729 Aligns scalar components and subcomponents of the array or record type
730 on boundaries appropriate to their inherent size (naturally
731 aligned).  For example, 1-byte components are aligned on byte boundaries,
732 2-byte integer components are aligned on 2-byte boundaries, 4-byte
733 integer components are aligned on 4-byte boundaries and so on.  These
734 alignment rules correspond to the normal rules for C compilers on all
735 machines except the VAX@.
736
737 @findex Component_Size_4
738 @item Component_Size_4
739 Naturally aligns components with a size of four or fewer
740 bytes.  Components that are larger than 4 bytes are placed on the next
741 4-byte boundary.
742
743 @findex Storage_Unit
744 @item Storage_Unit
745 Specifies that array or record components are byte aligned, i.e.@:
746 aligned on boundaries determined by the value of the constant
747 @code{System.Storage_Unit}.
748
749 @cindex OpenVMS
750 @item Default
751 Specifies that array or record components are aligned on default
752 boundaries, appropriate to the underlying hardware or operating system or
753 both.  For OpenVMS VAX systems, the @code{Default} choice is the same as
754 the @code{Storage_Unit} choice (byte alignment).  For all other systems,
755 the @code{Default} choice is the same as @code{Component_Size} (natural
756 alignment).
757 @end table
758
759 If the @code{Name} parameter is present, @var{type_local_name} must
760 refer to a local record or array type, and the specified alignment
761 choice applies to the specified type.  The use of
762 @code{Component_Alignment} together with a pragma @code{Pack} causes the
763 @code{Component_Alignment} pragma to be ignored.  The use of
764 @code{Component_Alignment} together with a record representation clause
765 is only effective for fields not specified by the representation clause.
766
767 If the @code{Name} parameter is absent, the pragma can be used as either
768 a configuration pragma, in which case it applies to one or more units in
769 accordance with the normal rules for configuration pragmas, or it can be
770 used within a declarative part, in which case it applies to types that
771 are declared within this declarative part, or within any nested scope
772 within this declarative part.  In either case it specifies the alignment
773 to be applied to any record or array type which has otherwise standard
774 representation.
775
776 If the alignment for a record or array type is not specified (using
777 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
778 clause), the GNAT uses the default alignment as described previously.
779
780 @findex Convention_Identifier
781 @cindex Conventions, synonyms
782 @item pragma Convention_Identifier
783 @noindent
784 Syntax:
785
786 @smallexample
787 pragma Convention_Identifier (
788          [Name =>]       IDENTIFIER,
789          [Convention =>] convention_IDENTIFIER);
790 @end smallexample
791
792 @noindent
793 This pragma provides a mechanism for supplying synonyms for existing
794 convention identifiers. The @code{Name} identifier can subsequently
795 be used as a synonym for the given convention in other pragmas (including
796 for example pragma @code{Import} or another @code{Convention_Identifier}
797 pragma). As an example of the use of this, suppose you had legacy code
798 which used Fortran77 as the identifier for Fortran. Then the pragma:
799
800 @smallexample
801 pragma Convention_Indentifier (Fortran77, Fortran);
802 @end smallexample
803
804 @noindent
805 would allow the use of the convention identifier @code{Fortran77} in
806 subsequent code, avoiding the need to modify the sources. As another
807 example, you could use this to parametrize convention requirements
808 according to systems. Suppose you needed to use @code{Stdcall} on
809 windows systems, and @code{C} on some other system, then you could
810 define a convention identifier @code{Library} and use a single
811 @code{Convention_Identifier} pragma to specify which convention
812 would be used system-wide.
813   
814 @findex CPP_Class
815 @cindex Interfacing with C++
816 @item pragma CPP_Class
817 @noindent
818 Syntax:
819
820 @smallexample
821 pragma CPP_Class ([Entity =>] LOCAL_NAME);
822 @end smallexample
823
824 @noindent
825 The argument denotes an entity in the current declarative region
826 that is declared as a tagged or untagged record type.  It indicates that
827 the type corresponds to an externally declared C++ class type, and is to
828 be laid out the same way that C++ would lay out the type.
829
830 If (and only if) the type is tagged, at least one component in the
831 record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding
832 to the C++ Vtable (or Vtables in the case of multiple inheritance) used
833 for dispatching.
834
835 Types for which @code{CPP_Class} is specified do not have assignment or
836 equality operators defined (such operations can be imported or declared
837 as subprograms as required).  Initialization is allowed only by
838 constructor functions (see pragma @code{CPP_Constructor}).
839
840 Pragma @code{CPP_Class} is intended primarily for automatic generation
841 using an automatic binding generator tool.  
842 See @ref{Interfacing to C++} for related information.
843
844 @cindex Interfacing with C++
845 @findex CPP_Constructor
846 @item pragma CPP_Constructor
847 @noindent
848 Syntax:
849
850 @smallexample
851 pragma CPP_Constructor ([Entity =>] LOCAL_NAME);
852 @end smallexample
853
854 @noindent
855 This pragma identifies an imported function (imported in the usual way
856 with pragma @code{Import}) as corresponding to a C++
857 constructor.  The argument is a name that must have been
858 previously mentioned in a pragma @code{Import} 
859 with @code{Convention} = @code{CPP}, and must be of one of the following
860 forms:
861
862 @itemize @bullet
863 @item
864 @code{function @var{Fname} return @var{T}'Class}
865
866 @item
867 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
868 @end itemize
869
870 @noindent
871 where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
872
873 The first form is the default constructor, used when an object of type
874 @var{T} is created on the Ada side with no explicit constructor.  Other
875 constructors (including the copy constructor, which is simply a special
876 case of the second form in which the one and only argument is of type
877 @var{T}), can only appear in two contexts:
878
879 @itemize @bullet
880 @item
881 On the right side of an initialization of an object of type @var{T}.
882 @item
883 In an extension aggregate for an object of a type derived from @var{T}.
884 @end itemize
885
886 Although the constructor is described as a function that returns a value
887 on the Ada side, it is typically a procedure with an extra implicit
888 argument (the object being initialized) at the implementation
889 level.  GNAT issues the appropriate call, whatever it is, to get the
890 object properly initialized.
891
892 In the case of derived objects, you may use one of two possible forms
893 for declaring and creating an object:
894
895 @itemize @bullet
896 @item @code{New_Object : Derived_T}
897 @item @code{New_Object : Derived_T := (@var{constructor-function-call with} @dots{})}
898 @end itemize
899
900 In the first case the default constructor is called and extension fields
901 if any are initialized according to the default initialization
902 expressions in the Ada declaration.  In the second case, the given
903 constructor is called and the extension aggregate indicates the explicit
904 values of the extension fields.
905
906 If no constructors are imported, it is impossible to create any objects
907 on the Ada side.  If no default constructor is imported, only the
908 initialization forms using an explicit call to a constructor are
909 permitted.
910
911 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
912 using an automatic binding generator tool.  
913 See @ref{Interfacing to C++} for more related information.
914
915 @cindex Interfacing to C++
916 @findex CPP_Virtual
917 @item pragma CPP_Virtual
918 @noindent
919 Syntax:
920
921 @smallexample
922 pragma CPP_Virtual
923      [Entity     =>] ENTITY,
924   [, [Vtable_Ptr =>] vtable_ENTITY,]
925   [, [Position   =>] static_integer_EXPRESSION])
926 @end smallexample
927
928 This pragma serves the same function as pragma @code{Import} in that
929 case of a virtual function imported from C++.  The @var{Entity} argument
930 must be a
931 primitive subprogram of a tagged type to which pragma @code{CPP_Class}
932 applies.  The @var{Vtable_Ptr} argument specifies
933 the Vtable_Ptr component which contains the
934 entry for this virtual function.  The @var{Position} argument
935 is the sequential number
936 counting virtual functions for this Vtable starting at 1.
937
938 The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
939 there is one Vtable_Ptr present (single inheritance case) and all
940 virtual functions are imported.  In that case the compiler can deduce both
941 these values.
942
943 No @code{External_Name} or @code{Link_Name} arguments are required for a
944 virtual function, since it is always accessed indirectly via the
945 appropriate Vtable entry.
946
947 Pragma @code{CPP_Virtual} is intended primarily for automatic generation
948 using an automatic binding generator tool.  
949 See @ref{Interfacing to C++} for related information.
950
951 @cindex Interfacing with C++
952 @findex CPP_Vtable
953 @item pragma CPP_Vtable
954 @noindent
955 Syntax:
956
957 @smallexample
958 pragma CPP_Vtable (
959   [Entity      =>] ENTITY,
960   [Vtable_Ptr  =>] vtable_ENTITY,
961   [Entry_Count =>] static_integer_EXPRESSION);
962 @end smallexample
963
964 @noindent
965 Given a record to which the pragma @code{CPP_Class} applies,
966 this pragma can be specified for each component of type
967 @code{CPP.Interfaces.Vtable_Ptr}.
968 @var{Entity} is the tagged type, @var{Vtable_Ptr}
969 is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
970 the number of virtual functions on the C++ side.  Not all of these
971 functions need to be imported on the Ada side.
972
973 You may omit the @code{CPP_Vtable} pragma if there is only one
974 @code{Vtable_Ptr} component in the record and all virtual functions are
975 imported on the Ada side (the default value for the entry count in this
976 case is simply the total number of virtual functions).
977
978 Pragma @code{CPP_Vtable} is intended primarily for automatic generation
979 using an automatic binding generator tool.  
980 See @ref{Interfacing to C++} for related information.
981
982 @findex Debug
983 @item pragma Debug
984 @noindent
985 Syntax:
986
987 @smallexample
988 pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
989
990 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
991   PROCEDURE_NAME
992 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
993 @end smallexample
994
995 @noindent
996 The argument has the syntactic form of an expression, meeting the
997 syntactic requirements for pragmas. 
998
999 If assertions are not enabled on the command line, this pragma has no
1000 effect.  If asserts are enabled, the semantics of the pragma is exactly
1001 equivalent to the procedure call statement corresponding to the argument
1002 with a terminating semicolon.  Pragmas are permitted in sequences of
1003 declarations, so you can use pragma @code{Debug} to intersperse calls to
1004 debug procedures in the middle of declarations.
1005
1006 @cindex Elaboration control
1007 @findex Elaboration_Checks
1008 @item pragma Elaboration_Checks
1009 @noindent
1010 Syntax:
1011
1012 @smallexample
1013 pragma Elaboration_Checks (RM | Static);
1014 @end smallexample
1015
1016 @noindent
1017 This is a configuration pragma that provides control over the
1018 elaboration model used by the compilation affected by the
1019 pragma.  If the parameter is RM, then the dynamic elaboration
1020 model described in the Ada Reference Manual is used, as though
1021 the @code{-gnatE} switch had been specified on the command
1022 line.  If the parameter is Static, then the default GNAT static
1023 model is used.  This configuration pragma overrides the setting
1024 of the command line.  For full details on the elaboration models
1025 used by the GNAT compiler, see section ``Elaboration Order
1026 Handling in GNAT'' in the @cite{GNAT User's Guide}.
1027
1028 @cindex Elimination of unused subprograms
1029 @findex Eliminate
1030 @item pragma Eliminate
1031 @noindent
1032 Syntax:
1033
1034 @smallexample
1035 pragma Eliminate (
1036     [Unit_Name =>] IDENTIFIER |
1037                    SELECTED_COMPONENT);
1038
1039 pragma Eliminate (
1040     [Unit_Name       =>]  IDENTIFIER |
1041                           SELECTED_COMPONENT,
1042     [Entity          =>]  IDENTIFIER |
1043                           SELECTED_COMPONENT |
1044                           STRING_LITERAL
1045   [,[Parameter_Types =>]  PARAMETER_TYPES]
1046   [,[Result_Type     =>]  result_SUBTYPE_NAME]
1047   [,[Homonym_Number  =>]  INTEGER_LITERAL]);
1048
1049 PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
1050 SUBTYPE_NAME    ::= STRING_LITERAL
1051 @end smallexample
1052
1053 @noindent
1054 This pragma indicates that the given entity is not used outside the
1055 compilation unit it is defined in.  The entity may be either a subprogram 
1056 or a variable.
1057
1058 If the entity to be eliminated is a library level subprogram, then
1059 the first form of pragma @code{Eliminate} is used with only a single argument.
1060 In this form, the @code{Unit_Name} argument specifies the name of the
1061 library  level unit to be eliminated.
1062
1063 In all other cases, both @code{Unit_Name} and @code{Entity} arguments
1064 are required.  item is an entity of a library package, then the first
1065 argument specifies the unit name, and the second argument specifies
1066 the particular entity.  If the second argument is in string form, it must
1067 correspond to the internal manner in which GNAT stores entity names (see
1068 compilation unit Namet in the compiler sources for details).
1069
1070 The remaining parameters are optionally used to distinguish
1071 between overloaded subprograms.  There are two ways of doing this.
1072
1073 Use @code{Parameter_Types} and @code{Result_Type} to specify the
1074 profile of the subprogram to be eliminated in a manner similar to that
1075 used for
1076 the extended @code{Import} and @code{Export} pragmas, except that the
1077 subtype names are always given as string literals, again corresponding
1078 to the internal manner in which GNAT stores entity names.
1079
1080 Alternatively, the @code{Homonym_Number} parameter is used to specify
1081 which overloaded alternative is to be eliminated.  A value of 1 indicates
1082 the first subprogram (in lexical order), 2 indicates the second etc.
1083
1084 The effect of the pragma is to allow the compiler to eliminate
1085 the code or data associated with the named entity.  Any reference to 
1086 an eliminated entity outside the compilation unit it is defined in,
1087 causes a compile time or link time error.
1088
1089 The parameters of this pragma may be given in any order, as long as
1090 the usual rules for use of named parameters and position parameters
1091 are used.
1092
1093 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1094 in a system independent manner, with unused entities eliminated, without
1095 the requirement of modifying the source text.  Normally the required set
1096 of @code{Eliminate} pragmas is constructed automatically using the gnatelim tool.
1097 Elimination of unused entities local to a compilation unit is automatic,
1098 without requiring the use of pragma @code{Eliminate}.
1099
1100 Note that the reason this pragma takes string literals where names might
1101 be expected is that a pragma @code{Eliminate} can appear in a context where the
1102 relevant names are not visible.
1103
1104 @cindex OpenVMS
1105 @findex Export_Exception
1106 @item pragma Export_Exception
1107 @noindent
1108 Syntax:
1109
1110 @smallexample
1111 pragma Export_Exception (
1112      [Internal =>] LOCAL_NAME,
1113   [, [External =>] EXTERNAL_SYMBOL,]
1114   [, [Form     =>] Ada | VMS]
1115   [, [Code     =>] static_integer_EXPRESSION]);
1116
1117 EXTERNAL_SYMBOL ::=
1118   IDENTIFIER
1119 | static_string_EXPRESSION
1120 @end smallexample
1121
1122 @noindent
1123 This pragma is implemented only in the OpenVMS implementation of GNAT@.  It
1124 causes the specified exception to be propagated outside of the Ada program,
1125 so that it can be handled by programs written in other OpenVMS languages.
1126 This pragma establishes an external name for an Ada exception and makes the
1127 name available to the OpenVMS Linker as a global symbol.  For further details
1128 on this pragma, see the
1129 DEC Ada Language Reference Manual, section 13.9a3.2.
1130
1131 @cindex Argument passing mechanisms
1132 @findex Export_Function
1133 @item pragma Export_Function @dots{}
1134
1135 @noindent
1136 Syntax:
1137
1138 @smallexample
1139 pragma Export_Function (
1140      [Internal         =>] LOCAL_NAME,      
1141   [, [External         =>] EXTERNAL_SYMBOL]
1142   [, [Parameter_Types  =>] PARAMETER_TYPES]
1143   [, [Result_Type      =>] result_SUBTYPE_MARK]
1144   [, [Mechanism        =>] MECHANISM]
1145   [, [Result_Mechanism =>] MECHANISM_NAME]);
1146
1147 EXTERNAL_SYMBOL ::=
1148   IDENTIFIER
1149 | static_string_EXPRESSION
1150
1151 PARAMETER_TYPES ::=
1152   null
1153 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1154
1155 MECHANISM ::=
1156   MECHANISM_NAME
1157 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1158
1159 MECHANISM_ASSOCIATION ::=
1160   [formal_parameter_NAME =>] MECHANISM_NAME
1161
1162 MECHANISM_NAME ::=
1163   Value
1164 | Reference
1165 | Descriptor [([Class =>] CLASS_NAME)]
1166
1167 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1168 @end smallexample
1169
1170 Use this pragma to make a function externally callable and optionally
1171 provide information on mechanisms to be used for passing parameter and
1172 result values.  We recommend, for the purposes of improving portability,
1173 this pragma always be used in conjunction with a separate pragma
1174 @code{Export}, which must precede the pragma @code{Export_Function}.
1175 GNAT does not require a separate pragma @code{Export}, but if none is
1176 present, @code{Convention Ada} is assumed, which is usually
1177 not what is wanted, so it is usually appropriate to use this
1178 pragma in conjunction with a @code{Export} or @code{Convention}
1179 pragma that specifies the desired foreign convention.
1180 Pragma @code{Export_Function}
1181 (and @code{Export}, if present) must appear in the same declarative
1182 region as the function to which they apply.
1183
1184 @var{internal_name} must uniquely designate the function to which the
1185 pragma applies.  If more than one function name exists of this name in
1186 the declarative part you must use the @code{Parameter_Types} and
1187 @code{Result_Type} parameters is mandatory to achieve the required
1188 unique designation.  @var{subtype_ mark}s in these parameters must
1189 exactly match the subtypes in the corresponding function specification,
1190 using positional notation to match parameters with subtype marks.
1191 @cindex OpenVMS
1192 @cindex Passing by descriptor
1193 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
1194
1195 @findex Export_Object
1196 @item pragma Export_Object @dots{}
1197 @noindent
1198 Syntax:
1199
1200 @smallexample
1201 pragma Export_Object
1202       [Internal =>] LOCAL_NAME,
1203    [, [External =>] EXTERNAL_SYMBOL]
1204    [, [Size     =>] EXTERNAL_SYMBOL]
1205
1206 EXTERNAL_SYMBOL ::=
1207   IDENTIFIER
1208 | static_string_EXPRESSION
1209 @end smallexample
1210
1211 This pragma designates an object as exported, and apart from the
1212 extended rules for external symbols, is identical in effect to the use of
1213 the normal @code{Export} pragma applied to an object.  You may use a
1214 separate Export pragma (and you probably should from the point of view
1215 of portability), but it is not required.  @var{Size} is syntax checked,
1216 but otherwise ignored by GNAT@.
1217
1218 @findex Export_Procedure
1219 @item pragma Export_Procedure @dots{}
1220 @noindent
1221 Syntax:
1222
1223 @smallexample
1224 pragma Export_Procedure (
1225      [Internal        =>] LOCAL_NAME
1226   [, [External        =>] EXTERNAL_SYMBOL]
1227   [, [Parameter_Types =>] PARAMETER_TYPES]
1228   [, [Mechanism       =>] MECHANISM]);
1229
1230 EXTERNAL_SYMBOL ::=
1231   IDENTIFIER
1232 | static_string_EXPRESSION
1233
1234 PARAMETER_TYPES ::=
1235   null
1236 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1237
1238 MECHANISM ::=
1239   MECHANISM_NAME
1240 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1241
1242 MECHANISM_ASSOCIATION ::=
1243   [formal_parameter_NAME =>] MECHANISM_NAME
1244
1245 MECHANISM_NAME ::=
1246   Value
1247 | Reference
1248 | Descriptor [([Class =>] CLASS_NAME)]
1249
1250 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1251 @end smallexample
1252
1253 @noindent
1254 This pragma is identical to @code{Export_Function} except that it
1255 applies to a procedure rather than a function and the parameters
1256 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1257 GNAT does not require a separate pragma @code{Export}, but if none is
1258 present, @code{Convention Ada} is assumed, which is usually
1259 not what is wanted, so it is usually appropriate to use this
1260 pragma in conjunction with a @code{Export} or @code{Convention}
1261 pragma that specifies the desired foreign convention.
1262
1263 @findex Export_Valued_Procedure
1264 @item pragma Export_Valued_Procedure
1265 @noindent
1266 Syntax:
1267
1268 @smallexample
1269 pragma Export_Valued_Procedure (
1270      [Internal        =>] LOCAL_NAME
1271   [, [External        =>] EXTERNAL_SYMBOL]
1272   [, [Parameter_Types =>] PARAMETER_TYPES]
1273   [, [Mechanism       =>] MECHANISM]);
1274
1275 EXTERNAL_SYMBOL ::=
1276   IDENTIFIER
1277 | static_string_EXPRESSION
1278
1279 PARAMETER_TYPES ::=
1280   null
1281 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1282
1283 MECHANISM ::=
1284   MECHANISM_NAME
1285 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1286
1287 MECHANISM_ASSOCIATION ::=
1288   [formal_parameter_NAME =>] MECHANISM_NAME
1289
1290 MECHANISM_NAME ::=
1291   Value
1292 | Reference
1293 | Descriptor [([Class =>] CLASS_NAME)]
1294
1295 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1296 @end smallexample
1297
1298 This pragma is identical to @code{Export_Procedure} except that the
1299 first parameter of @var{local_name}, which must be present, must be of
1300 mode @code{OUT}, and externally the subprogram is treated as a function
1301 with this parameter as the result of the function.  GNAT provides for
1302 this capability to allow the use of @code{OUT} and @code{IN OUT}
1303 parameters in interfacing to external functions (which are not permitted
1304 in Ada functions).
1305 GNAT does not require a separate pragma @code{Export}, but if none is
1306 present, @code{Convention Ada} is assumed, which is almost certainly
1307 not what is wanted since the whole point of this pragma is to interface
1308 with foreign language functions, so it is usually appropriate to use this
1309 pragma in conjunction with a @code{Export} or @code{Convention}
1310 pragma that specifies the desired foreign convention.
1311
1312 @cindex @code{system}, extending
1313 @cindex Dec Ada 83
1314 @findex Extend_System
1315 @item pragma Extend_System
1316 @noindent
1317 Syntax:
1318
1319 @smallexample
1320 pragma Extend_System ([Name =>] IDENTIFIER);
1321 @end smallexample
1322
1323 @noindent
1324 This pragma is used to provide backwards compatibility with other
1325 implementations that extend the facilities of package @code{System}.  In
1326 GNAT, @code{System} contains only the definitions that are present in
1327 the Ada 95 RM@.  However, other implementations, notably the DEC Ada 83
1328 implementation, provide many extensions to package @code{System}.
1329
1330 For each such implementation accommodated by this pragma, GNAT provides a
1331 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
1332 implementation, which provides the required additional definitions.  You
1333 can use this package in two ways.  You can @code{with} it in the normal
1334 way and access entities either by selection or using a @code{use}
1335 clause.  In this case no special processing is required.
1336
1337 However, if existing code contains references such as
1338 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
1339 definitions provided in package @code{System}, you may use this pragma
1340 to extend visibility in @code{System} in a non-standard way that
1341 provides greater compatibility with the existing code.  Pragma
1342 @code{Extend_System} is a configuration pragma whose single argument is
1343 the name of the package containing the extended definition
1344 (e.g.@: @code{Aux_DEC} for the DEC Ada case).  A unit compiled under
1345 control of this pragma will be processed using special visibility
1346 processing that looks in package @code{System.Aux_@var{xxx}} where
1347 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
1348 package @code{System}, but not found in package @code{System}.
1349
1350 You can use this pragma either to access a predefined @code{System}
1351 extension supplied with the compiler, for example @code{Aux_DEC} or
1352 you can construct your own extension unit following the above
1353 definition.  Note that such a package is a child of @code{System}
1354 and thus is considered part of the implementation.  To compile
1355 it you will have to use the appropriate switch for compiling
1356 system units.  See the GNAT User's Guide for details.
1357
1358 @findex External
1359 @item pragma External
1360 @noindent
1361 Syntax:
1362
1363 @smallexample
1364 pragma External (
1365   [   Convention    =>] convention_IDENTIFIER,
1366   [   Entity        =>] local_NAME
1367   [, [External_Name =>] static_string_EXPRESSION ]
1368   [, [Link_Name     =>] static_string_EXPRESSION ]);
1369 @end smallexample
1370
1371 @noindent
1372 This pragma is identical in syntax and semantics to pragma
1373 @code{Export} as defined in the Ada Reference Manual.  It is
1374 provided for compatibility with some Ada 83 compilers that
1375 used this pragma for exactly the same purposes as pragma
1376 @code{Export} before the latter was standardized.
1377
1378 @cindex Dec Ada 83 casing compatibility
1379 @cindex External Names, casing
1380 @cindex Casing of External names
1381 @findex External_Name_Casing
1382 @item pragma External_Name_Casing
1383 @noindent
1384 Syntax:
1385
1386 @smallexample
1387 pragma External_Name_Casing (
1388   Uppercase | Lowercase
1389   [, Uppercase | Lowercase | As_Is]);
1390 @end smallexample
1391
1392 @noindent
1393 This pragma provides control over the casing of external names associated
1394 with Import and Export pragmas.  There are two cases to consider:
1395
1396 @table @asis
1397 @item Implicit external names
1398 Implicit external names are derived from identifiers.  The most common case
1399 arises when a standard Ada 95 Import or Export pragma is used with only two
1400 arguments, as in:
1401
1402 @smallexample
1403    pragma Import (C, C_Routine);
1404 @end smallexample
1405
1406 @noindent
1407 Since Ada is a case insensitive language, the spelling of the identifier in
1408 the Ada source program does not provide any information on the desired
1409 casing of the external name, and so a convention is needed.  In GNAT the
1410 default treatment is that such names are converted to all lower case
1411 letters.  This corresponds to the normal C style in many environments.
1412 The first argument of pragma @code{External_Name_Casing} can be used to
1413 control this treatment.  If @code{Uppercase} is specified, then the name
1414 will be forced to all uppercase letters.  If @code{Lowercase} is specified,
1415 then the normal default of all lower case letters will be used.
1416
1417 This same implicit treatment is also used in the case of extended DEC Ada 83
1418 compatible Import and Export pragmas where an external name is explicitly
1419 specified using an identifier rather than a string.
1420
1421 @item Explicit external names
1422 Explicit external names are given as string literals.  The most common case
1423 arises when a standard Ada 95 Import or Export pragma is used with three
1424 arguments, as in:
1425
1426 @smallexample
1427 pragma Import (C, C_Routine, "C_routine");
1428 @end smallexample
1429
1430 @noindent
1431 In this case, the string literal normally provides the exact casing required
1432 for the external name.  The second argument of pragma 
1433 @code{External_Name_Casing} may be used to modify this behavior. 
1434 If @code{Uppercase} is specified, then the name
1435 will be forced to all uppercase letters.  If @code{Lowercase} is specified,
1436 then the name will be forced to all lowercase letters.  A specification of
1437 @code{As_Is} provides the normal default behavior in which the casing is
1438 taken from the string provided.
1439 @end table
1440
1441 @noindent
1442 This pragma may appear anywhere that a pragma is valid.  In particular, it
1443 can be used as a configuration pragma in the @file{gnat.adc} file, in which
1444 case it applies to all subsequent compilations, or it can be used as a program
1445 unit pragma, in which case it only applies to the current unit, or it can
1446 be used more locally to control individual Import/Export pragmas.
1447
1448 It is primarily intended for use with OpenVMS systems, where many
1449 compilers convert all symbols to upper case by default.  For interfacing to
1450 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
1451 the pragma:
1452
1453 @smallexample
1454 pragma External_Name_Casing (Uppercase, Uppercase);
1455 @end smallexample
1456
1457 @noindent
1458 to enforce the upper casing of all external symbols. 
1459
1460 @findex Finalize_Storage_Only
1461 @item pragma Finalize_Storage_Only
1462 @noindent
1463 Syntax:
1464
1465 @smallexample
1466 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
1467 @end smallexample
1468
1469 @noindent
1470 This pragma allows the compiler not to emit a Finalize call for objects
1471 defined at the library level.  This is mostly useful for types where
1472 finalization is only used to deal with storage reclamation since in most
1473 environments it is not necessary to reclaim memory just before terminating
1474 execution, hence the name.
1475
1476 @cindex OpenVMS
1477 @findex Float_Representation
1478 @item pragma Float_Representation
1479 @noindent
1480 Syntax:
1481
1482 @smallexample
1483 pragma Float_Representation (FLOAT_REP);
1484
1485 FLOAT_REP ::= VAX_Float | IEEE_Float
1486 @end smallexample
1487
1488 @noindent
1489 This pragma is implemented only in the OpenVMS implementation of GNAT@.
1490 It allows control over the internal representation chosen for the predefined
1491 floating point types declared in the packages @code{Standard} and
1492 @code{System}.  For further details on this pragma, see the
1493 DEC Ada Language Reference Manual, section 3.5.7a.  Note that to use this
1494 pragma, the standard runtime libraries must be recompiled.  See the
1495 description of the @code{GNAT LIBRARY} command in the OpenVMS version
1496 of the GNAT Users Guide for details on the use of this command.
1497
1498 @findex Ident
1499 @item pragma Ident
1500 @noindent
1501 Syntax:
1502
1503 @smallexample
1504 pragma Ident (static_string_EXPRESSION);
1505 @end smallexample
1506
1507 @noindent
1508 This pragma provides a string identification in the generated object file,
1509 if the system supports the concept of this kind of identification string.
1510 The maximum permitted length of the string literal is 31 characters.
1511 This pragma is allowed only in the outermost declarative part or
1512 declarative items of a compilation unit.
1513 @cindex OpenVMS
1514 On OpenVMS systems, the effect of the pragma is identical to the effect of
1515 the DEC Ada 83 pragma of the same name. 
1516
1517 @cindex OpenVMS
1518 @findex Import_Exception
1519 @item pragma Import_Exception
1520 @noindent
1521 Syntax:
1522
1523 @smallexample
1524 pragma Import_Exception (
1525      [Internal =>] LOCAL_NAME,
1526   [, [External =>] EXTERNAL_SYMBOL,]
1527   [, [Form     =>] Ada | VMS]
1528   [, [Code     =>] static_integer_EXPRESSION]);
1529
1530 EXTERNAL_SYMBOL ::=
1531   IDENTIFIER
1532 | static_string_EXPRESSION
1533 @end smallexample
1534
1535 @noindent
1536 This pragma is implemented only in the OpenVMS implementation of GNAT@.
1537 It allows OpenVMS conditions (for example, from OpenVMS system services or
1538 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
1539 The pragma specifies that the exception associated with an exception
1540 declaration in an Ada program be defined externally (in non-Ada code).
1541 For further details on this pragma, see the
1542 DEC Ada Language Reference Manual, section 13.9a.3.1.
1543
1544 @findex Import_Function
1545 @item pragma Import_Function @dots{}
1546 @noindent
1547 Syntax:
1548
1549 @smallexample
1550 pragma Import_Function (
1551      [Internal                 =>] LOCAL_NAME,
1552   [, [External                 =>] EXTERNAL_SYMBOL]
1553   [, [Parameter_Types          =>] PARAMETER_TYPES]
1554   [, [Result_Type              =>] SUBTYPE_MARK]
1555   [, [Mechanism                =>] MECHANISM]
1556   [, [Result_Mechanism         =>] MECHANISM_NAME]
1557   [, [First_Optional_Parameter =>] IDENTIFIER]);
1558
1559 EXTERNAL_SYMBOL ::=
1560   IDENTIFIER
1561 | static_string_EXPRESSION
1562
1563 PARAMETER_TYPES ::=
1564   null
1565 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1566
1567 MECHANISM ::=
1568   MECHANISM_NAME
1569 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1570
1571 MECHANISM_ASSOCIATION ::=
1572   [formal_parameter_NAME =>] MECHANISM_NAME
1573
1574 MECHANISM_NAME ::=
1575   Value
1576 | Reference
1577 | Descriptor [([Class =>] CLASS_NAME)]
1578
1579 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1580 @end smallexample
1581
1582 This pragma is used in conjunction with a pragma @code{Import} to
1583 specify additional information for an imported function.  The pragma
1584 @code{Import} (or equivalent pragma @code{Interface}) must precede the
1585 @code{Import_Function} pragma and both must appear in the same
1586 declarative part as the function specification.
1587
1588 The @var{Internal_Name} argument must uniquely designate
1589 the function to which the
1590 pragma applies.  If more than one function name exists of this name in
1591 the declarative part you must use the @code{Parameter_Types} and
1592 @var{Result_Type} parameters to achieve the required unique
1593 designation.  Subtype marks in these parameters must exactly match the
1594 subtypes in the corresponding function specification, using positional
1595 notation to match parameters with subtype marks.
1596
1597 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
1598 parameters to specify passing mechanisms for the
1599 parameters and result.  If you specify a single mechanism name, it
1600 applies to all parameters.  Otherwise you may specify a mechanism on a
1601 parameter by parameter basis using either positional or named
1602 notation.  If the mechanism is not specified, the default mechanism
1603 is used.
1604
1605 @cindex OpenVMS
1606 @cindex Passing by descriptor
1607 Passing by descriptor is supported only on the to OpenVMS ports of GNAT@.
1608
1609 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
1610 It specifies that the designated parameter and all following parameters
1611 are optional, meaning that they are not passed at the generated code
1612 level (this is distinct from the notion of optional parameters in Ada
1613 where the parameters are passed anyway with the designated optional
1614 parameters).  All optional parameters must be of mode @code{IN} and have
1615 default parameter values that are either known at compile time
1616 expressions, or uses of the @code{'Null_Parameter} attribute.
1617
1618 @findex Import_Object
1619 @item pragma Import_Object
1620 @noindent
1621 Syntax:
1622
1623 @smallexample
1624 pragma Import_Object
1625      [Internal =>] LOCAL_NAME,
1626   [, [External =>] EXTERNAL_SYMBOL],
1627   [, [Size     =>] EXTERNAL_SYMBOL])
1628
1629 EXTERNAL_SYMBOL ::=
1630   IDENTIFIER
1631 | static_string_EXPRESSION
1632 @end smallexample
1633
1634 @noindent
1635 This pragma designates an object as imported, and apart from the
1636 extended rules for external symbols, is identical in effect to the use of
1637 the normal @code{Import} pragma applied to an object.  Unlike the
1638 subprogram case, you need not use a separate @code{Import} pragma,
1639 although you may do so (and probably should do so from a portability
1640 point of view).  @var{size} is syntax checked, but otherwise ignored by
1641 GNAT@.
1642
1643 @findex Import_Procedure
1644 @item pragma Import_Procedure
1645 @noindent
1646 Syntax:
1647
1648 @smallexample
1649 pragma Import_Procedure (
1650      [Internal                 =>] LOCAL_NAME,
1651   [, [External                 =>] EXTERNAL_SYMBOL]
1652   [, [Parameter_Types          =>] PARAMETER_TYPES]
1653   [, [Mechanism                =>] MECHANISM]
1654   [, [First_Optional_Parameter =>] IDENTIFIER]);
1655
1656 EXTERNAL_SYMBOL ::=
1657   IDENTIFIER
1658 | static_string_EXPRESSION
1659
1660 PARAMETER_TYPES ::=
1661   null
1662 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1663
1664 MECHANISM ::=
1665   MECHANISM_NAME
1666 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1667
1668 MECHANISM_ASSOCIATION ::=
1669   [formal_parameter_NAME =>] MECHANISM_NAME
1670
1671 MECHANISM_NAME ::=
1672   Value
1673 | Reference
1674 | Descriptor [([Class =>] CLASS_NAME)]
1675
1676 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1677 @end smallexample
1678
1679 @noindent
1680 This pragma is identical to @code{Import_Function} except that it
1681 applies to a procedure rather than a function and the parameters
1682 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1683
1684 @findex Import_Valued_Procedure
1685 @item pragma Import_Valued_Procedure @dots{}
1686 @noindent
1687 Syntax:
1688
1689 @smallexample
1690 pragma Import_Valued_Procedure (
1691      [Internal                 =>] LOCAL_NAME,
1692   [, [External                 =>] EXTERNAL_SYMBOL]
1693   [, [Parameter_Types          =>] PARAMETER_TYPES]
1694   [, [Mechanism                =>] MECHANISM]
1695   [, [First_Optional_Parameter =>] IDENTIFIER]);
1696
1697 EXTERNAL_SYMBOL ::=
1698   IDENTIFIER
1699 | static_string_EXPRESSION
1700
1701 PARAMETER_TYPES ::=
1702   null
1703 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1704
1705 MECHANISM ::=
1706   MECHANISM_NAME
1707 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1708
1709 MECHANISM_ASSOCIATION ::=
1710   [formal_parameter_NAME =>] MECHANISM_NAME
1711
1712 MECHANISM_NAME ::=
1713   Value
1714 | Reference
1715 | Descriptor [([Class =>] CLASS_NAME)]
1716
1717 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1718 @end smallexample
1719
1720 @noindent
1721 This pragma is identical to @code{Import_Procedure} except that the
1722 first parameter of @var{local_name}, which must be present, must be of
1723 mode @code{OUT}, and externally the subprogram is treated as a function
1724 with this parameter as the result of the function.  The purpose of this
1725 capability is to allow the use of @code{OUT} and @code{IN OUT}
1726 parameters in interfacing to external functions (which are not permitted
1727 in Ada functions).  You may optionally use the @code{Mechanism}
1728 parameters to specify passing mechanisms for the parameters.
1729 If you specify a single mechanism name, it applies to all parameters.
1730 Otherwise you may specify a mechanism on a parameter by parameter
1731 basis using either positional or named notation.  If the mechanism is not
1732 specified, the default mechanism is used.
1733
1734 Note that it is important to use this pragma in conjunction with a separate
1735 pragma Import that specifies the desired convention, since otherwise the
1736 default convention is Ada, which is almost certainly not what is required.
1737
1738 @findex Initialize_Scalars
1739 @cindex debugging with Initialize_Scalars
1740 @item pragma Initialize_Scalars
1741 @noindent
1742 Syntax:
1743
1744 @smallexample
1745 pragma Initialize_Scalars;
1746 @end smallexample
1747
1748 @noindent
1749 This pragma is similar to @code{Normalize_Scalars} conceptually but has 
1750 two important differences.  First, there is no requirement for the pragma
1751 to be used uniformly in all units of a partition, in particular, it is fine
1752 to use this just for some or all of the application units of a partition,
1753 without needing to recompile the run-time library.
1754
1755 In the case where some units are compiled with the pragma, and some without,
1756 then a declaration of a variable where the type is defined in package
1757 Standard or is locally declared will always be subject to initialization,
1758 as will any declaration of a scalar variable.  For composite variables,
1759 whether the variable is initialized may also depend on whether the package
1760 in which the type of the variable is declared is compiled with the pragma.
1761
1762 The other important difference is that there is control over the value used
1763 for initializing scalar objects.  At bind time, you can select whether to
1764 initialize with invalid values (like Normalize_Scalars), or with high or
1765 low values, or with a specified bit pattern.  See the users guide for binder
1766 options for specifying these cases.
1767
1768 This means that you can compile a program, and then without having to
1769 recompile the program, you can run it with different values being used
1770 for initializing otherwise uninitialized values, to test if your program
1771 behavior depends on the choice.  Of course the behavior should not change,
1772 and if it does, then most likely you have an erroneous reference to an
1773 uninitialized value.
1774
1775 Note that pragma @code{Initialize_Scalars} is particularly useful in
1776 conjunction with the enhanced validity checking that is now provided
1777 in GNAT, which checks for invalid values under more conditions.
1778 Using this feature (see description of the @code{-gnatv} flag in the
1779 users guide) in conjunction with pragma @code{Initialize_Scalars}
1780 provides a powerful new tool to assist in the detection of problems
1781 caused by uninitialized variables.
1782
1783 @findex Inline_Always
1784 @item pragma Inline_Always
1785 @noindent
1786 Syntax:
1787
1788 @smallexample
1789 pragma Inline_Always (NAME [, NAME]);
1790 @end smallexample
1791
1792 @noindent
1793 Similar to pragma @code{Inline} except that inlining is not subject to
1794 the use of option @code{-gnatn} for inter-unit inlining.
1795
1796 @findex Inline_Generic
1797 @item pragma Inline_Generic
1798 @noindent
1799 Syntax:
1800
1801 @smallexample
1802 pragma Inline_Generic (generic_package_NAME)
1803 @end smallexample
1804
1805 @noindent
1806 This is implemented for compatibility with DEC Ada 83 and is recognized,
1807 but otherwise ignored, by GNAT@.  All generic instantiations are inlined
1808 by default when using GNAT@.
1809
1810 @findex Interface
1811 @item pragma Interface
1812 @noindent
1813 Syntax:
1814
1815 @smallexample
1816 pragma Interface (
1817      [Convention    =>] convention_identifier,
1818      [Entity =>] local_name
1819   [, [External_Name =>] static_string_expression],
1820   [, [Link_Name     =>] static_string_expression]);
1821 @end smallexample
1822
1823 @noindent
1824 This pragma is identical in syntax and semantics to
1825 the standard Ada 95 pragma @code{Import}.  It is provided for compatibility
1826 with Ada 83.  The definition is upwards compatible both with pragma
1827 @code{Interface} as defined in the Ada 83 Reference Manual, and also
1828 with some extended implementations of this pragma in certain Ada 83
1829 implementations.
1830
1831 @findex Interface_Name
1832 @item pragma Interface_Name
1833 @noindent
1834 Syntax:
1835
1836 @smallexample
1837 pragma Interface_Name ( 
1838      [Entity        =>] LOCAL_NAME
1839   [, [External_Name =>] static_string_EXPRESSION]
1840   [, [Link_Name     =>] static_string_EXPRESSION]);
1841 @end smallexample
1842
1843 @noindent
1844 This pragma provides an alternative way of specifying the interface name
1845 for an interfaced subprogram, and is provided for compatibility with Ada
1846 83 compilers that use the pragma for this purpose.  You must provide at
1847 least one of @var{External_Name} or @var{Link_Name}.
1848
1849 @findex License
1850 @item pragma License
1851 @cindex License checking
1852 @noindent
1853 Syntax:
1854
1855 @smallexample
1856 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
1857 @end smallexample
1858
1859 @noindent
1860 This pragma is provided to allow automated checking for appropriate license
1861 conditions with respect to the standard and modified GPL@.  A pragma @code{License},
1862 which is a configuration pragma that typically appears at the start of a
1863 source file or in a separate @file{gnat.adc} file, specifies the licensing
1864 conditions of a unit as follows:
1865
1866 @itemize @bullet
1867 @item Unrestricted
1868 This is used for a unit that can be freely used with no license restrictions.
1869 Examples of such units are public domain units, and units from the Ada
1870 Reference Manual.
1871
1872 @item GPL
1873 This is used for a unit that is licensed under the unmodified GPL, and which
1874 therefore cannot be @code{with}'ed by a restricted unit.
1875
1876 @item Modified_GPL
1877 This is used for a unit licensed under the GNAT modified GPL that includes
1878 a special exception paragraph that specifically permits the inclusion of
1879 the unit in programs without requiring the entire program to be released
1880 under the GPL@.  This is the license used for the GNAT run-time which ensures
1881 that the run-time can be used freely in any program without GPL concerns.
1882
1883 @item Restricted
1884 This is used for a unit that is restricted in that it is not permitted to
1885 depend on units that are licensed under the GPL@.  Typical examples are
1886 proprietary code that is to be released under more restrictive license
1887 conditions.  Note that restricted units are permitted to @code{with} units
1888 which are licensed under the modified GPL (this is the whole point of the
1889 modified GPL).
1890
1891 @end itemize
1892
1893 @noindent
1894 Normally a unit with no @code{License} pragma is considered to have an
1895 unknown license, and no checking is done.  However, standard GNAT headers
1896 are recognized, and license information is derived from them as follows.
1897
1898 @itemize @bullet
1899
1900 A GNAT license header starts with a line containing 78 hyphens.  The following
1901 comment text is searched for the appearence of any of the following strings.
1902
1903 If the string ``GNU General Public License'' is found, then the unit is assumed
1904 to have GPL license, unless the string ``As a special exception'' follows, in
1905 which case the license is assumed to be modified GPL@.
1906
1907 If one of the strings
1908 ``This specification is adapated from the Ada Semantic Interface'' or
1909 ``This specification is derived from the Ada Reference Manual'' is found
1910 then the unit is assumed to be unrestricted.
1911 @end itemize
1912
1913 @noindent
1914 These default actions means that a program with a restricted license pragma
1915 will automatically get warnings if a GPL unit is inappropriately
1916 @code{with}'ed.  For example, the program:
1917
1918 @smallexample
1919 with Sem_Ch3;
1920 with GNAT.Sockets;
1921 procedure Secret_Stuff is
1922 @dots{}
1923 end Secret_Stuff
1924 @end smallexample
1925
1926 @noindent
1927 if compiled with pragma @code{License} (@code{Restricted}) in a
1928 @file{gnat.adc} file will generate the warning:
1929
1930 @smallexample
1931 1.  with Sem_Ch3;
1932         |
1933    >>> license of withed unit "Sem_Ch3" is incompatible
1934
1935 2.  with GNAT.Sockets;
1936 3.  procedure Secret_Stuff is
1937 @end smallexample
1938 @noindent
1939 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
1940 compiler and is licensed under the
1941 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 
1942 run time, and is therefore licensed under the modified GPL@.
1943
1944 @findex Link_With
1945 @item pragma Link_With
1946 @noindent
1947 Syntax:
1948
1949 @smallexample
1950 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
1951 @end smallexample
1952
1953 @noindent
1954 This pragma is provided for compatibility with certain Ada 83 compilers.
1955 It has exactly the same effect as pragma @code{Linker_Options} except
1956 that spaces occurring within one of the string expressions are treated
1957 as separators. For example, in the following case:
1958
1959 @smallexample
1960 pragma Link_With ("-labc -ldef");
1961 @end smallexample
1962
1963 @noindent
1964 results in passing the strings @code{-labc} and @code{-ldef} as two
1965 separate arguments to the linker. In addition pragma Link_With allows
1966 multiple arguments, with the same effect as successive pragmas.
1967
1968 @findex Linker_Alias
1969 @item pragma Linker_Alias
1970 @noindent
1971 Syntax:
1972
1973 @smallexample
1974 pragma Linker_Alias (
1975   [Entity =>] LOCAL_NAME
1976   [Alias  =>] static_string_EXPRESSION);
1977 @end smallexample
1978
1979 @noindent
1980 This pragma establishes a linker alias for the given named entity.  For
1981 further details on the exact effect, consult the GCC manual.
1982
1983 @findex Linker_Section
1984 @item pragma Linker_Section
1985 @noindent
1986 Syntax:
1987
1988 @smallexample
1989 pragma Linker_Section (
1990   [Entity  =>] LOCAL_NAME
1991   [Section =>] static_string_EXPRESSION);
1992 @end smallexample
1993
1994 @noindent
1995 This pragma specifies the name of the linker section for the given entity.
1996 For further details on the exact effect, consult the GCC manual.
1997
1998 @findex No_Run_Time
1999 @item pragma No_Run_Time
2000 @noindent
2001 Syntax:
2002
2003 @smallexample
2004 pragma No_Run_Time;
2005 @end smallexample
2006
2007 @noindent
2008 This is a configuration pragma that makes sure the user code does not
2009 use nor need anything from the GNAT run time.  This is mostly useful in
2010 context where code certification is required.  Please consult the 
2011 @cite{GNAT Pro High-Integrity Edition User's Guide} for additional information.
2012
2013 @findex Normalize_Scalars
2014 @item pragma Normalize_Scalars
2015 @noindent
2016 Syntax:
2017
2018 @smallexample
2019 pragma Normalize_Scalars;
2020 @end smallexample
2021
2022 @noindent
2023 This is a language defined pragma which is fully implemented in GNAT@.  The
2024 effect is to cause all scalar objects that are not otherwise initialized
2025 to be initialized.  The initial values are implementation dependent and
2026 are as follows:
2027
2028 @table @code
2029 @item Standard.Character
2030 @noindent
2031 Objects whose root type is Standard.Character are initialized to
2032 Character'Last.  This will be out of range of the subtype only if
2033 the subtype range excludes this value.
2034
2035 @item Standard.Wide_Character
2036 @noindent
2037 Objects whose root type is Standard.Wide_Character are initialized to
2038 Wide_Character'Last.  This will be out of range of the subtype only if
2039 the subtype range excludes this value.
2040
2041 @item Integer types
2042 @noindent
2043 Objects of an integer type are initialized to base_type'First, where
2044 base_type is the base type of the object type.  This will be out of range
2045 of the subtype only if the subtype range excludes this value.  For example,
2046 if you declare the subtype:
2047
2048 @smallexample
2049 subtype Ityp is integer range 1 .. 10;
2050 @end smallexample
2051
2052 @noindent
2053 then objects of type x will be initialized to Integer'First, a negative
2054 number that is certainly outside the range of subtype @code{Ityp}.
2055
2056 @item Real types
2057 Objects of all real types (fixed and floating) are initialized to
2058 base_type'First, where base_Type is the base type of the object type.
2059 This will be out of range of the subtype only if the subtype range
2060 excludes this value.
2061
2062 @item Modular types
2063 Objects of a modular type are initialized to typ'Last.  This will be out
2064 of range of the subtype only if the subtype excludes this value.
2065
2066 @item Enumeration types
2067 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
2068 the value @code{2 ** typ'Size - 1}.  This will be out of range of the enumeration
2069 subtype in all cases except where the subtype contains exactly
2070 2**8, 2**16, or 2**32 elements.
2071
2072 @end table
2073
2074 @cindex OpenVMS
2075 @findex Long_Float
2076 @item pragma Long_Float
2077 @noindent
2078 Syntax:
2079
2080 @smallexample
2081 pragma Long_Float (FLOAT_FORMAT);
2082
2083 FLOAT_FORMAT ::= D_Float | G_Float
2084 @end smallexample
2085
2086 @noindent
2087 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2088 It allows control over the internal representation chosen for the predefined
2089 type @code{Long_Float} and for floating point type representations with
2090 @code{digits} specified in the range 7 through 15.
2091 For further details on this pragma, see the
2092 @cite{DEC Ada Language Reference Manual}, section 3.5.7b.  Note that to use this
2093 pragma, the standard runtime libraries must be recompiled.  See the
2094 description of the @code{GNAT LIBRARY} command in the OpenVMS version
2095 of the GNAT User's Guide for details on the use of this command.
2096
2097 @findex Machine_Attribute
2098 @item pragma Machine_Attribute @dots{}
2099 @noindent
2100 Syntax:
2101
2102 @smallexample
2103 pragma Machine_Attribute (
2104   [Attribute_Name =>] string_EXPRESSION,
2105   [Entity         =>] LOCAL_NAME);
2106 @end smallexample
2107
2108 Machine dependent attributes can be specified for types and/or
2109 declarations.  Currently only subprogram entities are supported.  This
2110 pragma is semantically equivalent to 
2111 @code{__attribute__((@var{string_expression}))} in GNU C, 
2112 where @code{@var{string_expression}} is
2113 recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and
2114 @code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the
2115 configuration header file @file{tm.h} for each machine.  See the GCC
2116 manual for further information.
2117
2118 @cindex OpenVMS
2119 @findex Main_Storage
2120 @item pragma Main_Storage
2121 @noindent
2122 Syntax:
2123
2124 @smallexample
2125 pragma Main_Storage
2126   (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
2127
2128 MAIN_STORAGE_OPTION ::=
2129   [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
2130 | [TOP_GUARD       =>] static_SIMPLE_EXPRESSION
2131
2132 @end smallexample
2133
2134 @noindent
2135 This pragma is provided for compatibility with OpenVMS Vax Systems.  It has
2136 no effect in GNAT, other than being syntax checked.  Note that the pragma
2137 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
2138
2139 @findex No_Return
2140 @item pragma No_Return
2141 @noindent
2142 Syntax:
2143
2144 @smallexample
2145 pragma No_Return (procedure_LOCAL_NAME);
2146 @end smallexample
2147
2148 @noindent
2149 @var{procedure_local_NAME} must refer to one or more procedure
2150 declarations in the current declarative part.  A procedure to which this
2151 pragma is applied may not contain any explicit @code{return} statements,
2152 and also may not contain any implicit return statements from falling off
2153 the end of a statement sequence.  One use of this pragma is to identify
2154 procedures whose only purpose is to raise an exception.
2155
2156 Another use of this pragma is to suppress incorrect warnings about
2157 missing returns in functions, where the last statement of a function
2158 statement sequence is a call to such a procedure.
2159
2160 @findex Passive
2161 @item pragma Passive
2162 @noindent
2163 Syntax:
2164
2165 @smallexample
2166 pragma Passive ([Semaphore | No]);
2167 @end smallexample
2168
2169 @noindent
2170 Syntax checked, but otherwise ignored by GNAT@.  This is recognized for
2171 compatibility with DEC Ada 83 implementations, where it is used within a
2172 task definition to request that a task be made passive.  If the argument
2173 @code{Semaphore} is present, or no argument is omitted, then DEC Ada 83
2174 treats the pragma as an assertion that the containing task is passive
2175 and that optimization of context switch with this task is permitted and
2176 desired.  If the argument @code{No} is present, the task must not be
2177 optimized.  GNAT does not attempt to optimize any tasks in this manner
2178 (since protected objects are available in place of passive tasks).
2179
2180 @findex Polling 
2181 @item pragma Polling
2182 @noindent
2183 Syntax:
2184
2185 @smallexample
2186 pragma Polling (ON | OFF);
2187 @end smallexample
2188
2189 @noindent
2190 This pragma controls the generation of polling code.  This is normally off.
2191 If @code{pragma Polling (ON)} is used then periodic calls are generated to
2192 the routine @code{Ada.Exceptions.Poll}.  This routine is a separate unit in the
2193 runtime library, and can be found in file @file{a-excpol.adb}.
2194
2195 Pragma @code{Polling} can appear as a configuration pragma (for example it can be
2196 placed in the @file{gnat.adc} file) to enable polling globally, or it can be used
2197 in the statement or declaration sequence to control polling more locally.
2198
2199 A call to the polling routine is generated at the start of every loop and
2200 at the start of every subprogram call.  This guarantees that the @code{Poll}
2201 routine is called frequently, and places an upper bound (determined by
2202 the complexity of the code) on the period between two @code{Poll} calls.
2203
2204 The primary purpose of the polling interface is to enable asynchronous 
2205 aborts on targets that cannot otherwise support it (for example Windows
2206 NT), but it may be used for any other purpose requiring periodic polling.
2207 The standard version is null, and can be replaced by a user program.  This
2208 will require re-compilation of the @code{Ada.Exceptions} package that can be found
2209 in files @file{a-except.ads} and @file{a-except.adb}.
2210
2211 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
2212 distribution) is used to enable the asynchronous abort capability on
2213 targets that do not normally support the capability.  The version of @code{Poll}
2214 in this file makes a call to the appropriate runtime routine to test for
2215 an abort condition.
2216
2217 Note that polling can also be enabled by use of the @code{-gnatP} switch.  See
2218 the @cite{GNAT User's Guide} for details.
2219
2220 @findex Propagate_Exceptions
2221 @cindex Zero Cost Exceptions
2222 @item pragma Propagate_Exceptions
2223 @noindent
2224 Syntax:
2225
2226 @smallexample
2227 pragma Propagate_Exceptions (subprogram_LOCAL_NAME);
2228 @end smallexample
2229
2230 @noindent
2231 This pragma indicates that the given entity, which is the name of an
2232 imported foreign-language subprogram may receive an Ada exception, 
2233 and that the exception should be propagated.  It is relevant only if
2234 zero cost exception handling is in use, and is thus never needed if
2235 the alternative @code{longjmp} / @code{setjmp} implementation of exceptions is used
2236 (although it is harmless to use it in such cases).
2237
2238 The implementation of fast exceptions always properly propagates
2239 exceptions through Ada code, as described in the Ada Reference Manual.
2240 However, this manual is silent about the propagation of exceptions
2241 through foreign code.  For example, consider the
2242 situation where @code{P1} calls
2243 @code{P2}, and @code{P2} calls @code{P3}, where
2244 @code{P1} and @code{P3} are in Ada, but @code{P2} is in C@.
2245 @code{P3} raises an Ada exception.  The question is whether or not
2246 it will be propagated through @code{P2} and can be handled in 
2247 @code{P1}.
2248
2249 For the @code{longjmp} / @code{setjmp} implementation of exceptions, the answer is
2250 always yes.  For some targets on which zero cost exception handling
2251 is implemented, the answer is also always yes.  However, there are
2252 some targets, notably in the current version all x86 architecture
2253 targets, in which the answer is that such propagation does not
2254 happen automatically.  If such propagation is required on these
2255 targets, it is mandatory to use @code{Propagate_Exceptions} to 
2256 name all foreign language routines through which Ada exceptions
2257 may be propagated.
2258
2259 @findex Psect_Object
2260 @item pragma Psect_Object
2261 @noindent
2262 Syntax:
2263
2264 @smallexample
2265 pragma Psect_Object
2266      [Internal =>] LOCAL_NAME,
2267   [, [External =>] EXTERNAL_SYMBOL]
2268   [, [Size     =>] EXTERNAL_SYMBOL]
2269
2270 EXTERNAL_SYMBOL ::=
2271   IDENTIFIER
2272 | static_string_EXPRESSION
2273 @end smallexample
2274
2275 @noindent
2276 This pragma is identical in effect to pragma @code{Common_Object}.
2277
2278 @findex Pure_Function
2279 @item pragma Pure_Function
2280 @noindent
2281 Syntax:
2282
2283 @smallexample
2284 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
2285 @end smallexample
2286
2287 This pragma appears in the same declarative part as a function
2288 declaration (or a set of function declarations if more than one
2289 overloaded declaration exists, in which case the pragma applies
2290 to all entities).  If specifies that the function @code{Entity} is
2291 to be considered pure for the purposes of code generation.  This means
2292 that the compiler can assume that there are no side effects, and
2293 in particular that two calls with identical arguments produce the
2294 same result.  It also means that the function can be used in an
2295 address clause.
2296
2297 Note that, quite deliberately, there are no static checks to try
2298 to ensure that this promise is met, so @code{Pure_Function} can be used
2299 with functions that are conceptually pure, even if they do modify
2300 global variables.  For example, a square root function that is
2301 instrumented to count the number of times it is called is still
2302 conceptually pure, and can still be optimized, even though it
2303 modifies a global variable (the count).  Memo functions are another
2304 example (where a table of previous calls is kept and consulted to
2305 avoid re-computation).
2306
2307 @findex Pure
2308 Note: Most functions in a @code{Pure} package are automatically pure, and
2309 there is no need to use pragma @code{Pure_Function} for such functions.  An
2310 exception is any function that has at least one formal of type
2311 @code{System.Address} or a type derived from it.  Such functions are not
2312 considered pure by default, since the compiler assumes that the
2313 @code{Address} parameter may be functioning as a pointer and that the
2314 referenced data may change even if the address value does not.  The use
2315 of pragma @code{Pure_Function} for such a function will override this default
2316 assumption, and cause the compiler to treat such a function as pure.
2317
2318 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
2319 applies to the underlying renamed function.  This can be used to
2320 disambiguate cases of overloading where some but not all functions
2321 in a set of overloaded functions are to be designated as pure.
2322
2323 @findex Ravenscar
2324 @item pragma Ravenscar
2325 @noindent
2326 Syntax:
2327
2328 @smallexample
2329 pragma Ravenscar
2330 @end smallexample
2331
2332 @noindent
2333 A configuration pragma that establishes the following set of restrictions:
2334
2335 @table @code
2336 @item No_Abort_Statements
2337 [RM D.7] There are no abort_statements, and there are 
2338 no calls to Task_Identification.Abort_Task.
2339
2340 @item No_Select_Statements
2341 There are no select_statements.
2342
2343 @item No_Task_Hierarchy
2344 [RM D.7] All (non-environment) tasks depend 
2345 directly on the environment task of the partition.  
2346
2347 @item No_Task_Allocators
2348 [RM D.7] There are no allocators for task types
2349 or types containing task subcomponents.
2350
2351 @item No_Dynamic_Priorities
2352 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
2353
2354 @item No_Terminate_Alternatives
2355 [RM D.7] There are no selective_accepts with terminate_alternatives
2356
2357 @item No_Dynamic_Interrupts
2358 There are no semantic dependencies on Ada.Interrupts.
2359
2360 @item No_Protected_Type_Allocators
2361 There are no allocators for protected types or
2362 types containing protected subcomponents.
2363
2364 @item No_Local_Protected_Objects
2365 Protected objects and access types that designate 
2366 such objects shall be declared only at library level.
2367
2368 @item No_Requeue
2369 Requeue statements are not allowed.
2370
2371 @item No_Calendar
2372 There are no semantic dependencies on the package Ada.Calendar.
2373
2374 @item No_Relative_Delay
2375 There are no delay_relative_statements.
2376
2377 @item No_Task_Attributes
2378 There are no semantic dependencies on the Ada.Task_Attributes package and
2379 there are no references to the attributes Callable and Terminated [RM 9.9].
2380
2381 @item Static_Storage_Size
2382 The expression for pragma Storage_Size is static.
2383
2384 @item Boolean_Entry_Barriers
2385 Entry barrier condition expressions shall be boolean 
2386 objects which are declared in the protected type 
2387 which contains the entry.
2388
2389 @item Max_Asynchronous_Select_Nesting = 0
2390 [RM D.7] Specifies the maximum dynamic nesting level of asynchronous_selects.
2391 A value of zero prevents the use of any asynchronous_select.
2392
2393 @item Max_Task_Entries = 0
2394 [RM D.7] Specifies the maximum number of entries
2395 per task.  The bounds of every entry family
2396 of a task unit shall be static, or shall be
2397 defined by a discriminant of a subtype whose
2398 corresponding bound is static.  A value of zero
2399 indicates that no rendezvous are possible.  For
2400 the Ravenscar pragma, the value of Max_Task_Entries is always
2401 0 (zero).
2402
2403 @item Max_Protected_Entries = 1
2404 [RM D.7] Specifies the maximum number of entries per 
2405 protected type.  The bounds of every entry family of 
2406 a protected unit shall be static, or shall be defined 
2407 by a discriminant of a subtype whose corresponding 
2408 bound is static.  For the Ravenscar pragma the value of 
2409 Max_Protected_Entries is always 1.
2410
2411 @item Max_Select_Alternatives = 0
2412 [RM D.7] Specifies the maximum number of alternatives in a selective_accept.
2413 For the Ravenscar pragma the value if always 0.
2414
2415 @item No_Task_Termination
2416 Tasks which terminate are erroneous.
2417
2418 @item No_Entry_Queue
2419 No task can be queued on a protected entry.  Note that this restrictions is
2420 checked at run time.  The violation of this restriction generates a
2421 Program_Error exception.
2422 @end table
2423
2424 @noindent
2425 This set of restrictions corresponds to the definition of the ``Ravenscar
2426 Profile'' for limited tasking, devised and published by the @cite{International
2427 Real-Time Ada Workshop}, 1997. 
2428
2429 The above set is a superset of the restrictions provided by pragma
2430 @code{Restricted_Run_Time}, it includes six additional restrictions
2431 (@code{Boolean_Entry_Barriers}, @code{No_Select_Statements},
2432 @code{No_Calendar}, @code{Static_Storage_Size},
2433 @code{No_Relative_Delay} and @code{No_Task_Termination}).  This means
2434 that pragma @code{Ravenscar}, like the pragma @code{Restricted_Run_Time}, automatically
2435 causes the use of a simplified, more efficient version of the tasking
2436 run-time system.
2437
2438 @findex Restricted_Run_Time
2439 @item pragma Restricted_Run_Time
2440 @noindent
2441 Syntax:
2442
2443 @smallexample
2444 pragma Restricted_Run_Time
2445 @end smallexample
2446
2447 @noindent
2448 A configuration pragma that establishes the following set of restrictions:
2449
2450 @itemize @bullet
2451 @item No_Abort_Statements
2452 @item No_Asynchronous_Control
2453 @item No_Entry_Queue
2454 @item No_Task_Hierarchy
2455 @item No_Task_Allocators
2456 @item No_Dynamic_Priorities
2457 @item No_Terminate_Alternatives
2458 @item No_Dynamic_Interrupts
2459 @item No_Protected_Type_Allocators
2460 @item No_Local_Protected_Objects
2461 @item No_Requeue
2462 @item No_Task_Attributes
2463 @item Max_Asynchronous_Select_Nesting =  0
2464 @item Max_Task_Entries =  0
2465 @item Max_Protected_Entries = 1
2466 @item Max_Select_Alternatives = 0
2467 @end itemize
2468
2469 @noindent
2470 This set of restrictions causes the automatic selection of a simplified
2471 version of the run time that provides improved performance for the
2472 limited set of tasking functionality permitted by this set of restrictions.
2473
2474 @findex Share_Generic
2475 @item pragma Share_Generic
2476 @noindent
2477 Syntax:
2478
2479 @smallexample
2480 pragma Share_Generic (NAME @{, NAME@});
2481 @end smallexample
2482
2483 @noindent
2484 This pragma is recognized for compatibility with other Ada compilers
2485 but is ignored by GNAT@.  GNAT does not provide the capability for
2486 sharing of generic code.  All generic instantiations result in making
2487 an inlined copy of the template with appropriate substitutions.
2488
2489 @findex Source_File_Name
2490 @item pragma Source_File_Name
2491 @noindent
2492 Syntax:
2493
2494 @smallexample
2495 pragma Source_File_Name (
2496   [Unit_Name   =>] unit_NAME,
2497   Spec_File_Name =>  STRING_LITERAL);
2498
2499 pragma Source_File_Name (
2500   [Unit_Name   =>] unit_NAME,
2501   Body_File_Name =>  STRING_LITERAL);
2502 @end smallexample
2503
2504 @noindent
2505 Use this to override the normal naming convention.  It is a configuration
2506 pragma, and so has the usual applicability of configuration pragmas
2507 (i.e.@: it applies to either an entire partition, or to all units in a
2508 compilation, or to a single unit, depending on how it is used.
2509 @var{unit_name} is mapped to @var{file_name_literal}.  The identifier for
2510 the second argument is required, and indicates whether this is the file
2511 name for the spec or for the body.
2512
2513 Another form of the @code{Source_File_Name} pragma allows
2514 the specification of patterns defining alternative file naming schemes
2515 to apply to all files. 
2516
2517 @smallexample
2518 pragma Source_File_Name
2519   (Spec_File_Name => STRING_LITERAL
2520    [,Casing => CASING_SPEC]
2521    [,Dot_Replacement => STRING_LITERAL]);
2522
2523 pragma Source_File_Name
2524   (Body_File_Name => STRING_LITERAL
2525    [,Casing => CASING_SPEC]
2526    [,Dot_Replacement => STRING_LITERAL]);
2527
2528 pragma Source_File_Name
2529   (Subunit_File_Name => STRING_LITERAL
2530    [,Casing => CASING_SPEC]
2531    [,Dot_Replacement => STRING_LITERAL]);
2532
2533 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
2534 @end smallexample
2535
2536 @noindent
2537 The first argument is a pattern that contains a single asterisk indicating
2538 the point at which the unit name is to be inserted in the pattern string
2539 to form the file name.  The second argument is optional.  If present it
2540 specifies the casing of the unit name in the resulting file name string.
2541 The default is lower case.  Finally the third argument allows for systematic
2542 replacement of any dots in the unit name by the specified string literal.
2543
2544 For more details on the use of the @code{Source_File_Name} pragma,
2545 see the sections ``Using Other File Names'' and 
2546 ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
2547
2548 @findex Source_Reference
2549 @item pragma Source_Reference
2550 @noindent
2551 Syntax:
2552
2553 @smallexample
2554 pragma Source_Reference (INTEGER_LITERAL,
2555                          STRING_LITERAL);
2556 @end smallexample
2557
2558 @noindent
2559 This pragma must appear as the first line of a source file.
2560 @var{integer_literal} is the logical line number of the line following
2561 the pragma line (for use in error messages and debugging
2562 information).  @var{string_literal} is a static string constant that
2563 specifies the file name to be used in error messages and debugging
2564 information.  This is most notably used for the output of @code{gnatchop}
2565 with the @code{-r} switch, to make sure that the original unchopped
2566 source file is the one referred to.
2567
2568 The second argument must be a string literal, it cannot be a static
2569 string expression other than a string literal.  This is because its value
2570 is needed for error messages issued by all phases of the compiler.
2571
2572 @findex Stream_Convert
2573 @item pragma Stream_Convert
2574 @noindent
2575 Syntax:
2576
2577 @smallexample
2578 pragma Stream_Convert (
2579   [Entity =>] type_LOCAL_NAME,
2580   [Read   =>] function_NAME,
2581   [Write  =>] function NAME);
2582 @end smallexample
2583
2584 @noindent
2585 This pragma provides an efficient way of providing stream functions for
2586 types defined in packages.  Not only is it simpler to use than declaring
2587 the necessary functions with attribute representation clauses, but more
2588 significantly, it allows the declaration to made in such a way that the
2589 stream packages are not loaded unless they are needed.  The use of
2590 the Stream_Convert pragma adds no overhead at all, unless the stream
2591 attributes are actually used on the designated type.
2592
2593 The first argument specifies the type for which stream functions are
2594 provided.  The second parameter provides a function used to read values
2595 of this type.  It must name a function whose argument type may be any
2596 subtype, and whose returned type must be the type given as the first
2597 argument to the pragma.
2598
2599 The meaning of the @var{Read}
2600 parameter is that if a stream attribute directly
2601 or indirectly specifies reading of the type given as the first parameter,
2602 then a value of the type given as the argument to the Read function is
2603 read from the stream, and then the Read function is used to convert this
2604 to the required target type.
2605
2606 Similarly the @var{Write} parameter specifies how to treat write attributes
2607 that directly or indirectly apply to the type given as the first parameter.
2608 It must have an input parameter of the type specified by the first parameter,
2609 and the return type must be the same as the input type of the Read function.
2610 The effect is to first call the Write function to convert to the given stream
2611 type, and then write the result type to the stream.
2612
2613 The Read and Write functions must not be overloaded subprograms.  If necessary
2614 renamings can be supplied to meet this requirement.
2615 The usage of this attribute is best illustrated by a simple example, taken
2616 from the GNAT implementation of package Ada.Strings.Unbounded:
2617
2618 @smallexample
2619 function To_Unbounded (S : String)
2620            return Unbounded_String
2621   renames To_Unbounded_String;
2622
2623 pragma Stream_Convert
2624   (Unbounded_String, To_Unbounded, To_String);
2625 @end smallexample
2626
2627 @noindent
2628 The specifications of the referenced functions, as given in the Ada 95
2629 Reference Manual are:
2630
2631 @smallexample
2632 function To_Unbounded_String (Source : String)
2633   return Unbounded_String;
2634
2635 function To_String (Source : Unbounded_String)
2636   return String;
2637 @end smallexample
2638
2639 @noindent
2640 The effect is that if the value of an unbounded string is written to a
2641 stream, then the representation of the item in the stream is in the same
2642 format used for @code{Standard.String}, and this same representation is
2643 expected when a value of this type is read from the stream.
2644
2645 @findex Style_Checks
2646 @item pragma Style_Checks
2647 @noindent
2648 Syntax:
2649
2650 @smallexample
2651 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
2652                      On | Off [, LOCAL_NAME]);
2653 @end smallexample
2654
2655 @noindent
2656 This pragma is used in conjunction with compiler switches to control the
2657 built in style checking provided by GNAT@.  The compiler switches, if set
2658 provide an initial setting for the switches, and this pragma may be used
2659 to modify these settings, or the settings may be provided entirely by
2660 the use of the pragma.  This pragma can be used anywhere that a pragma
2661 is legal, including use as a configuration pragma (including use in
2662 the @file{gnat.adc} file).
2663
2664 The form with a string literal specifies which style options are to be
2665 activated.  These are additive, so they apply in addition to any previously
2666 set style check options.  The codes for the options are the same as those
2667 used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}.
2668 For example the following two methods can be used to enable
2669 layout checking:
2670
2671 @smallexample
2672 pragma Style_Checks ("l");
2673 gcc -c -gnatyl @dots{}
2674 @end smallexample
2675
2676 @noindent
2677 The form ALL_CHECKS activates all standard checks (its use is equivalent
2678 to the use of the @code{gnaty} switch with no options.  See GNAT User's
2679 Guide for details.
2680
2681 The forms with @code{Off} and @code{On}
2682 can be used to temporarily disable style checks
2683 as shown in the following example:
2684
2685 @smallexample
2686 @iftex
2687 @leftskip=0cm
2688 @end iftex
2689 pragma Style_Checks ("k"); -- requires keywords in lower case
2690 pragma Style_Checks (Off); -- turn off style checks
2691 NULL;                      -- this will not generate an error message
2692 pragma Style_Checks (On);  -- turn style checks back on
2693 NULL;                      -- this will generate an error message
2694 @end smallexample
2695
2696 @noindent
2697 Finally the two argument form is allowed only if the first argument is
2698 @code{On} or @code{Off}.  The effect is to turn of semantic style checks
2699 for the specified entity, as shown in the following example:
2700
2701 @smallexample
2702 @iftex
2703 @leftskip=0cm
2704 @end iftex
2705 pragma Style_Checks ("r"); -- require consistency of identifier casing
2706 Arg : Integer;
2707 Rf1 : Integer := ARG;      -- incorrect, wrong case
2708 pragma Style_Checks (Off, Arg);
2709 Rf2 : Integer := ARG;      -- OK, no error
2710 @end smallexample
2711
2712 @findex Subtitle
2713 @item pragma Subtitle
2714 @noindent
2715 Syntax:
2716
2717 @smallexample
2718 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
2719 @end smallexample
2720
2721 @noindent
2722 This pragma is recognized for compatibility with other Ada compilers
2723 but is ignored by GNAT@.
2724
2725 @findex Suppress_All
2726 @item pragma Suppress_All
2727 @noindent
2728 Syntax:
2729
2730 @smallexample
2731 pragma Suppress_All;
2732 @end smallexample
2733
2734 @noindent
2735 This pragma can only appear immediately following a compilation
2736 unit.  The effect is to apply @code{Suppress (All_Checks)} to the unit
2737 which it follows.  This pragma is implemented for compatibility with DEC
2738 Ada 83 usage.  The use of pragma @code{Suppress (All_Checks)} as a normal
2739 configuration pragma is the preferred usage in GNAT@.
2740
2741 @findex Suppress_Initialization
2742 @cindex Suppressing initialization
2743 @cindex Initialization, suppression of
2744 @item pragma Suppress_Initialization
2745 @noindent
2746 Syntax:
2747
2748 @smallexample
2749 pragma Suppress_Initialization ([Entity =>] type_Name);
2750 @end smallexample
2751
2752 @noindent
2753 This pragma suppresses any implicit or explicit initialization
2754 associated with the given type name for all variables of this type.
2755
2756 @findex Task_Info
2757 @item pragma Task_Info
2758 @noindent
2759 Syntax
2760
2761 @smallexample
2762 pragma Task_Info (EXPRESSION);
2763 @end smallexample
2764
2765 @noindent
2766 This pragma appears within a task definition (like pragma
2767 @code{Priority}) and applies to the task in which it appears.  The
2768 argument must be of type @code{System.Task_Info.Task_Info_Type}.
2769 The @code{Task_Info} pragma provides system dependent control over
2770 aspect of tasking implementation, for example, the ability to map
2771 tasks to specific processors.  For details on the facilities available
2772 for the version of GNAT that you are using, see the documentation
2773 in the specification of package System.Task_Info in the runtime
2774 library.
2775
2776 @findex Task_Name
2777 @item pragma Task_Name
2778 @noindent
2779 Syntax
2780
2781 @smallexample
2782 pragma Task_Name (string_EXPRESSION);
2783 @end smallexample
2784
2785 @noindent
2786 This pragma appears within a task definition (like pragma
2787 @code{Priority}) and applies to the task in which it appears.  The
2788 argument must be of type String, and provides a name to be used for
2789 the task instance when the task is created.  Note that this expression
2790 is not required to be static, and in particular, it can contain
2791 references to task discriminants.  This facility can be used to
2792 provide different names for different tasks as they are created,
2793 as illustrated in the example below.
2794
2795 The task name is recorded internally in the run-time structures
2796 and is accessible to tools like the debugger.  In addition the
2797 routine @code{Ada.Task_Identification.Image} will return this
2798 string, with a unique task address appended.
2799
2800 @smallexample
2801 --  Example of the use of pragma Task_Name
2802
2803 with Ada.Task_Identification;
2804 use Ada.Task_Identification;
2805 with Text_IO; use Text_IO;
2806 procedure t3 is
2807
2808    type Astring is access String;
2809
2810    task type Task_Typ (Name : access String) is
2811       pragma Task_Name (Name.all);
2812    end Task_Typ;
2813    
2814    task body Task_Typ is
2815       Nam : constant String := Image (Current_Task);
2816    begin
2817       Put_Line ("-->" & Nam (1 .. 14) & "<--");
2818    end Task_Typ;
2819    
2820    type Ptr_Task is access Task_Typ;
2821    Task_Var : Ptr_Task;
2822
2823 begin
2824    Task_Var :=
2825      new Task_Typ (new String'("This is task 1"));
2826    Task_Var :=
2827      new Task_Typ (new String'("This is task 2"));
2828 end;
2829 @end smallexample
2830
2831 @findex Task_Storage
2832 @item pragma Task_Storage
2833 Syntax:
2834
2835 @smallexample
2836 pragma Task_Storage
2837   [Task_Type =>] LOCAL_NAME,
2838   [Top_Guard =>] static_integer_EXPRESSION);
2839 @end smallexample
2840
2841 This pragma specifies the length of the guard area for tasks.  The guard
2842 area is an additional storage area allocated to a task.  A value of zero
2843 means that either no guard area is created or a minimal guard area is
2844 created, depending on the target.  This pragma can appear anywhere a
2845 @code{Storage_Size} attribute definition clause is allowed for a task
2846 type.
2847
2848 @findex Time_Slice
2849 @item pragma Time_Slice
2850 @noindent
2851 Syntax:
2852
2853 @smallexample
2854 pragma Time_Slice (static_duration_EXPRESSION);
2855 @end smallexample
2856
2857 @noindent
2858 For implementations of GNAT on operating systems where it is possible
2859 to supply a time slice value, this pragma may be used for this purpose.
2860 It is ignored if it is used in a system that does not allow this control,
2861 or if it appears in other than the main program unit.
2862 @cindex OpenVMS
2863 Note that the effect of this pragma is identical to the effect of the
2864 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
2865
2866 @findex Title
2867 @item pragma Title
2868 @noindent
2869 Syntax:
2870
2871 @smallexample
2872 pragma Title (TITLING_OPTION [, TITLING OPTION]);
2873
2874 TITLING_OPTION ::=
2875   [Title    =>] STRING_LITERAL,
2876 | [Subtitle =>] STRING_LITERAL
2877 @end smallexample
2878
2879 @noindent
2880 Syntax checked but otherwise ignored by GNAT@.  This is a listing control
2881 pragma used in DEC Ada 83 implementations to provide a title and/or
2882 subtitle for the program listing.  The program listing generated by GNAT
2883 does not have titles or subtitles.
2884
2885 Unlike other pragmas, the full flexibility of named notation is allowed
2886 for this pragma, i.e.@: the parameters may be given in any order if named
2887 notation is used, and named and positional notation can be mixed
2888 following the normal rules for procedure calls in Ada.
2889
2890 @cindex Unions in C
2891 @findex Unchecked_Union
2892 @item pragma Unchecked_Union
2893 @noindent
2894 Syntax:
2895
2896 @smallexample
2897 pragma Unchecked_Union (first_subtype_LOCAL_NAME)
2898 @end smallexample
2899
2900 @noindent
2901 This pragma is used to declare that the specified type should be represented
2902 in a manner
2903 equivalent to a C union type, and is intended only for use in
2904 interfacing with C code that uses union types.  In Ada terms, the named
2905 type must obey the following rules:
2906
2907 @itemize @bullet
2908 @item
2909 It is a non-tagged non-limited record type.
2910 @item
2911 It has a single discrete discriminant with a default value.
2912 @item
2913 The component list consists of a single variant part.
2914 @item
2915 Each variant has a component list with a single component.
2916 @item
2917 No nested variants are allowed.
2918 @item
2919 No component has an explicit default value.
2920 @item
2921 No component has a non-static constraint.
2922 @end itemize
2923
2924 In addition, given a type that meets the above requirements, the
2925 following restrictions apply to its use throughout the program:
2926
2927 @itemize @bullet
2928 @item
2929 The discriminant name can be mentioned only in an aggregate.
2930 @item
2931 No subtypes may be created of this type.
2932 @item
2933 The type may not be constrained by giving a discriminant value.
2934 @item
2935 The type cannot be passed as the actual for a generic formal with a
2936 discriminant.
2937 @end itemize
2938
2939 Equality and inequality operations on @code{unchecked_unions} are not
2940 available, since there is no discriminant to compare and the compiler
2941 does not even know how many bits to compare.  It is implementation
2942 dependent whether this is detected at compile time as an illegality or
2943 whether it is undetected and considered to be an erroneous construct.  In
2944 GNAT, a direct comparison is illegal, but GNAT does not attempt to catch
2945 the composite case (where two composites are compared that contain an
2946 unchecked union component), so such comparisons are simply considered
2947 erroneous.
2948
2949 The layout of the resulting type corresponds exactly to a C union, where
2950 each branch of the union corresponds to a single variant in the Ada
2951 record.  The semantics of the Ada program is not changed in any way by
2952 the pragma, i.e.@: provided the above restrictions are followed, and no
2953 erroneous incorrect references to fields or erroneous comparisons occur,
2954 the semantics is exactly as described by the Ada reference manual.
2955 Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the
2956 type and the default convention is C
2957
2958 @findex Unimplemented_Unit
2959 @item pragma Unimplemented_Unit
2960 @noindent
2961 Syntax:
2962
2963 @smallexample
2964 pragma Unimplemented_Unit;
2965 @end smallexample
2966
2967 @noindent
2968 If this pragma occurs in a unit that is processed by the compiler, GNAT
2969 aborts with the message @samp{@var{xxx} not implemented}, where
2970 @var{xxx} is the name of the current compilation unit.  This pragma is
2971 intended to allow the compiler to handle unimplemented library units in
2972 a clean manner.
2973
2974 The abort only happens if code is being generated.  Thus you can use
2975 specs of unimplemented packages in syntax or semantic checking mode.
2976
2977 @findex Unreferenced
2978 @item pragma Unreferenced
2979 @cindex Warnings, unreferenced
2980 @noindent
2981 Syntax:
2982
2983 @smallexample
2984 pragma Unreferenced (local_Name @{, local_Name@});
2985 @end smallexample
2986
2987 @noindent
2988 This pragma signals that the entities whose names are listed are
2989 deliberately not referenced. This suppresses warnings about the
2990 entities being unreferenced, and in addition a warning will be
2991 generated if one of these entities is in fact referenced.
2992
2993 This is particularly useful for clearly signalling that a particular
2994 parameter is not referenced in some particular subprogram implementation
2995 and that this is deliberate. It can also be useful in the case of
2996 objects declared only for their initialization or finalization side
2997 effects.
2998
2999 If @code{local_Name} identifies more than one matching homonym in the
3000 current scope, then the entity most recently declared is the one to which
3001 the pragma applies.
3002
3003 @findex Unreserve_All_Interrupts
3004 @item pragma Unreserve_All_Interrupts
3005 @noindent
3006 Syntax:
3007
3008 @smallexample
3009 pragma Unreserve_All_Interrupts;
3010 @end smallexample
3011
3012 @noindent
3013 Normally certain interrupts are reserved to the implementation.  Any attempt
3014 to attach an interrupt causes Program_Error to be raised, as described in
3015 RM C.3.2(22).  A typical example is the @code{SIGINT} interrupt used in
3016 many systems for an @kbd{Ctrl-C} interrupt.  Normally this interrupt is
3017 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
3018 interrupt execution.
3019
3020 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
3021 a program, then all such interrupts are unreserved.  This allows the
3022 program to handle these interrupts, but disables their standard
3023 functions.  For example, if this pragma is used, then pressing
3024 @kbd{Ctrl-C} will not automatically interrupt execution.  However,
3025 a program can then handle the @code{SIGINT} interrupt as it chooses.
3026
3027 For a full list of the interrupts handled in a specific implementation,
3028 see the source code for the specification of @code{Ada.Interrupts.Names} in
3029 file @file{a-intnam.ads}.  This is a target dependent file that contains the
3030 list of interrupts recognized for a given target.  The documentation in
3031 this file also specifies what interrupts are affected by the use of
3032 the @code{Unreserve_All_Interrupts} pragma.
3033
3034 @findex Unsuppress
3035 @item pragma Unsuppress
3036 @noindent
3037 Syntax:
3038
3039 @smallexample
3040 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
3041 @end smallexample
3042
3043 @noindent
3044 This pragma undoes the effect of a previous pragma @code{Suppress}.  If
3045 there is no corresponding pragma @code{Suppress} in effect, it has no
3046 effect.  The range of the effect is the same as for pragma
3047 @code{Suppress}.  The meaning of the arguments is identical to that used
3048 in pragma @code{Suppress}.
3049
3050 One important application is to ensure that checks are on in cases where
3051 code depends on the checks for its correct functioning, so that the code
3052 will compile correctly even if the compiler switches are set to suppress
3053 checks.
3054
3055 @cindex @code{Size}, VADS compatibility
3056 @findex Use_VADS_Size
3057 @item pragma Use_VADS_Size
3058 @noindent
3059 Syntax:
3060
3061 @smallexample
3062 pragma Use_VADS_Size;
3063 @end smallexample
3064
3065 @noindent
3066 This is a configuration pragma.  In a unit to which it applies, any use
3067 of the 'Size attribute is automatically interpreted as a use of the
3068 'VADS_Size attribute.  Note that this may result in incorrect semantic
3069 processing of valid Ada 95 programs.  This is intended to aid in the
3070 handling of legacy code which depends on the interpretation of Size
3071 as implemented in the VADS compiler.  See description of the VADS_Size
3072 attribute for further details.
3073
3074 @findex Validity_Checks
3075 @item pragma Validity_Checks
3076 @noindent
3077 Syntax:
3078
3079 @smallexample
3080 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
3081 @end smallexample
3082
3083 @noindent
3084 This pragma is used in conjunction with compiler switches to control the
3085 built in validity checking provided by GNAT@.  The compiler switches, if set
3086 provide an initial setting for the switches, and this pragma may be used
3087 to modify these settings, or the settings may be provided entirely by
3088 the use of the pragma.  This pragma can be used anywhere that a pragma
3089 is legal, including use as a configuration pragma (including use in
3090 the @file{gnat.adc} file).
3091
3092 The form with a string literal specifies which validity options are to be
3093 activated.  The validity checks are first set to include only the default
3094 reference manual settings, and then a string of letters in the string
3095 specifies the exact set of options required.  The form of this string
3096 is exactly as described for the @code{-gnatVx} compiler switch (see the
3097 GNAT users guide for details).  For example the following two methods
3098 can be used to enable validity checking for mode @code{in} and
3099 @code{in out} subprogram parameters:
3100
3101 @smallexample
3102 pragma Validity_Checks ("im");
3103 gcc -c -gnatVim @dots{}
3104 @end smallexample
3105
3106 @noindent
3107 The form ALL_CHECKS activates all standard checks (its use is equivalent
3108 to the use of the @code{gnatva} switch.
3109
3110 The forms with @code{Off} and @code{On}
3111 can be used to temporarily disable validity checks
3112 as shown in the following example:
3113
3114 @smallexample
3115 @iftex
3116 @leftskip=0cm
3117 @end iftex
3118 pragma Validity_Checks ("c"); -- validity checks for copies
3119 pragma Validity_Checks (Off); -- turn off validity checks
3120 A := B;                       -- B will not be validity checked
3121 pragma Validity_Checks (On);  -- turn validity checks back on
3122 A := C;                       -- C will be validity checked
3123 @end smallexample
3124
3125 @findex Volatile
3126 @item pragma Volatile
3127 @noindent
3128 Syntax:
3129
3130 @smallexample
3131 pragma Volatile (local_NAME)
3132 @end smallexample
3133
3134 @noindent
3135 This pragma is defined by the Ada 95 Reference Manual, and the GNAT
3136 implementation is fully conformant with this definition.  The reason it
3137 is mentioned in this section is that a pragma of the same name was supplied
3138 in some Ada 83 compilers, including DEC Ada 83.  The Ada 95 implementation
3139 of pragma Volatile is upwards compatible with the implementation in
3140 Dec Ada 83.
3141
3142 @findex Warnings
3143 @item pragma Warnings
3144 @noindent
3145 Syntax:
3146
3147 @smallexample
3148 pragma Warnings (On | Off [, LOCAL_NAME]);
3149 @end smallexample
3150
3151 @noindent
3152 Normally warnings are enabled, with the output being controlled by
3153 the command line switch.  Warnings (@code{Off}) turns off generation of
3154 warnings until a Warnings (@code{On}) is encountered or the end of the
3155 current unit.  If generation of warnings is turned off using this
3156 pragma, then no warning messages are output, regardless of the
3157 setting of the command line switches.
3158
3159 The form with a single argument is a configuration pragma.
3160
3161 If the @var{local_name} parameter is present, warnings are suppressed for
3162 the specified entity.  This suppression is effective from the point where
3163 it occurs till the end of the extended scope of the variable (similar to
3164 the scope of @code{Suppress}).
3165
3166 @findex Weak_External
3167 @item pragma Weak_External
3168 @noindent
3169 Syntax:
3170
3171 @smallexample
3172 pragma Weak_External ([Entity =>] LOCAL_NAME);
3173 @end smallexample
3174
3175 @noindent
3176 This pragma specifies that the given entity should be marked as a weak
3177 external (one that does not have to be resolved) for the linker.  For
3178 further details, consult the GCC manual.
3179 @end table
3180
3181 @node Implementation Defined Attributes
3182 @chapter Implementation Defined Attributes
3183 Ada 95 defines (throughout the Ada 95 reference manual,
3184 summarized in annex K),
3185 a set of attributes that provide useful additional functionality in all
3186 areas of the language.  These language defined attributes are implemented
3187 in GNAT and work as described in the Ada 95 Reference Manual.
3188
3189 In addition, Ada 95 allows implementations to define additional
3190 attributes whose meaning is defined by the implementation.  GNAT provides
3191 a number of these implementation-dependent attributes which can be used
3192 to extend and enhance the functionality of the compiler.  This section of
3193 the GNAT reference manual describes these additional attributes.
3194
3195 Note that any program using these attributes may not be portable to
3196 other compilers (although GNAT implements this set of attributes on all
3197 platforms).  Therefore if portability to other compilers is an important
3198 consideration, you should minimize the use of these attributes.
3199
3200 @table @code
3201 @findex Abort_Signal
3202 @item Abort_Signal
3203 @noindent
3204 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
3205 prefix) provides the entity for the special exception used to signal
3206 task abort or asynchronous transfer of control.  Normally this attribute
3207 should only be used in the tasking runtime (it is highly peculiar, and
3208 completely outside the normal semantics of Ada, for a user program to
3209 intercept the abort exception).
3210
3211 @cindex Size of @code{Address}
3212 @findex Address_Size
3213 @item Address_Size
3214 @noindent
3215 @code{Standard'Address_Size} (@code{Standard} is the only allowed
3216 prefix) is a static constant giving the number of bits in an
3217 @code{Address}.  It is used primarily for constructing the definition of
3218 @code{Memory_Size} in package @code{Standard}, but may be freely used in user
3219 programs and has the advantage of being static, while a direct
3220 reference to System.Address'Size is non-static because Address
3221 is a private type.
3222
3223 @findex Asm_Input
3224 @item Asm_Input
3225 @noindent
3226 The @code{Asm_Input} attribute denotes a function that takes two
3227 parameters.  The first is a string, the second is an expression of the
3228 type designated by the prefix.  The first (string) argument is required
3229 to be a static expression, and is the constraint for the parameter,
3230 (e.g.@: what kind of register is required).  The second argument is the
3231 value to be used as the input argument.  The possible values for the
3232 constant are the same as those used in the RTL, and are dependent on
3233 the configuration file used to built the GCC back end.
3234 @ref{Machine Code Insertions}
3235
3236 @findex Asm_Output
3237 @item Asm_Output
3238 @noindent
3239 The @code{Asm_Output} attribute denotes a function that takes two
3240 parameters.  The first is a string, the second is the name of a variable
3241 of the type designated by the attribute prefix.  The first (string)
3242 argument is required to be a static expression and designates the
3243 constraint for the parameter (e.g.@: what kind of register is
3244 required).  The second argument is the variable to be updated with the
3245 result.  The possible values for constraint are the same as those used in
3246 the RTL, and are dependent on the configuration file used to build the
3247 GCC back end.  If there are no output operands, then this argument may
3248 either be omitted, or explicitly given as @code{No_Output_Operands}.
3249 @ref{Machine Code Insertions}
3250
3251 @cindex OpenVMS
3252 @findex AST_Entry
3253 @item AST_Entry
3254 @noindent
3255 This attribute is implemented only in OpenVMS versions of GNAT@.  Applied to
3256 the name of an entry, it yields a value of the predefined type AST_Handler
3257 (declared in the predefined package System, as extended by the use of
3258 pragma @code{Extend_System (Aux_DEC)}).  This value enables the given entry to
3259 be called when an AST occurs.  For further details, refer to the @cite{DEC Ada
3260 Language Reference Manual}, section 9.12a.
3261
3262 @findex Bit
3263 @item Bit
3264 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
3265 offset within the storage unit (byte) that contains the first bit of
3266 storage allocated for the object.  The value of this attribute is of the
3267 type @code{Universal_Integer}, and is always a non-negative number not
3268 exceeding the value of @code{System.Storage_Unit}.
3269
3270 For an object that is a variable or a constant allocated in a register,
3271 the value is zero.  (The use of this attribute does not force the
3272 allocation of a variable to memory).
3273
3274 For an object that is a formal parameter, this attribute applies
3275 to either the matching actual parameter or to a copy of the
3276 matching actual parameter.
3277
3278 For an access object the value is zero.  Note that
3279 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
3280 designated object.  Similarly for a record component
3281 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
3282 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
3283 are subject to index checks.
3284
3285 This attribute is designed to be compatible with the DEC Ada 83 definition
3286 and implementation of the @code{Bit} attribute.
3287
3288 @findex Bit_Position
3289 @item Bit_Position
3290 @noindent
3291 @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
3292 of the fields of the record type, yields the bit
3293 offset within the record contains the first bit of
3294 storage allocated for the object.  The value of this attribute is of the
3295 type @code{Universal_Integer}.  The value depends only on the field
3296 @var{C} and is independent of the alignment of
3297 the containing record @var{R}.
3298
3299 @findex Code_Address
3300 @cindex Subprogram address
3301 @cindex Address of subprogram code
3302 @item Code_Address
3303 @noindent
3304 The @code{'Address}
3305 attribute may be applied to subprograms in Ada 95, but the
3306 intended effect from the Ada 95 reference manual seems to be to provide
3307 an address value which can be used to call the subprogram by means of
3308 an address clause as in the following example:
3309
3310 @smallexample
3311 procedure K is @dots{}
3312
3313 procedure L;
3314 for L'Address use K'Address;
3315 pragma Import (Ada, L);
3316 @end smallexample
3317
3318 @noindent
3319 A call to @code{L} is then expected to result in a call to @code{K}@.  In Ada 83, where
3320 there were no access-to-subprogram values, this was a common work around
3321 for getting the effect of an indirect call.
3322 GNAT implements the above use of @code{Address} and the technique illustrated
3323 by the example code works correctly.
3324
3325 However, for some purposes, it is useful to have the address of the start
3326 of the generated code for the subprogram.  On some architectures, this is
3327 not necessarily the same as the @code{Address} value described above.  For example,
3328 the @code{Address} value may reference a subprogram descriptor rather than the
3329 subprogram itself.
3330
3331 The @code{'Code_Address} attribute, which can only be applied to 
3332 subprogram entities, always returns the address of the start of the 
3333 generated code of the specified subprogram, which may or may not be
3334 the same value as is returned by the corresponding @code{'Address}
3335 attribute.
3336
3337 @cindex Big endian
3338 @cindex Little endian
3339 @findex Default_Bit_Order
3340 @item Default_Bit_Order
3341 @noindent
3342 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
3343 permissible prefix), provides the value @code{System.Default_Bit_Order}
3344 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
3345 @code{Low_Order_First}).  This is used to construct the definition of
3346 @code{Default_Bit_Order} in package @code{System}.
3347
3348 @findex Elaborated
3349 @item Elaborated
3350 @noindent
3351 The prefix of the @code{'Elaborated} attribute must be a unit name.  The
3352 value is a Boolean which indicates whether or not the given unit has been
3353 elaborated.  This attribute is primarily intended for internal use by the
3354 generated code for dynamic elaboration checking, but it can also be used
3355 in user programs.  The value will always be True once elaboration of all
3356 units has been completed.
3357
3358 @findex Elab_Body
3359 @item Elab_Body
3360 @noindent
3361 This attribute can only be applied to a program unit name.  It returns
3362 the entity for the corresponding elaboration procedure for elaborating
3363 the body of the referenced unit.  This is used in the main generated
3364 elaboration procedure by the binder and is not normally used in any
3365 other context.  However, there may be specialized situations in which it
3366 is useful to be able to call this elaboration procedure from Ada code,
3367 e.g.@: if it is necessary to do selective re-elaboration to fix some
3368 error.
3369
3370 @findex Elab_Spec
3371 @item Elab_Spec
3372 @noindent
3373 This attribute can only be applied to a program unit name.  It returns
3374 the entity for the corresponding elaboration procedure for elaborating
3375 the specification of the referenced unit.  This is used in the main
3376 generated elaboration procedure by the binder and is not normally used
3377 in any other context.  However, there may be specialized situations in
3378 which it is useful to be able to call this elaboration procedure from
3379 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
3380 some error.
3381
3382 @cindex Ada 83 attributes
3383 @findex Emax
3384 @item Emax
3385 @noindent
3386 The @code{Emax} attribute is provided for compatibility with Ada 83.  See
3387 the Ada 83 reference manual for an exact description of the semantics of
3388 this attribute.
3389
3390 @cindex Representation of enums
3391 @findex Enum_Rep
3392 @item Enum_Rep
3393 @noindent
3394 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
3395 function with the following specification:
3396
3397 @smallexample
3398 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
3399   return Universal_Integer;
3400 @end smallexample
3401
3402 @noindent
3403 It is also allowable to apply @code{Enum_Rep} directly to an object of an
3404 enumeration type or to a non-overloaded enumeration
3405 literal.  In this case @code{@var{S}'Enum_Rep} is equivalent to 
3406 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
3407 enumeration literal or object.
3408
3409 The function returns the representation value for the given enumeration
3410 value.  This will be equal to value of the @code{Pos} attribute in the
3411 absence of an enumeration representation clause.  This is a static
3412 attribute (i.e.@: the result is static if the argument is static).
3413
3414 @code{@var{S}'Enum_Rep} can also be used with integer types and objects, in which
3415 case it simply returns the integer value.  The reason for this is to allow
3416 it to be used for @code{(<>)} discrete formal arguments in a generic unit that
3417 can be instantiated with either enumeration types or integer types.  Note
3418 that if @code{Enum_Rep} is used on a modular type whose upper bound exceeds the
3419 upper bound of the largest signed integer type, and the argument is a
3420 variable, so that the universal integer calculation is done at run-time,
3421 then the call to @code{Enum_Rep} may raise @code{Constraint_Error}.
3422
3423 @cindex Ada 83 attributes
3424 @findex Epsilon
3425 @item Epsilon
3426 @noindent
3427 The @code{Epsilon} attribute is provided for compatibility with Ada 83.  See
3428 the Ada 83 reference manual for an exact description of the semantics of
3429 this attribute.
3430
3431 @findex Fixed_Value
3432 @item Fixed_Value
3433 @noindent
3434 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
3435 function with the following specification:
3436
3437 @smallexample
3438 function @var{S}'Fixed_Value (Arg : Universal_Integer)
3439   return @var{S};
3440 @end smallexample
3441
3442 @noindent
3443 The value returned is the fixed-point value @var{V} such that
3444
3445 @smallexample
3446 @var{V} = Arg * @var{S}'Small
3447 @end smallexample
3448
3449 @noindent
3450 The effect is thus equivalent to first converting the argument to the
3451 integer type used to represent @var{S}, and then doing an unchecked
3452 conversion to the fixed-point type.  This attribute is primarily intended
3453 for use in implementation of the input-output functions for fixed-point
3454 values.
3455
3456 @cindex Discriminants, testing for
3457 @findex Has_Discriminants
3458 @item Has_Discriminants
3459 @noindent
3460 The prefix of the @code{Has_Discriminants} attribute is a type.  The result
3461 is a Boolean value which is True if the type has discriminants, and False
3462 otherwise.  The intended use of this attribute is in conjunction with generic
3463 definitions.  If the attribute is applied to a generic private type, it
3464 indicates whether or not the corresponding actual type has discriminants.
3465
3466 @findex Img
3467 @item Img
3468 @noindent
3469 The @code{Img} attribute differs from @code{Image} in that it may be
3470 applied to objects as well as types, in which case it gives the
3471 @code{Image} for the subtype of the object.  This is convenient for
3472 debugging:
3473
3474 @smallexample
3475 Put_Line ("X = " & X'Img);
3476 @end smallexample
3477
3478 @noindent
3479 has the same meaning as the more verbose:
3480
3481 @smallexample
3482 Put_Line ("X = " & @var{type}'Image (X));
3483 @end smallexample
3484
3485 where @var{type} is the subtype of the object X@.
3486
3487 @findex Integer_Value
3488 @item Integer_Value
3489 @noindent
3490 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
3491 function with the following specification:
3492
3493 @smallexample
3494 function @var{S}'Integer_Value (Arg : Universal_Fixed)
3495   return @var{S};
3496 @end smallexample
3497
3498 @noindent
3499 The value returned is the integer value @var{V}, such that
3500
3501 @smallexample
3502 Arg = @var{V} * @var{type}'Small
3503 @end smallexample
3504
3505 @noindent
3506 The effect is thus equivalent to first doing an unchecked convert from
3507 the fixed-point type to its corresponding implementation type, and then
3508 converting the result to the target integer type.  This attribute is
3509 primarily intended for use in implementation of the standard
3510 input-output functions for fixed-point values.
3511
3512 @cindex Ada 83 attributes
3513 @findex Large
3514 @item Large
3515 @noindent
3516 The @code{Large} attribute is provided for compatibility with Ada 83.  See
3517 the Ada 83 reference manual for an exact description of the semantics of
3518 this attribute.
3519
3520 @findex Machine_Size
3521 @item Machine_Size
3522 @noindent
3523 This attribute is identical to the @code{Object_Size} attribute.  It is
3524 provided for compatibility with the DEC Ada 83 attribute of this name.
3525    
3526 @cindex Ada 83 attributes
3527 @findex Mantissa
3528 @item Mantissa
3529 @noindent
3530 The @code{Mantissa} attribute is provided for compatibility with Ada 83.  See
3531 the Ada 83 reference manual for an exact description of the semantics of
3532 this attribute.
3533
3534 @cindex Interrupt priority, maximum
3535 @findex Max_Interrupt_Priority
3536 @item Max_Interrupt_Priority
3537 @noindent
3538 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
3539 permissible prefix), provides the value
3540 @code{System.Max_Interrupt_Priority} and is intended primarily for
3541 constructing this definition in package @code{System}.
3542
3543 @cindex Priority, maximum
3544 @findex Max_Priority
3545 @item Max_Priority
3546 @noindent
3547 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
3548 prefix) provides the value @code{System.Max_Priority} and is intended
3549 primarily for constructing this definition in package @code{System}.
3550
3551 @cindex Alignment, maximum
3552 @findex Maximum_Alignment
3553 @item Maximum_Alignment
3554 @noindent
3555 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
3556 permissible prefix) provides the maximum useful alignment value for the
3557 target.  This is a static value that can be used to specify the alignment
3558 for an object, guaranteeing that it is properly aligned in all
3559 cases.  This is useful when an external object is imported and its
3560 alignment requirements are unknown.
3561
3562 @cindex Return values, passing mechanism
3563 @cindex Parameters, passing mechanism
3564 @findex Mechanism_Code
3565 @item Mechanism_Code
3566 @noindent
3567 @code{@var{function}'Mechanism_Code} yields an integer code for the
3568 mechanism used for the result of function, and
3569 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
3570 used for formal parameter number @var{n} (a static integer value with 1
3571 meaning the first parameter) of @var{subprogram}.  The code returned is:
3572
3573 @table @asis
3574 @item 1
3575 by copy (value)
3576 @item 2
3577 by reference
3578 @item 3
3579 by descriptor (default descriptor class)
3580 @item 4
3581 by descriptor (UBS: unaligned bit string)
3582 @item 5
3583 by descriptor (UBSB: aligned bit string with arbitrary bounds)
3584 @item 6
3585 by descriptor (UBA: unaligned bit array)
3586 @item 7
3587 by descriptor (S: string, also scalar access type parameter)
3588 @item 8
3589 by descriptor (SB: string with arbitrary bounds)
3590 @item 9
3591 by descriptor (A: contiguous array)
3592 @item 10
3593 by descriptor (NCA: non-contiguous array)
3594 @end table
3595
3596 @cindex OpenVMS
3597 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
3598
3599 @cindex Zero address, passing
3600 @findex Null_Parameter
3601 @item Null_Parameter
3602 @noindent
3603 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
3604 type or subtype @var{T} allocated at machine address zero.  The attribute
3605 is allowed only as the default expression of a formal parameter, or as
3606 an actual expression of a subprogram call.  In either case, the
3607 subprogram must be imported.
3608
3609 The identity of the object is represented by the address zero in the
3610 argument list, independent of the passing mechanism (explicit or
3611 default).
3612
3613 This capability is needed to specify that a zero address should be
3614 passed for a record or other composite object passed by reference.
3615 There is no way of indicating this without the @code{Null_Parameter}
3616 attribute.
3617
3618 @cindex Size, used for objects
3619 @findex Object_Size
3620 @item Object_Size
3621 @noindent
3622 The size of an object is not necessarily the same as the size of the type
3623 of an object.  This is because by default object sizes are increased to be
3624 a multiple of the alignment of the object.  For example, 
3625 @code{Natural'Size} is
3626 31, but by default objects of type @code{Natural} will have a size of 32 bits.
3627 Similarly, a record containing an integer and a character:
3628
3629 @smallexample
3630 type Rec is record
3631    I : Integer;
3632    C : Character;
3633 end record;
3634 @end smallexample
3635
3636 @noindent
3637 will have a size of 40 (that is @code{Rec'Size} will be 40.  The 
3638 alignment will be 4, because of the
3639 integer field, and so the default size of record objects for this type
3640 will be 64 (8 bytes).
3641
3642 The @code{@var{type}'Object_Size} attribute
3643 has been added to GNAT to allow the
3644 default object size of a type to be easily determined.  For example,
3645 @code{Natural'Object_Size} is 32, and
3646 @code{Rec'Object_Size} (for the record type in the above example) will be
3647 64.  Note also that, unlike the situation with the
3648 @code{Size} attribute as defined in the Ada RM, the 
3649 @code{Object_Size} attribute can be specified individually
3650 for different subtypes.  For example:
3651
3652 @smallexample
3653 type R is new Integer;
3654 subtype R1 is R range 1 .. 10;
3655 subtype R2 is R range 1 .. 10;
3656 for R2'Object_Size use 8;
3657 @end smallexample
3658
3659 @noindent
3660 In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
3661 32 since the default object size for a subtype is the same as the object size
3662 for the parent subtype.  This means that objects of type @code{R}
3663 or @code{R1} will
3664 by default be 32 bits (four bytes).  But objects of type
3665 @code{R2} will be only
3666 8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
3667
3668 @cindex Parameters, when passed by reference
3669 @findex Passed_By_Reference
3670 @item Passed_By_Reference
3671 @noindent
3672 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
3673 a value of type @code{Boolean} value that is @code{True} if the type is
3674 normally passed by reference and @code{False} if the type is normally
3675 passed by copy in calls.  For scalar types, the result is always @code{False}
3676 and is static.  For non-scalar types, the result is non-static.
3677
3678 @findex Range_Length
3679 @item Range_Length
3680 @noindent
3681 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
3682 the number of values represented by the subtype (zero for a null