OSDN Git Service

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