]>
Commit | Line | Data |
---|---|---|
41af791f | 1 | \input texinfo @c -*-texinfo-*- |
41af791f GB |
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 | |
e2500fed | 11 | @c $Revision: 1.3.8.1 $ |
41af791f | 12 | @c o |
ad42149c | 13 | @c Copyright (C) 1995-2002 Free Software Foundation o |
41af791f | 14 | @c o |
41af791f GB |
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 | ||
ad42149c FW |
25 | @dircategory GNU Ada tools |
26 | @direntry | |
27 | * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. | |
28 | @end direntry | |
41af791f GB |
29 | @titlepage |
30 | ||
31 | ||
32 | @title GNAT Reference Manual | |
33 | @subtitle GNAT, The GNU Ada 95 Compiler | |
ad42149c FW |
34 | @ifset vxworks |
35 | @title Version 3.16w | |
36 | @end ifset | |
37 | @ifclear vxworks | |
38 | @subtitle Version 3.16w | |
39 | @end ifclear | |
41af791f GB |
40 | @author Ada Core Technologies, Inc. |
41 | ||
42 | @page | |
43 | @vskip 0pt plus 1filll | |
44 | ||
45 | ||
ad42149c | 46 | Copyright @copyright{} 1995-2001, Free Software Foundation |
41af791f GB |
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 | ||
41af791f GB |
56 | |
57 | @end titlepage | |
ace133aa | 58 | @ifnottex |
41af791f GB |
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 | ||
ad42149c FW |
67 | @ifset vxworks |
68 | Version 3.16w | |
69 | @end ifset | |
70 | @ifclear vxworks | |
71 | Version 3.16w | |
72 | @end ifclear | |
41af791f GB |
73 | |
74 | Ada Core Technologies, Inc. | |
75 | ||
76 | ||
ad42149c | 77 | Copyright @copyright{} 1995-2001, Free Software Foundation |
41af791f GB |
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; | |
ad42149c FW |
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''. | |
41af791f | 86 | |
41af791f GB |
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 | ||
ad42149c | 131 | * Ada.Characters.Latin_9 (a-chlat9.ads):: |
41af791f | 132 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: |
ad42149c | 133 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: |
41af791f GB |
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):: | |
ad42149c | 168 | * GNAT.MD5 (g-md5.ads):: |
41af791f GB |
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):: | |
ad42149c | 196 | * Interfaces.VxWorks.IO (i-vxwoio.ads):: |
41af791f GB |
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 | ||
ace133aa | 232 | @end ifnottex |
41af791f GB |
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 | |
ad42149c | 239 | GNAT compiler. It includes information on implementation dependent |
41af791f GB |
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 | |
ad42149c | 245 | different machines. However, since Ada 95 is designed to be used in a |
41af791f | 246 | wide variety of applications, it also contains a number of system |
ad42149c | 247 | dependent features to Functbe used in interfacing to the external world. |
41af791f GB |
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 | |
46b58b8c | 308 | extensive set of standard library routines as implemented by GNAT@. |
41af791f GB |
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 | |
ad42149c | 349 | @code{Option flags} |
41af791f GB |
350 | |
351 | @item | |
ad42149c | 352 | @file{File Names}, @samp{button names}, and @samp{field names}. |
41af791f GB |
353 | |
354 | @item | |
ad42149c | 355 | @code{Variables}. |
41af791f GB |
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 | |
ad42149c | 372 | characters @samp{$ } (dollar sign followed by space). If your system uses this |
41af791f | 373 | sequence as a prompt, then the commands will appear exactly as you see them |
ad42149c FW |
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. | |
41af791f GB |
376 | |
377 | @node Related Information | |
378 | @unnumberedsec Related Information | |
ad42149c | 379 | See the following documents for further information on GNAT: |
41af791f GB |
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 | |
ad42149c | 392 | of the standard reference manual cited above. The annotations describe |
41af791f GB |
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 | |
ad42149c | 413 | information to the compiler. These language defined pragmas are |
41af791f GB |
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 | |
ad42149c | 418 | whose meaning is defined by the implementation. GNAT provides a number |
41af791f | 419 | of these implementation-dependent pragmas which can be used to extend |
ad42149c | 420 | and enhance the functionality of the compiler. This section of the GNAT |
41af791f GB |
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 | |
ad42149c | 425 | platforms). Therefore if portability to other compilers is an important |
41af791f GB |
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 | |
ad42149c | 442 | handled sequence of statements (right after the @code{begin}). It has |
41af791f GB |
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 | |
ad42149c | 459 | switches. In Ada 83 mode, GNAT attempts to be as compatible with |
41af791f | 460 | the syntax and semantics of Ada 83, as defined in the original Ada |
ad42149c | 461 | 83 Reference Manual as possible. In particular, the new Ada 95 |
41af791f GB |
462 | keywords are not recognized, optional package bodies are allowed, |
463 | and generics may name types with unknown discriminants without using | |
ad42149c | 464 | the @code{(<>)} notation. In addition, some but not all of the additional |
41af791f GB |
465 | restrictions of Ada 83 are enforced. |
466 | ||
ad42149c | 467 | Ada 83 mode is intended for two purposes. Firstly, it allows existing |
41af791f GB |
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 | |
ad42149c | 489 | contexts. This pragma is useful when writing a reusable component that |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f | 508 | can be either a string literal or an |
ad42149c FW |
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 | |
41af791f GB |
512 | unambiguous. |
513 | ||
514 | The analyzed pragma is retained in the tree, but not otherwise processed | |
ad42149c | 515 | by any part of the GNAT compiler. This pragma is intended for use by |
46b58b8c | 516 | external tools, including ASIS@. |
41af791f GB |
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 | |
ad42149c | 531 | line switch is set to activate assertions. The pragma expands into code |
41af791f GB |
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 | |
ad42149c | 545 | with the exception occurrence if the exception is raised. If no second |
41af791f GB |
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, | |
ad42149c | 548 | and @var{nnn} is the line number of the assert. A pragma is not a |
41af791f GB |
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 | |
ad42149c | 553 | @dots{} |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 567 | are suppressed). More precisely it is not quite true that the pragma |
41af791f GB |
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 | |
ad42149c FW |
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. | |
41af791f GB |
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 | |
ad42149c FW |
577 | assertions that have an effect on the program. You should generally |
578 | avoid side effects in the expression arguments of this pragma. However, | |
41af791f GB |
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 | |
ad42149c | 594 | This pragma is implemented only in the OpenVMS implementation of GNAT@. The |
41af791f | 595 | argument is the simple name of a single entry; at most one @code{AST_Entry} |
ad42149c | 596 | pragma is allowed for any given entry. This pragma must be used in |
41af791f GB |
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 | |
ad42149c | 599 | as the entry to which it applies. This pragma specifies that the given entry |
41af791f | 600 | may be used to handle an OpenVMS asynchronous system trap (@code{AST}) |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 619 | B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change |
41af791f GB |
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 | |
46b58b8c | 634 | If these conditions are met the argument is passed by copy, i.e.@: in a |
41af791f GB |
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 | |
ad42149c | 653 | This is almost identical in effect to pragma @code{Ident}. It allows the |
41af791f | 654 | placement of a comment into the object file and hence into the |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 683 | of fields. The @var{size} argument |
41af791f GB |
684 | is syntax checked in GNAT, but otherwise ignored. |
685 | ||
ad42149c | 686 | @code{Common_Object} is not supported on all platforms. If no |
41af791f GB |
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 | |
ad42149c | 703 | two fields of the same floating-point type. The effect of this pragma is |
41af791f | 704 | to force gcc to use the special internal complex representation form for |
ad42149c | 705 | this record, which may be more efficient. Note that this may result in |
41af791f | 706 | the code for this type not conforming to standard ABI (application |
ad42149c | 707 | binary interface) requirements for the handling of record types. For |
41af791f GB |
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 | |
ad42149c | 739 | aligned). For example, 1-byte components are aligned on byte boundaries, |
41af791f | 740 | 2-byte integer components are aligned on 2-byte boundaries, 4-byte |
ad42149c | 741 | integer components are aligned on 4-byte boundaries and so on. These |
41af791f | 742 | alignment rules correspond to the normal rules for C compilers on all |
46b58b8c | 743 | machines except the VAX@. |
41af791f GB |
744 | |
745 | @findex Component_Size_4 | |
746 | @item Component_Size_4 | |
747 | Naturally aligns components with a size of four or fewer | |
ad42149c | 748 | bytes. Components that are larger than 4 bytes are placed on the next |
41af791f GB |
749 | 4-byte boundary. |
750 | ||
751 | @findex Storage_Unit | |
752 | @item Storage_Unit | |
46b58b8c | 753 | Specifies that array or record components are byte aligned, i.e.@: |
41af791f GB |
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 | |
ad42149c FW |
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, | |
41af791f GB |
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 | |
ad42149c | 769 | choice applies to the specified type. The use of |
41af791f | 770 | @code{Component_Alignment} together with a pragma @code{Pack} causes the |
ad42149c | 771 | @code{Component_Alignment} pragma to be ignored. The use of |
41af791f GB |
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 | |
ad42149c | 780 | within this declarative part. In either case it specifies the alignment |
41af791f GB |
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. | |
ad42149c FW |
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. | |
41af791f GB |
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 | |
ad42149c | 834 | that is declared as a tagged or untagged record type. It indicates that |
41af791f GB |
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 | |
ad42149c | 845 | as subprograms as required). Initialization is allowed only by |
41af791f GB |
846 | constructor functions (see pragma @code{CPP_Constructor}). |
847 | ||
848 | Pragma @code{CPP_Class} is intended primarily for automatic generation | |
ad42149c FW |
849 | using an automatic binding generator tool. |
850 | See @ref{Interfacing to C++} for related information. | |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 882 | @var{T} is created on the Ada side with no explicit constructor. Other |
41af791f GB |
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 | |
ad42149c | 897 | level. GNAT issues the appropriate call, whatever it is, to get the |
41af791f GB |
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 | |
ad42149c | 910 | expressions in the Ada declaration. In the second case, the given |
41af791f GB |
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 | |
ad42149c | 915 | on the Ada side. If no default constructor is imported, only the |
41af791f GB |
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 | |
ad42149c FW |
920 | using an automatic binding generator tool. |
921 | See @ref{Interfacing to C++} for more related information. | |
41af791f GB |
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 | |
ad42149c | 937 | case of a virtual function imported from C++. The @var{Entity} argument |
41af791f GB |
938 | must be a |
939 | primitive subprogram of a tagged type to which pragma @code{CPP_Class} | |
ad42149c | 940 | applies. The @var{Vtable_Ptr} argument specifies |
41af791f | 941 | the Vtable_Ptr component which contains the |
ad42149c | 942 | entry for this virtual function. The @var{Position} argument |
41af791f GB |
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 | |
ad42149c FW |
956 | using an automatic binding generator tool. |
957 | See @ref{Interfacing to C++} for related information. | |
41af791f GB |
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 | |
ad42149c | 978 | the number of virtual functions on the C++ side. Not all of these |
41af791f GB |
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 | |
ad42149c FW |
987 | using an automatic binding generator tool. |
988 | See @ref{Interfacing to C++} for related information. | |
41af791f GB |
989 | |
990 | @findex Debug | |
991 | @item pragma Debug | |
992 | @noindent | |
993 | Syntax: | |
994 | ||
995 | @smallexample | |
ad42149c FW |
996 | pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON); |
997 | ||
998 | PROCEDURE_CALL_WITHOUT_SEMICOLON ::= | |
999 | PROCEDURE_NAME | |
1000 | | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART | |
41af791f GB |
1001 | @end smallexample |
1002 | ||
1003 | @noindent | |
ad42149c FW |
1004 | The argument has the syntactic form of an expression, meeting the |
1005 | syntactic requirements for pragmas. | |
1006 | ||
41af791f | 1007 | If assertions are not enabled on the command line, this pragma has no |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 1027 | pragma. If the parameter is RM, then the dynamic elaboration |
41af791f GB |
1028 | model described in the Ada Reference Manual is used, as though |
1029 | the @code{-gnatE} switch had been specified on the command | |
ad42149c FW |
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}. | |
41af791f GB |
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 | | |
ad42149c | 1049 | SELECTED_COMPONENT, |
41af791f GB |
1050 | [Entity =>] IDENTIFIER | |
1051 | SELECTED_COMPONENT | | |
ad42149c FW |
1052 | STRING_LITERAL |
1053 | [,[Parameter_Types =>] PARAMETER_TYPES] | |
1054 | [,[Result_Type =>] result_SUBTYPE_NAME] | |
1055 | [,[Homonym_Number =>] INTEGER_LITERAL]); | |
41af791f GB |
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 | |
ad42149c | 1063 | compilation unit it is defined in. The entity may be either a subprogram |
41af791f GB |
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 | |
ad42149c | 1072 | are required. item is an entity of a library package, then the first |
41af791f | 1073 | argument specifies the unit name, and the second argument specifies |
ad42149c | 1074 | the particular entity. If the second argument is in string form, it must |
41af791f GB |
1075 | correspond to the internal manner in which GNAT stores entity names (see |
1076 | compilation unit Namet in the compiler sources for details). | |
ad42149c FW |
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 | |
41af791f GB |
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 | ||
ad42149c FW |
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 | ||
41af791f GB |
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 | ||
ad42149c FW |
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 | |
41af791f | 1102 | in a system independent manner, with unused entities eliminated, without |
ad42149c FW |
1103 | the requirement of modifying the source text. Normally the required set |
1104 | of @code{Eliminate} pragmas is constructed automatically using the gnatelim tool. | |
41af791f | 1105 | Elimination of unused entities local to a compilation unit is automatic, |
ad42149c | 1106 | without requiring the use of pragma @code{Eliminate}. |
41af791f GB |
1107 | |
1108 | Note that the reason this pragma takes string literals where names might | |
ad42149c | 1109 | be expected is that a pragma @code{Eliminate} can appear in a context where the |
41af791f GB |
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 | |
ad42149c | 1131 | This pragma is implemented only in the OpenVMS implementation of GNAT@. It |
41af791f GB |
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 | |
ad42149c | 1135 | name available to the OpenVMS Linker as a global symbol. For further details |
41af791f GB |
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 | |
ad42149c | 1180 | result values. We recommend, for the purposes of improving portability, |
41af791f GB |
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 | |
ad42149c | 1193 | pragma applies. If more than one function name exists of this name in |
41af791f GB |
1194 | the declarative part you must use the @code{Parameter_Types} and |
1195 | @code{Result_Type} parameters is mandatory to achieve the required | |
ad42149c | 1196 | unique designation. @var{subtype_ mark}s in these parameters must |
41af791f GB |
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 | |
46b58b8c | 1201 | Passing by descriptor is supported only on the OpenVMS ports of GNAT@. |
41af791f GB |
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 | |
ad42149c | 1221 | the normal @code{Export} pragma applied to an object. You may use a |
41af791f GB |
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, | |
46b58b8c | 1224 | but otherwise ignored by GNAT@. |
41af791f GB |
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 | |
ad42149c | 1309 | with this parameter as the result of the function. GNAT provides for |
41af791f GB |
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 | |
ad42149c | 1333 | implementations that extend the facilities of package @code{System}. In |
41af791f | 1334 | GNAT, @code{System} contains only the definitions that are present in |
ad42149c | 1335 | the Ada 95 RM@. However, other implementations, notably the DEC Ada 83 |
41af791f GB |
1336 | implementation, provide many extensions to package @code{System}. |
1337 | ||
1338 | For each such implementation accommodated by this pragma, GNAT provides a | |
46b58b8c | 1339 | package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 |
ad42149c | 1340 | implementation, which provides the required additional definitions. You |
41af791f GB |
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} | |
ad42149c | 1343 | clause. In this case no special processing is required. |
41af791f GB |
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 | |
ad42149c | 1349 | provides greater compatibility with the existing code. Pragma |
41af791f GB |
1350 | @code{Extend_System} is a configuration pragma whose single argument is |
1351 | the name of the package containing the extended definition | |
ad42149c | 1352 | (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under |
41af791f GB |
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 | |
ad42149c FW |
1361 | definition. Note that such a package is a child of @code{System} |
1362 | and thus is considered part of the implementation. To compile | |
41af791f | 1363 | it you will have to use the appropriate switch for compiling |
ad42149c | 1364 | system units. See the GNAT User's Guide for details. |
41af791f GB |
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 | |
ad42149c | 1381 | @code{Export} as defined in the Ada Reference Manual. It is |
41af791f GB |
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 | |
ad42149c | 1402 | with Import and Export pragmas. There are two cases to consider: |
41af791f GB |
1403 | |
1404 | @table @asis | |
1405 | @item Implicit external names | |
ad42149c | 1406 | Implicit external names are derived from identifiers. The most common case |
41af791f GB |
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 | |
ad42149c | 1417 | casing of the external name, and so a convention is needed. In GNAT the |
41af791f | 1418 | default treatment is that such names are converted to all lower case |
ad42149c | 1419 | letters. This corresponds to the normal C style in many environments. |
41af791f | 1420 | The first argument of pragma @code{External_Name_Casing} can be used to |
ad42149c FW |
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, | |
41af791f GB |
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 | |
ad42149c | 1430 | Explicit external names are given as string literals. The most common case |
41af791f GB |
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 | |
ad42149c | 1440 | for the external name. The second argument of pragma |
41af791f GB |
1441 | @code{External_Name_Casing} may be used to modify this behavior. |
1442 | If @code{Uppercase} is specified, then the name | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | ||
ad42149c FW |
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 | |
46b58b8c | 1458 | such compilers (e.g.@: the DEC C compiler), it may be convenient to use |
41af791f GB |
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 | |
ad42149c | 1479 | defined at the library level. This is mostly useful for types where |
41af791f GB |
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 | |
46b58b8c | 1497 | This pragma is implemented only in the OpenVMS implementation of GNAT@. |
41af791f GB |
1498 | It allows control over the internal representation chosen for the predefined |
1499 | floating point types declared in the packages @code{Standard} and | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
46b58b8c | 1544 | This pragma is implemented only in the OpenVMS implementation of GNAT@. |
41af791f GB |
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 | |
ad42149c | 1591 | specify additional information for an imported function. The pragma |
41af791f GB |
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 | |
ad42149c | 1598 | pragma applies. If more than one function name exists of this name in |
41af791f GB |
1599 | the declarative part you must use the @code{Parameter_Types} and |
1600 | @var{Result_Type} parameters to achieve the required unique | |
ad42149c | 1601 | designation. Subtype marks in these parameters must exactly match the |
41af791f GB |
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 | |
ad42149c | 1607 | parameters and result. If you specify a single mechanism name, it |
41af791f GB |
1608 | applies to all parameters. Otherwise you may specify a mechanism on a |
1609 | parameter by parameter basis using either positional or named | |
ad42149c | 1610 | notation. If the mechanism is not specified, the default mechanism |
41af791f GB |
1611 | is used. |
1612 | ||
1613 | @cindex OpenVMS | |
1614 | @cindex Passing by descriptor | |
46b58b8c | 1615 | Passing by descriptor is supported only on the to OpenVMS ports of GNAT@. |
41af791f | 1616 | |
46b58b8c | 1617 | @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. |
41af791f GB |
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 | |
ad42149c | 1622 | parameters). All optional parameters must be of mode @code{IN} and have |
41af791f GB |
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 | |
ad42149c | 1648 | point of view). @var{size} is syntax checked, but otherwise ignored by |
46b58b8c | 1649 | GNAT@. |
41af791f GB |
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 | |
ad42149c | 1732 | with this parameter as the result of the function. The purpose of this |
41af791f GB |
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 | |
ad42149c | 1739 | basis using either positional or named notation. If the mechanism is not |
41af791f GB |
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 | |
ad42149c | 1758 | two important differences. First, there is no requirement for the pragma |
41af791f GB |
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, | |
ad42149c | 1766 | as will any declaration of a scalar variable. For composite variables, |
41af791f GB |
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 | |
ad42149c | 1771 | for initializing scalar objects. At bind time, you can select whether to |
41af791f | 1772 | initialize with invalid values (like Normalize_Scalars), or with high or |
ad42149c | 1773 | low values, or with a specified bit pattern. See the users guide for binder |
41af791f GB |
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 | |
ad42149c | 1779 | behavior depends on the choice. Of course the behavior should not change, |
41af791f GB |
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 | |
ad42149c | 1785 | in GNAT, which checks for invalid values under more conditions. |
41af791f GB |
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 | |
ad42149c | 1801 | Similar to pragma @code{Inline} except that inlining is not subject to |
41af791f GB |
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, | |
ad42149c | 1815 | but otherwise ignored, by GNAT@. All generic instantiations are inlined |
46b58b8c | 1816 | by default when using GNAT@. |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 1854 | 83 compilers that use the pragma for this purpose. You must provide at |
41af791f GB |
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 | |
ad42149c | 1869 | conditions with respect to the standard and modified GPL@. A pragma @code{License}, |
41af791f GB |
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 | |
ad42149c | 1888 | under the GPL@. This is the license used for the GNAT run-time which ensures |
41af791f GB |
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 | |
ad42149c | 1893 | depend on units that are licensed under the GPL@. Typical examples are |
41af791f | 1894 | proprietary code that is to be released under more restrictive license |
ad42149c | 1895 | conditions. Note that restricted units are permitted to @code{with} units |
41af791f GB |
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 | |
ad42149c | 1903 | unknown license, and no checking is done. However, standard GNAT headers |
41af791f GB |
1904 | are recognized, and license information is derived from them as follows. |
1905 | ||
1906 | @itemize @bullet | |
1907 | ||
ad42149c | 1908 | A GNAT license header starts with a line containing 78 hyphens. The following |
41af791f GB |
1909 | comment text is searched for the appearence of any of the following strings. |
1910 | ||
ad42149c FW |
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 | |
46b58b8c | 1913 | which case the license is assumed to be modified GPL@. |
41af791f GB |
1914 | |
1915 | If one of the strings | |
ad42149c FW |
1916 | ``This specification is adapated from the Ada Semantic Interface'' or |
1917 | ``This specification is derived from the Ada Reference Manual'' is found | |
41af791f GB |
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 | |
ad42149c | 1924 | @code{with}'ed. For example, the program: |
41af791f GB |
1925 | |
1926 | @smallexample | |
1927 | with Sem_Ch3; | |
1928 | with GNAT.Sockets; | |
1929 | procedure Secret_Stuff is | |
ad42149c | 1930 | @dots{} |
41af791f GB |
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 | |
ad42149c | 1939 | 1. with Sem_Ch3; |
41af791f GB |
1940 | | |
1941 | >>> license of withed unit "Sem_Ch3" is incompatible | |
1942 | ||
ad42149c FW |
1943 | 2. with GNAT.Sockets; |
1944 | 3. procedure Secret_Stuff is | |
41af791f GB |
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 | |
46b58b8c | 1950 | run time, and is therefore licensed under the modified GPL@. |
41af791f GB |
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 | |
ad42149c FW |
1973 | separate arguments to the linker. In addition pragma Link_With allows |
1974 | multiple arguments, with the same effect as successive pragmas. | |
41af791f GB |
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 | |
ad42149c | 1988 | This pragma establishes a linker alias for the given named entity. For |
41af791f GB |
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 | |
ad42149c FW |
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. | |
41af791f GB |
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 | |
ad42149c | 2031 | This is a language defined pragma which is fully implemented in GNAT@. The |
41af791f | 2032 | effect is to cause all scalar objects that are not otherwise initialized |
ad42149c | 2033 | to be initialized. The initial values are implementation dependent and |
41af791f GB |
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 | |
ad42149c | 2040 | Character'Last. This will be out of range of the subtype only if |
41af791f GB |
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 | |
ad42149c | 2046 | Wide_Character'Last. This will be out of range of the subtype only if |
41af791f GB |
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 | |
ad42149c FW |
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, | |
41af791f GB |
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 | |
ad42149c | 2071 | Objects of a modular type are initialized to typ'Last. This will be out |
41af791f GB |
2072 | of range of the subtype only if the subtype excludes this value. |
2073 | ||
2074 | @item Enumeration types | |
46b58b8c | 2075 | Objects of an enumeration type are initialized to all one-bits, i.e.@: to |
ad42149c | 2076 | the value @code{2 ** typ'Size - 1}. This will be out of range of the enumeration |
41af791f | 2077 | subtype in all cases except where the subtype contains exactly |
ad42149c | 2078 | 2**8, 2**16, or 2**32 elements. |
41af791f GB |
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 | |
46b58b8c | 2095 | This pragma is implemented only in the OpenVMS implementation of GNAT@. |
41af791f GB |
2096 | It allows control over the internal representation chosen for the predefined |
2097 | type @code{Long_Float} and for floating point type representations with | |
ad42149c | 2098 | @code{digits} specified in the range 7 through 15. |
41af791f | 2099 | For further details on this pragma, see the |
ad42149c FW |
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 | |
41af791f | 2102 | description of the @code{GNAT LIBRARY} command in the OpenVMS version |
ad42149c | 2103 | of the GNAT User's Guide for details on the use of this command. |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 2158 | declarations in the current declarative part. A procedure to which this |
41af791f GB |
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 | |
ad42149c | 2161 | the end of a statement sequence. One use of this pragma is to identify |
41af791f GB |
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 | |
ad42149c | 2178 | Syntax checked, but otherwise ignored by GNAT@. This is recognized for |
41af791f GB |
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 | |
ad42149c | 2185 | optimized. GNAT does not attempt to optimize any tasks in this manner |
41af791f GB |
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 | |
ad42149c | 2198 | This pragma controls the generation of polling code. This is normally off. |
41af791f | 2199 | If @code{pragma Polling (ON)} is used then periodic calls are generated to |
ad42149c FW |
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}. | |
41af791f | 2202 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 2208 | at the start of every subprogram call. This guarantees that the @code{Poll} |
41af791f | 2209 | routine is called frequently, and places an upper bound (determined by |
ad42149c | 2210 | the complexity of the code) on the period between two @code{Poll} calls. |
41af791f GB |
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. | |
ad42149c FW |
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}. | |
41af791f | 2218 | |
ad42149c | 2219 | A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT |
41af791f | 2220 | distribution) is used to enable the asynchronous abort capability on |
ad42149c | 2221 | targets that do not normally support the capability. The version of @code{Poll} |
41af791f GB |
2222 | in this file makes a call to the appropriate runtime routine to test for |
2223 | an abort condition. | |
2224 | ||
ad42149c FW |
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. | |
41af791f GB |
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, | |
ad42149c | 2241 | and that the exception should be propagated. It is relevant only if |
41af791f | 2242 | zero cost exception handling is in use, and is thus never needed if |
ad42149c | 2243 | the alternative @code{longjmp} / @code{setjmp} implementation of exceptions is used |
41af791f GB |
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 | |
ad42149c | 2249 | through foreign code. For example, consider the |
41af791f GB |
2250 | situation where @code{P1} calls |
2251 | @code{P2}, and @code{P2} calls @code{P3}, where | |
46b58b8c | 2252 | @code{P1} and @code{P3} are in Ada, but @code{P2} is in C@. |
ad42149c | 2253 | @code{P3} raises an Ada exception. The question is whether or not |
41af791f GB |
2254 | it will be propagated through @code{P2} and can be handled in |
2255 | @code{P1}. | |
2256 | ||
ad42149c FW |
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 | |
41af791f GB |
2260 | some targets, notably in the current version all x86 architecture |
2261 | targets, in which the answer is that such propagation does not | |
ad42149c | 2262 | happen automatically. If such propagation is required on these |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
2300 | that the compiler can assume that there are no side effects, and |
2301 | in particular that two calls with identical arguments produce the | |
ad42149c | 2302 | same result. It also means that the function can be used in an |
41af791f GB |
2303 | address clause. |
2304 | ||
2305 | Note that, quite deliberately, there are no static checks to try | |
ad42149c | 2306 | to ensure that this promise is met, so @code{Pure_Function} can be used |
41af791f | 2307 | with functions that are conceptually pure, even if they do modify |
ad42149c | 2308 | global variables. For example, a square root function that is |
41af791f GB |
2309 | instrumented to count the number of times it is called is still |
2310 | conceptually pure, and can still be optimized, even though it | |
ad42149c | 2311 | modifies a global variable (the count). Memo functions are another |
41af791f GB |
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 | |
ad42149c | 2317 | there is no need to use pragma @code{Pure_Function} for such functions. An |
41af791f | 2318 | exception is any function that has at least one formal of type |
ad42149c | 2319 | @code{System.Address} or a type derived from it. Such functions are not |
41af791f GB |
2320 | considered pure by default, since the compiler assumes that the |
2321 | @code{Address} parameter may be functioning as a pointer and that the | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 2327 | applies to the underlying renamed function. This can be used to |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
2429 | Program_Error exception. |
2430 | @end table | |
2431 | ||
2432 | @noindent | |
ad42149c FW |
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. | |
41af791f GB |
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}, | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c FW |
2493 | but is ignored by GNAT@. GNAT does not provide the capability for |
2494 | sharing of generic code. All generic instantiations result in making | |
41af791f GB |
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 | |
ad42149c | 2513 | Use this to override the normal naming convention. It is a configuration |
41af791f | 2514 | pragma, and so has the usual applicability of configuration pragmas |
46b58b8c | 2515 | (i.e.@: it applies to either an entire partition, or to all units in a |
41af791f | 2516 | compilation, or to a single unit, depending on how it is used. |
ad42149c | 2517 | @var{unit_name} is mapped to @var{file_name_literal}. The identifier for |
41af791f GB |
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 | |
ad42149c | 2547 | to form the file name. The second argument is optional. If present it |
41af791f | 2548 | specifies the casing of the unit name in the resulting file name string. |
ad42149c | 2549 | The default is lower case. Finally the third argument allows for systematic |
41af791f GB |
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, | |
ad42149c FW |
2553 | see the sections ``Using Other File Names'' and |
2554 | ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}. | |
41af791f GB |
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 | |
ad42149c | 2570 | information). @var{string_literal} is a static string constant that |
41af791f | 2571 | specifies the file name to be used in error messages and debugging |
ad42149c FW |
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 | |
41af791f GB |
2574 | source file is the one referred to. |
2575 | ||
2576 | The second argument must be a string literal, it cannot be a static | |
ad42149c | 2577 | string expression other than a string literal. This is because its value |
41af791f GB |
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 | |
ad42149c | 2594 | types defined in packages. Not only is it simpler to use than declaring |
41af791f GB |
2595 | the necessary functions with attribute representation clauses, but more |
2596 | significantly, it allows the declaration to made in such a way that the | |
ad42149c | 2597 | stream packages are not loaded unless they are needed. The use of |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | ||
ad42149c | 2621 | The Read and Write functions must not be overloaded subprograms. If necessary |
41af791f GB |
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 | |
ad42149c | 2665 | built in style checking provided by GNAT@. The compiler switches, if set |
41af791f GB |
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 | |
ad42149c | 2668 | the use of the pragma. This pragma can be used anywhere that a pragma |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
2677 | layout checking: |
2678 | ||
2679 | @smallexample | |
2680 | pragma Style_Checks ("l"); | |
ad42149c | 2681 | gcc -c -gnatyl @dots{} |
41af791f GB |
2682 | @end smallexample |
2683 | ||
2684 | @noindent | |
2685 | The form ALL_CHECKS activates all standard checks (its use is equivalent | |
ad42149c | 2686 | to the use of the @code{gnaty} switch with no options. See GNAT User's |
41af791f GB |
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 | |
ad42149c | 2706 | @code{On} or @code{Off}. The effect is to turn of semantic style checks |
41af791f GB |
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 | |
46b58b8c | 2731 | but is ignored by GNAT@. |
41af791f GB |
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 | |
ad42149c FW |
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 | |
46b58b8c | 2747 | configuration pragma is the preferred usage in GNAT@. |
41af791f GB |
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 | |
ad42149c | 2775 | @code{Priority}) and applies to the task in which it appears. The |
41af791f GB |
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 | |
ad42149c | 2779 | tasks to specific processors. For details on the facilities available |
41af791f GB |
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 | |
ad42149c | 2795 | @code{Priority}) and applies to the task in which it appears. The |
41af791f | 2796 | argument must be of type String, and provides a name to be used for |
ad42149c | 2797 | the task instance when the task is created. Note that this expression |
41af791f | 2798 | is not required to be static, and in particular, it can contain |
ad42149c | 2799 | references to task discriminants. This facility can be used to |
41af791f GB |
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 | |
ad42149c | 2804 | and is accessible to tools like the debugger. In addition the |
41af791f GB |
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 | |
ad42149c | 2852 | created, depending on the target. This pragma can appear anywhere a |
41af791f GB |
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 | |
ad42149c | 2888 | Syntax checked but otherwise ignored by GNAT@. This is a listing control |
41af791f | 2889 | pragma used in DEC Ada 83 implementations to provide a title and/or |
ad42149c | 2890 | subtitle for the program listing. The program listing generated by GNAT |
41af791f GB |
2891 | does not have titles or subtitles. |
2892 | ||
2893 | Unlike other pragmas, the full flexibility of named notation is allowed | |
46b58b8c | 2894 | for this pragma, i.e.@: the parameters may be given in any order if named |
41af791f GB |
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 | |
ad42149c | 2912 | interfacing with C code that uses union types. In Ada terms, the named |
41af791f GB |
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 | |
ad42149c | 2949 | does not even know how many bits to compare. It is implementation |
41af791f | 2950 | dependent whether this is detected at compile time as an illegality or |
ad42149c | 2951 | whether it is undetected and considered to be an erroneous construct. In |
41af791f GB |
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 | |
ad42149c | 2959 | record. The semantics of the Ada program is not changed in any way by |
46b58b8c | 2960 | the pragma, i.e.@: provided the above restrictions are followed, and no |
41af791f GB |
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 | ||
ad42149c FW |
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 | ||
41af791f GB |
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 | |
ad42149c | 3021 | Normally certain interrupts are reserved to the implementation. Any attempt |
41af791f | 3022 | to attach an interrupt causes Program_Error to be raised, as described in |
ad42149c FW |
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 | |
41af791f GB |
3026 | interrupt execution. |
3027 | ||
ad42149c FW |
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 | |
41af791f | 3030 | program to handle these interrupts, but disables their standard |
ad42149c FW |
3031 | functions. For example, if this pragma is used, then pressing |
3032 | @kbd{Ctrl-C} will not automatically interrupt execution. However, | |
41af791f GB |
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, | |
ad42149c FW |
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 | |
41af791f | 3039 | this file also specifies what interrupts are affected by the use of |
ad42149c | 3040 | the @code{Unreserve_All_Interrupts} pragma. |
41af791f GB |
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 | |
ad42149c | 3052 | This pragma undoes the effect of a previous pragma @code{Suppress}. If |
41af791f | 3053 | there is no corresponding pragma @code{Suppress} in effect, it has no |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3074 | This is a configuration pragma. In a unit to which it applies, any use |
41af791f | 3075 | of the 'Size attribute is automatically interpreted as a use of the |
ad42149c FW |
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 | |
41af791f | 3078 | handling of legacy code which depends on the interpretation of Size |
ad42149c | 3079 | as implemented in the VADS compiler. See description of the VADS_Size |
41af791f GB |
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 | |
ad42149c | 3093 | built in validity checking provided by GNAT@. The compiler switches, if set |
41af791f GB |
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 | |
ad42149c | 3096 | the use of the pragma. This pragma can be used anywhere that a pragma |
41af791f GB |
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 | |
ad42149c | 3101 | activated. The validity checks are first set to include only the default |
41af791f | 3102 | reference manual settings, and then a string of letters in the string |
ad42149c | 3103 | specifies the exact set of options required. The form of this string |
41af791f | 3104 | is exactly as described for the @code{-gnatVx} compiler switch (see the |
ad42149c | 3105 | GNAT users guide for details). For example the following two methods |
41af791f GB |
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"); | |
ad42149c | 3111 | gcc -c -gnatVim @dots{} |
41af791f GB |
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 | |
ad42149c | 3144 | implementation is fully conformant with this definition. The reason it |
41af791f | 3145 | is mentioned in this section is that a pragma of the same name was supplied |
ad42149c | 3146 | in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation |
41af791f GB |
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 | |
ad42149c | 3161 | the command line switch. Warnings (@code{Off}) turns off generation of |
41af791f | 3162 | warnings until a Warnings (@code{On}) is encountered or the end of the |
ad42149c | 3163 | current unit. If generation of warnings is turned off using this |
41af791f GB |
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 | |
ad42149c | 3170 | the specified entity. This suppression is effective from the point where |
41af791f GB |
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 | |
ad42149c | 3185 | external (one that does not have to be resolved) for the linker. For |
41af791f GB |
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 | |
ad42149c | 3194 | areas of the language. These language defined attributes are implemented |
41af791f GB |
3195 | in GNAT and work as described in the Ada 95 Reference Manual. |
3196 | ||
3197 | In addition, Ada 95 allows implementations to define additional | |
ad42149c | 3198 | attributes whose meaning is defined by the implementation. GNAT provides |
41af791f | 3199 | a number of these implementation-dependent attributes which can be used |
ad42149c | 3200 | to extend and enhance the functionality of the compiler. This section of |
41af791f GB |
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 | |
ad42149c | 3205 | platforms). Therefore if portability to other compilers is an important |
41af791f GB |
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 | |
ad42149c | 3214 | task abort or asynchronous transfer of control. Normally this attribute |
41af791f GB |
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 | |
ad42149c | 3225 | @code{Address}. It is used primarily for constructing the definition of |
41af791f GB |
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 | |
ad42149c | 3236 | type designated by the prefix. The first (string) argument is required |
41af791f | 3237 | to be a static expression, and is the constraint for the parameter, |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3249 | of the type designated by the attribute prefix. The first (string) |
41af791f | 3250 | argument is required to be a static expression and designates the |
46b58b8c | 3251 | constraint for the parameter (e.g.@: what kind of register is |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3263 | This attribute is implemented only in OpenVMS versions of GNAT@. Applied to |
41af791f GB |
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 | |
ad42149c FW |
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. | |
41af791f GB |
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 | |
ad42149c | 3274 | storage allocated for the object. The value of this attribute is of the |
41af791f GB |
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, | |
ad42149c | 3279 | the value is zero. (The use of this attribute does not force the |
41af791f GB |
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 | ||
ad42149c | 3286 | For an access object the value is zero. Note that |
41af791f | 3287 | @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the |
ad42149c | 3288 | designated object. Similarly for a record component |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3319 | procedure K is @dots{} |
41af791f GB |
3320 | |
3321 | procedure L; | |
3322 | for L'Address use K'Address; | |
3323 | pragma Import (Ada, L); | |
3324 | @end smallexample | |
3325 | ||
3326 | @noindent | |
ad42149c | 3327 | A call to @code{L} is then expected to result in a call to @code{K}@. In Ada 83, where |
41af791f GB |
3328 | there were no access-to-subprogram values, this was a common work around |
3329 | for getting the effect of an indirect call. | |
ad42149c | 3330 | GNAT implements the above use of @code{Address} and the technique illustrated |
41af791f GB |
3331 | by the example code works correctly. |
3332 | ||
3333 | However, for some purposes, it is useful to have the address of the start | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3353 | @code{Low_Order_First}). This is used to construct the definition of |
41af791f GB |
3354 | @code{Default_Bit_Order} in package @code{System}. |
3355 | ||
3356 | @findex Elaborated | |
3357 | @item Elaborated | |
3358 | @noindent | |
ad42149c | 3359 | The prefix of the @code{'Elaborated} attribute must be a unit name. The |
41af791f | 3360 | value is a Boolean which indicates whether or not the given unit has been |
ad42149c | 3361 | elaborated. This attribute is primarily intended for internal use by the |
41af791f | 3362 | generated code for dynamic elaboration checking, but it can also be used |
ad42149c | 3363 | in user programs. The value will always be True once elaboration of all |
41af791f GB |
3364 | units has been completed. |
3365 | ||
3366 | @findex Elab_Body | |
3367 | @item Elab_Body | |
3368 | @noindent | |
ad42149c | 3369 | This attribute can only be applied to a program unit name. It returns |
41af791f | 3370 | the entity for the corresponding elaboration procedure for elaborating |
ad42149c | 3371 | the body of the referenced unit. This is used in the main generated |
41af791f GB |
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, | |
46b58b8c | 3375 | e.g.@: if it is necessary to do selective re-elaboration to fix some |
41af791f GB |
3376 | error. |
3377 | ||
3378 | @findex Elab_Spec | |
3379 | @item Elab_Spec | |
3380 | @noindent | |
ad42149c | 3381 | This attribute can only be applied to a program unit name. It returns |
41af791f | 3382 | the entity for the corresponding elaboration procedure for elaborating |
ad42149c | 3383 | the specification of the referenced unit. This is used in the main |
41af791f GB |
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 | |
46b58b8c | 3387 | Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix |
41af791f GB |
3388 | some error. |
3389 | ||
3390 | @cindex Ada 83 attributes | |
3391 | @findex Emax | |
3392 | @item Emax | |
3393 | @noindent | |
ad42149c | 3394 | The @code{Emax} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3411 | It is also allowable to apply @code{Enum_Rep} directly to an object of an |
41af791f | 3412 | enumeration type or to a non-overloaded enumeration |
ad42149c | 3413 | literal. In this case @code{@var{S}'Enum_Rep} is equivalent to |
41af791f GB |
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 | |
ad42149c FW |
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 | |
46b58b8c | 3420 | attribute (i.e.@: the result is static if the argument is static). |
41af791f | 3421 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3435 | The @code{Epsilon} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3460 | conversion to the fixed-point type. This attribute is primarily intended |
41af791f GB |
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 | |
ad42149c | 3468 | The prefix of the @code{Has_Discriminants} attribute is a type. The result |
41af791f | 3469 | is a Boolean value which is True if the type has discriminants, and False |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3479 | @code{Image} for the subtype of the object. This is convenient for |
41af791f GB |
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 | ||
46b58b8c | 3493 | where @var{type} is the subtype of the object X@. |
41af791f GB |
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 | |
ad42149c | 3516 | converting the result to the target integer type. This attribute is |
41af791f GB |
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 | |
ad42149c | 3524 | The @code{Large} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3531 | This attribute is identical to the @code{Object_Size} attribute. It is |
41af791f GB |
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 | |
ad42149c | 3538 | The @code{Mantissa} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3565 | target. This is a static value that can be used to specify the alignment |
41af791f | 3566 | for an object, guaranteeing that it is properly aligned in all |
ad42149c | 3567 | cases. This is useful when an external object is imported and its |
41af791f GB |
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 | |
ad42149c | 3579 | meaning the first parameter) of @var{subprogram}. The code returned is: |
41af791f GB |
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 | |
ad42149c | 3605 | Values from 3 through 10 are only relevant to Digital OpenVMS implementations. |
41af791f GB |
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 | |
ad42149c | 3612 | type or subtype @var{T} allocated at machine address zero. The attribute |
41af791f | 3613 | is allowed only as the default expression of a formal parameter, or as |
ad42149c | 3614 | an actual expression of a subprogram call. In either case, the |
41af791f GB |
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 | |
ad42149c FW |
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, | |
41af791f GB |
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 | |
ad42149c | 3645 | will have a size of 40 (that is @code{Rec'Size} will be 40. The |
41af791f GB |
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 | |
ad42149c | 3652 | default object size of a type to be easily determined. For example, |
41af791f GB |
3653 | @code{Natural'Object_Size} is 32, and |
3654 | @code{Rec'Object_Size} (for the record type in the above example) will be | |
ad42149c | 3655 | 64. Note also that, unlike the situation with the |
41af791f GB |
3656 | @code{Size} attribute as defined in the Ada RM, the |
3657 | @code{Object_Size} attribute can be specified individually | |
ad42149c | 3658 | for different subtypes. For example: |
41af791f GB |
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 | |
ad42149c | 3670 | for the parent subtype. This means that objects of type @code{R} |
41af791f | 3671 | or @code{R1} will |
ad42149c | 3672 | by default be 32 bits (four bytes). But objects of type |
41af791f GB |
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 | |
ad42149c FW |
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. | |
41af791f GB |
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 | |
ad42149c | 3691 | range). The result is static for static subtypes. @code{Range_Length} |
41af791f GB |
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 | |
ad42149c | 3699 | The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3707 | The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3715 | The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3725 | for compatibility with Ada 83. See |
41af791f GB |
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 | |
ad42149c | 3750 | it is a static attribute. This means that if its argument is |
41af791f | 3751 | a static expression, then the result of the attribute is a |
ad42149c | 3752 | static expression. The result is that such an expression can be |
46b58b8c | 3753 | used in contexts (e.g.@: preelaborable packages) which require a |
41af791f GB |
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 | |
ad42149c | 3762 | the value of the type class for the full type of @var{type}. If |
41af791f GB |
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 | |
ad42149c | 3782 | applies to all concurrent types. This attribute is designed to |
41af791f GB |
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 | |
ad42149c FW |
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} | |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3804 | would preclude their use as numbers). This is used internally for the |
41af791f GB |
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} | |
ad42149c | 3813 | except that all accessibility and aliased view checks are omitted. This |
41af791f GB |
3814 | is a user-beware attribute. It is similar to |
3815 | @code{Address}, for which it is a desirable replacement where the value | |
ad42149c | 3816 | desired is an access type. In other words, its effect is identical to |
41af791f | 3817 | first applying the @code{Address} attribute and then doing an unchecked |
ad42149c | 3818 | conversion to a desired access type. In GNAT, but not necessarily in |
41af791f GB |
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 | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3834 | typical machines). In addition @code{'VADS_Size} applied to an object |
41af791f GB |
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 | |
ad42149c | 3842 | a value of the given subtype. It is the same as @code{@var{type}'Size}, |
41af791f GB |
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 | |
ad42149c | 3866 | by the phrase ``implementation advice''. These sections are not normative, |
46b58b8c | 3867 | i.e.@: they do not specify requirements that all compilers must |
ad42149c FW |
3868 | follow. Rather they provide advice on generally desirable behavior. You |
3869 | may wonder why they are not requirements. The most typical answer is | |
41af791f GB |
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 | |
ad42149c | 3874 | the Ada 95 Reference Manual. This chapter contains a table giving the |
41af791f GB |
3875 | reference manual section number, paragraph number and several keywords |
3876 | for each advice. Each entry consists of the text of the advice followed | |
ad42149c FW |
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 | |
41af791f GB |
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 | |
ad42149c | 3891 | Not relevant. All specialized needs annex features are either supported, |
41af791f GB |
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 | |
ad42149c | 3912 | error or erroneous execution. Not all such situations are detected at |
41af791f GB |
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 | |
ad42149c | 3955 | that this advice not be followed. For details see the separate section |
41af791f GB |
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 | |
ad42149c | 3983 | subset of the set of graphic characters of @code{Wide_Character}. Any |
41af791f GB |
3984 | character set ``localizations'' should be reflected in the results of |
3985 | the subprograms defined in the language-defined package | |
ad42149c | 3986 | @code{Characters.Handling} (see A.3) available in such a mode. In a mode with |
41af791f GB |
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 | |
ad42149c | 3995 | encoding. However, this only applies to the external forms. Internally |
41af791f GB |
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) | |
ad42149c FW |
4005 | arithmetic. No other named integer subtypes are recommended for package |
4006 | @code{Standard}. Instead, appropriate named integer subtypes should be | |
41af791f GB |
4007 | provided in the library package @code{Interfaces} (see B.2). |
4008 | @end cartouche | |
ad42149c FW |
4009 | @code{Long_Integer} is supported. Other standard integer types are supported |
4010 | so this advice is not fully followed. These types | |
41af791f GB |
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 | |
ad42149c | 4018 | modular types with a binary modulus up to @code{System.Max_Int*2+2}. An |
41af791f GB |
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 | |
ad42149c | 4031 | @code{Program_Error}. This is particularly important for enumeration |
41af791f GB |
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 | |
ad42149c FW |
4043 | precision. No other named floating point subtypes are recommended for |
4044 | package @code{Standard}. Instead, appropriate named floating point subtypes | |
41af791f GB |
4045 | should be provided in the library package @code{Interfaces} (see B.2). |
4046 | @end cartouche | |
ad42149c | 4047 | @code{Short_Float} and @code{Long_Long_Float} are also provided. The |
41af791f | 4048 | former provides improved compatibility with other implementations |
ad42149c FW |
4049 | supporting this type. The latter corresponds to the highest precision |
4050 | floating-point type supported by the hardware. On most machines, this | |
41af791f | 4051 | will be the same as @code{Long_Float}, but on some machines, it will |
ad42149c | 4052 | correspond to the IEEE extended form. The notable case is all ia32 |
41af791f GB |
4053 | (x86) implementations, where @code{Long_Long_Float} corresponds to |
4054 | the 80-bit extended precision format supported in hardware on this | |
ad42149c | 4055 | processor. Note that the 128-bit format on SPARC is not supported, |
41af791f GB |
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 | |
ad42149c FW |
4065 | array aggregates (see 4.3.3). However, if a pragma @code{Convention} |
4066 | (@code{Fortran}, @dots{}) applies to a multidimensional array type, then | |
41af791f GB |
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 | |
ad42149c | 4079 | Followed. (@code{Duration'Small} = 10**(@minus{}9)). |
41af791f GB |
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 | |
ad42149c | 4097 | Followed, except in the case of tagged types. Tagged types involve |
41af791f GB |
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 | |
ad42149c | 4100 | package. It is not easy to see how it would be possible to follow this |
41af791f GB |
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 | |
ad42149c FW |
4109 | debugging. @code{Exception_Message} should be short, about one |
4110 | line. @code{Exception_Information} can be long. @code{Exception_Message} | |
41af791f | 4111 | should not include the |
ad42149c | 4112 | @code{Exception_Name}. @code{Exception_Information} should include both |
41af791f GB |
4113 | the @code{Exception_Name} and the @code{Exception_Message}. |
4114 | @end cartouche | |
ad42149c | 4115 | Followed. For each exception that doesn't have a specified |
41af791f | 4116 | @code{Exception_Message}, the compiler generates one containing the location |
ad42149c | 4117 | of the raise statement. This location has the form ``file:line'', where |
41af791f | 4118 | file is the short file name (without path information) and line is the line |
ad42149c | 4119 | number in the file. Note that in the case of the Zero Cost Exception |
41af791f GB |
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 | |
ad42149c FW |
4150 | Followed. GNAT does not support non-static expressions in representation |
4151 | clauses unless they are constants declared before the entity. For | |
41af791f GB |
4152 | example: |
4153 | ||
4154 | @smallexample | |
4155 | X : typ; | |
4156 | for X'Address use To_address (16#2000#); | |
4157 | @end smallexample | |
4158 | ||
4159 | @noindent | |
ad42149c | 4160 | will be rejected, since the To_Address expression is non-static. Instead |
41af791f GB |
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 | |
ad42149c | 4178 | Followed. Size Clauses are not permitted on non-static components, as |
41af791f GB |
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 | |
ad42149c | 4205 | word boundaries to improve the packing. A component whose @code{Size} is |
41af791f GB |
4206 | greater than the word size may be allocated an integral number of words. |
4207 | @end cartouche | |
ad42149c | 4208 | Followed. Tight packing of arrays is supported for all component sizes |
41af791f GB |
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 | |
ad42149c | 4303 | supported by the target linker. For example, page alignment is likely to |
41af791f GB |
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 | |
ad42149c | 4350 | for a sign bit only if the subtype contains negative values. If such a |
41af791f GB |
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 | |
4368 | The recommended level of support for the @code{Component_Size} | |
4369 | attribute is: | |
4370 | @end cartouche | |
4371 | @sp 1 | |
4372 | @cartouche | |
4373 | An implementation need not support specified @code{Component_Sizes} that are | |
4374 | less than the @code{Size} of the component subtype. | |
4375 | @end cartouche | |
4376 | Followed. | |
4377 | ||
4378 | @sp 1 | |
4379 | @cartouche | |
4380 | An implementation should support specified @code{Component_Size}s that | |
ad42149c | 4381 | are factors and multiples of the word size. For such |
41af791f | 4382 | @code{Component_Size}s, the array should contain no gaps between |
ad42149c | 4383 | components. For other @code{Component_Size}s (if supported), the array |
41af791f GB |
4384 | should contain no gaps between components when packing is also |
4385 | specified; the implementation should forbid this combination in cases | |
4386 | where it cannot support a no-gaps representation. | |
4387 | @end cartouche | |
4388 | Followed. | |
4389 | ||
4390 | @cindex Enumeration representation clauses | |
4391 | @cindex Representation clauses, enumeration | |
4392 | @item 13.4(9-10): Enumeration Representation Clauses | |
4393 | @sp 1 | |
4394 | @cartouche | |
4395 | The recommended level of support for enumeration representation clauses | |
4396 | is: | |
4397 | ||
4398 | An implementation need not support enumeration representation clauses | |
4399 | for boolean types, but should at minimum support the internal codes in | |
4400 | the range @code{System.Min_Int.System.Max_Int}. | |
4401 | @end cartouche | |
4402 | Followed. | |
4403 | ||
4404 | @cindex Record representation clauses | |
4405 | @cindex Representation clauses, records | |
4406 | @item 13.5.1(17-22): Record Representation Clauses | |
4407 | @sp 1 | |
4408 | @cartouche | |
4409 | The recommended level of support for | |
4410 | @*@code{record_representation_clauses} is: | |
4411 | ||
4412 | An implementation should support storage places that can be extracted | |
4413 | with a load, mask, shift sequence of machine code, and set with a load, | |
4414 | shift, mask, store sequence, given the available machine instructions | |
4415 | and run-time model. | |
4416 | @end cartouche | |
4417 | Followed. | |
4418 | ||
4419 | @sp 1 | |
4420 | @cartouche | |
4421 | A storage place should be supported if its size is equal to the | |
4422 | @code{Size} of the component subtype, and it starts and ends on a | |
4423 | boundary that obeys the @code{Alignment} of the component subtype. | |
4424 | @end cartouche | |
4425 | Followed. | |
4426 | ||
4427 | @sp 1 | |
4428 | @cartouche | |
4429 | If the default bit ordering applies to the declaration of a given type, | |
4430 | then for a component whose subtype's @code{Size} is less than the word | |
4431 | size, any storage place that does not cross an aligned word boundary | |
4432 | should be supported. | |
4433 | @end cartouche | |
4434 | Followed. | |
4435 | ||
4436 | @sp 1 | |
4437 | @cartouche | |
4438 | An implementation may reserve a storage place for the tag field of a | |
4439 | tagged type, and disallow other components from overlapping that place. | |
4440 | @end cartouche | |
ad42149c FW |
4441 | Followed. The storage place for the tag field is the beginning of the tagged |
4442 | record, and its size is Address'Size. GNAT will reject an explicit component | |
41af791f GB |
4443 | clause for the tag field. |
4444 | ||
4445 | @sp 1 | |
4446 | @cartouche | |
4447 | An implementation need not support a @code{component_clause} for a | |
4448 | component of an extension part if the storage place is not after the | |
4449 | storage places of all components of the parent type, whether or not | |
4450 | those storage places had been specified. | |
4451 | @end cartouche | |
ad42149c | 4452 | Followed. The above advice on record representation clauses is followed, |
41af791f GB |
4453 | and all mentioned features are implemented. |
4454 | ||
4455 | @cindex Storage place attributes | |
4456 | @item 13.5.2(5): Storage Place Attributes | |
4457 | @sp 1 | |
4458 | @cartouche | |
4459 | If a component is represented using some form of pointer (such as an | |
4460 | offset) to the actual data of the component, and this data is contiguous | |
4461 | with the rest of the object, then the storage place attributes should | |
ad42149c | 4462 | reflect the place of the actual data, not the pointer. If a component is |
41af791f GB |
4463 | allocated discontinuously from the rest of the object, then a warning |
4464 | should be generated upon reference to one of its storage place | |
4465 | attributes. | |
4466 | @end cartouche | |
ad42149c | 4467 | Followed. There are no such components in GNAT@. |
41af791f GB |
4468 | |
4469 | @cindex Bit ordering | |
4470 | @item 13.5.3(7-8): Bit Ordering | |
4471 | @sp 1 | |
4472 | @cartouche | |
4473 | The recommended level of support for the non-default bit ordering is: | |
4474 | @end cartouche | |
4475 | @sp 1 | |
4476 | @cartouche | |
4477 | If @code{Word_Size} = @code{Storage_Unit}, then the implementation | |
4478 | should support the non-default bit ordering in addition to the default | |
4479 | bit ordering. | |
4480 | @end cartouche | |
ad42149c | 4481 | Followed. Word size does not equal storage size in this implementation. |
41af791f GB |
4482 | Thus non-default bit ordering is not supported. |
4483 | ||
4484 | @cindex @code{Address}, as private type | |
4485 | @item 13.7(37): Address as Private | |
4486 | @sp 1 | |
4487 | @cartouche | |
4488 | @code{Address} should be of a private type. | |
4489 | @end cartouche | |
4490 | Followed. | |
4491 | ||
4492 | @cindex Operations, on @code{Address} | |
4493 | @cindex @code{Address}, operations of | |
4494 | @item 13.7.1(16): Address Operations | |
4495 | @sp 1 | |
4496 | @cartouche | |
4497 | Operations in @code{System} and its children should reflect the target | |
ad42149c FW |
4498 | environment semantics as closely as is reasonable. For example, on most |
4499 | machines, it makes sense for address arithmetic to ``wrap around''. | |
41af791f GB |
4500 | Operations that do not make sense should raise @code{Program_Error}. |
4501 | @end cartouche | |
ad42149c | 4502 | Followed. Address arithmetic is modular arithmetic that wraps around. No |
41af791f GB |
4503 | operation raises @code{Program_Error}, since all operations make sense. |
4504 | ||
4505 | @cindex Unchecked conversion | |
4506 | @item 13.9(14-17): Unchecked Conversion | |
4507 | @sp 1 | |
4508 | @cartouche | |
4509 | The @code{Size} of an array object should not include its bounds; hence, | |
4510 | the bounds should not be part of the converted data. | |
4511 | @end cartouche | |
4512 | Followed. | |
4513 | ||
4514 | @sp 1 | |
4515 | @cartouche | |
4516 | The implementation should not generate unnecessary run-time checks to | |
4517 | ensure that the representation of @var{S} is a representation of the | |
ad42149c FW |
4518 | target type. It should take advantage of the permission to return by |
4519 | reference when possible. Restrictions on unchecked conversions should be | |
41af791f GB |
4520 | avoided unless required by the target environment. |
4521 | @end cartouche | |
ad42149c | 4522 | Followed. There are no restrictions on unchecked conversion. A warning is |
41af791f GB |
4523 | generated if the source and target types do not have the same size since |
4524 | the semantics in this case may be target dependent. | |
4525 | ||
4526 | @sp 1 | |
4527 | @cartouche | |
4528 | The recommended level of support for unchecked conversions is: | |
4529 | @end cartouche | |
4530 | @sp 1 | |
4531 | @cartouche | |
4532 | Unchecked conversions should be supported and should be reversible in | |
ad42149c | 4533 | the cases where this clause defines the result. To enable meaningful use |
41af791f GB |
4534 | of unchecked conversion, a contiguous representation should be used for |
4535 | elementary subtypes, for statically constrained array subtypes whose | |
4536 | component subtype is one of the subtypes described in this paragraph, | |
4537 | and for record subtypes without discriminants whose component subtypes | |
4538 | are described in this paragraph. | |
4539 | @end cartouche | |
4540 | Followed. | |
4541 | ||
4542 | @cindex Heap usage, implicit | |
4543 | @item 13.11(23-25): Implicit Heap Usage | |
4544 | @sp 1 | |
4545 | @cartouche | |
4546 | An implementation should document any cases in which it dynamically | |
4547 | allocates heap storage for a purpose other than the evaluation of an | |
4548 | allocator. | |
4549 | @end cartouche | |
4550 | Followed, the only other points at which heap storage is dynamically | |
4551 | allocated are as follows: | |
4552 | ||
4553 | @itemize @bullet | |
4554 | @item | |
4555 | At initial elaboration time, to allocate dynamically sized global | |
4556 | objects. | |
4557 | ||
4558 | @item | |
4559 | To allocate space for a task when a task is created. | |
4560 | ||
4561 | @item | |
ad42149c | 4562 | To extend the secondary stack dynamically when needed. The secondary |
41af791f GB |
4563 | stack is used for returning variable length results. |
4564 | @end itemize | |
4565 | ||
4566 | @sp 1 | |
4567 | @cartouche | |
ad42149c FW |
4568 | A default (implementation-provided) storage pool for an |
4569 | access-to-constant type should not have overhead to support deallocation of | |
41af791f GB |
4570 | individual objects. |
4571 | @end cartouche | |
4572 | Followed. | |
4573 | ||
4574 | @sp 1 | |
4575 | @cartouche | |
4576 | A storage pool for an anonymous access type should be created at the | |
4577 | point of an allocator for the type, and be reclaimed when the designated | |
4578 | object becomes inaccessible. | |
4579 | @end cartouche | |
4580 | Followed. | |
4581 | ||
4582 | @cindex Unchecked deallocation | |
4583 | @item 13.11.2(17): Unchecked De-allocation | |
4584 | @sp 1 | |
4585 | @cartouche | |
4586 | For a standard storage pool, @code{Free} should actually reclaim the | |
4587 | storage. | |
4588 | @end cartouche | |
4589 | Followed. | |
4590 | ||
4591 | @cindex Stream oriented attributes | |
4592 | @item 13.13.2(17): Stream Oriented Attributes | |
4593 | @sp 1 | |
4594 | @cartouche | |
4595 | If a stream element is the same size as a storage element, then the | |
4596 | normal in-memory representation should be used by @code{Read} and | |
ad42149c | 4597 | @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} |
41af791f GB |
4598 | should use the smallest number of stream elements needed to represent |
4599 | all values in the base range of the scalar type. | |
4600 | @end cartouche | |
ad42149c | 4601 | Followed. In particular, the interpretation chosen is that of AI-195, |
41af791f GB |
4602 | which specifies that the size to be used is that of the first subtype. |
4603 | ||
4604 | @item A.1(52): Implementation Advice | |
4605 | @sp 1 | |
4606 | @cartouche | |
4607 | If an implementation provides additional named predefined integer types, | |
4608 | then the names should end with @samp{Integer} as in | |
ad42149c | 4609 | @samp{Long_Integer}. If an implementation provides additional named |
41af791f GB |
4610 | predefined floating point types, then the names should end with |
4611 | @samp{Float} as in @samp{Long_Float}. | |
4612 | @end cartouche | |
4613 | Followed. | |
4614 | ||
4615 | @findex Ada.Characters.Handling | |
4616 | @item A.3.2(49): @code{Ada.Characters.Handling} | |
4617 | @sp 1 | |
4618 | @cartouche | |
4619 | If an implementation provides a localized definition of @code{Character} | |
4620 | or @code{Wide_Character}, then the effects of the subprograms in | |
ad42149c | 4621 | @code{Characters.Handling} should reflect the localizations. See also |
41af791f GB |
4622 | 3.5.2. |
4623 | @end cartouche | |
ad42149c | 4624 | Followed. GNAT provides no such localized definitions. |
41af791f GB |
4625 | |
4626 | @cindex Bounded-length strings | |
4627 | @item A.4.4(106): Bounded-Length String Handling | |
4628 | @sp 1 | |
4629 | @cartouche | |
4630 | Bounded string objects should not be implemented by implicit pointers | |
4631 | and dynamic allocation. | |
4632 | @end cartouche | |
ad42149c | 4633 | Followed. No implicit pointers or dynamic allocation are used. |
41af791f GB |
4634 | |
4635 | @cindex Random number generation | |
4636 | @item A.5.2(46-47): Random Number Generation | |
4637 | @sp 1 | |
4638 | @cartouche | |
4639 | Any storage associated with an object of type @code{Generator} should be | |
4640 | reclaimed on exit from the scope of the object. | |
4641 | @end cartouche | |
4642 | Followed. | |
4643 | ||
4644 | @sp 1 | |
4645 | @cartouche | |
4646 | If the generator period is sufficiently long in relation to the number | |
4647 | of distinct initiator values, then each possible value of | |
4648 | @code{Initiator} passed to @code{Reset} should initiate a sequence of | |
4649 | random numbers that does not, in a practical sense, overlap the sequence | |
ad42149c | 4650 | initiated by any other value. If this is not possible, then the mapping |
41af791f GB |
4651 | between initiator values and generator states should be a rapidly |
4652 | varying function of the initiator value. | |
4653 | @end cartouche | |
ad42149c | 4654 | Followed. The generator period is sufficiently long for the first |
41af791f GB |
4655 | condition here to hold true. |
4656 | ||
4657 | @findex Get_Immediate | |
4658 | @item A.10.7(23): @code{Get_Immediate} | |
4659 | @sp 1 | |
4660 | @cartouche | |
4661 | The @code{Get_Immediate} procedures should be implemented with | |
ad42149c | 4662 | unbuffered input. For a device such as a keyboard, input should be |
41af791f | 4663 | @dfn{available} if a key has already been typed, whereas for a disk |
ad42149c | 4664 | file, input should always be available except at end of file. For a file |
41af791f GB |
4665 | associated with a keyboard-like device, any line-editing features of the |
4666 | underlying operating system should be disabled during the execution of | |
4667 | @code{Get_Immediate}. | |
4668 | @end cartouche | |
4669 | Followed. | |
4670 | ||
4671 | @findex Export | |
4672 | @item B.1(39-41): Pragma @code{Export} | |
4673 | @sp 1 | |
4674 | @cartouche | |
4675 | If an implementation supports pragma @code{Export} to a given language, | |
4676 | then it should also allow the main subprogram to be written in that | |
ad42149c | 4677 | language. It should support some mechanism for invoking the elaboration |
41af791f | 4678 | of the Ada library units included in the system, and for invoking the |
ad42149c | 4679 | finalization of the environment task. On typical systems, the |
41af791f | 4680 | recommended mechanism is to provide two subprograms whose link names are |
ad42149c FW |
4681 | @code{adainit} and @code{adafinal}. @code{adainit} should contain the |
4682 | elaboration code for library units. @code{adafinal} should contain the | |
4683 | finalization code. These subprograms should have no effect the second | |
41af791f GB |
4684 | and subsequent time they are called. |
4685 | @end cartouche | |
4686 | Followed. | |
4687 | ||
4688 | @sp 1 | |
4689 | @cartouche | |
4690 | Automatic elaboration of pre-elaborated packages should be | |
ad42149c | 4691 | provided when pragma @code{Export} is supported. |
41af791f | 4692 | @end cartouche |
ad42149c | 4693 | Followed when the main program is in Ada. If the main program is in a |
41af791f GB |
4694 | foreign language, then |
4695 | @code{adainit} must be called to elaborate pre-elaborated | |
4696 | packages. | |
4697 | ||
4698 | @sp 1 | |
4699 | @cartouche | |
4700 | For each supported convention @var{L} other than @code{Intrinsic}, an | |
4701 | implementation should support @code{Import} and @code{Export} pragmas | |
4702 | for objects of @var{L}-compatible types and for subprograms, and pragma | |
4703 | @code{Convention} for @var{L}-eligible types and for subprograms, | |
ad42149c | 4704 | presuming the other language has corresponding features. Pragma |
41af791f GB |
4705 | @code{Convention} need not be supported for scalar types. |
4706 | @end cartouche | |
4707 | Followed. | |
4708 | ||
4709 | @cindex Package @code{Interfaces} | |
4710 | @findex Interfaces | |
4711 | @item B.2(12-13): Package @code{Interfaces} | |
4712 | @sp 1 | |
4713 | @cartouche | |
4714 | For each implementation-defined convention identifier, there should be a | |
ad42149c | 4715 | child package of package Interfaces with the corresponding name. This |
41af791f GB |
4716 | package should contain any declarations that would be useful for |
4717 | interfacing to the language (implementation) represented by the | |
ad42149c | 4718 | convention. Any declarations useful for interfacing to any language on |
41af791f GB |
4719 | the given hardware architecture should be provided directly in |
4720 | @code{Interfaces}. | |
4721 | @end cartouche | |
ad42149c | 4722 | Followed. An additional package not defined |
41af791f GB |
4723 | in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used |
4724 | for interfacing to C++. | |
4725 | ||
4726 | @sp 1 | |
4727 | @cartouche | |
4728 | An implementation supporting an interface to C, COBOL, or Fortran should | |
4729 | provide the corresponding package or packages described in the following | |
4730 | clauses. | |
4731 | @end cartouche | |
ad42149c | 4732 | Followed. GNAT provides all the packages described in this section. |
41af791f GB |
4733 | |
4734 | @cindex C, interfacing with | |
4735 | @item B.3(63-71): Interfacing with C | |
4736 | @sp 1 | |
4737 | @cartouche | |
4738 | An implementation should support the following interface correspondences | |
46b58b8c | 4739 | between Ada and C@. |
41af791f GB |
4740 | @end cartouche |
4741 | Followed. | |
4742 | ||
4743 | @sp 1 | |
4744 | @cartouche | |
4745 | An Ada procedure corresponds to a void-returning C function. | |
4746 | @end cartouche | |
4747 | Followed. | |
4748 | ||
4749 | @sp 1 | |
4750 | @cartouche | |
4751 | An Ada function corresponds to a non-void C function. | |
4752 | @end cartouche | |
4753 | Followed. | |
4754 | ||
4755 | @sp 1 | |
4756 | @cartouche | |
4757 | An Ada @code{in} scalar parameter is passed as a scalar argument to a C | |
4758 | function. | |
4759 | @end cartouche | |
4760 | Followed. | |
4761 | ||
4762 | @sp 1 | |
4763 | @cartouche | |
4764 | An Ada @code{in} parameter of an access-to-object type with designated | |
4765 | type @var{T} is passed as a @code{@var{t}*} argument to a C function, | |
4766 | where @var{t} is the C type corresponding to the Ada type @var{T}. | |
4767 | @end cartouche | |
4768 | Followed. | |
4769 | ||
4770 | @sp 1 | |
4771 | @cartouche | |
4772 | An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} | |
4773 | parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} | |
4774 | argument to a C function, where @var{t} is the C type corresponding to | |
ad42149c | 4775 | the Ada type @var{T}. In the case of an elementary @code{out} or |
41af791f GB |
4776 | @code{in out} parameter, a pointer to a temporary copy is used to |
4777 | preserve by-copy semantics. | |
4778 | @end cartouche | |
4779 | Followed. | |
4780 | ||
4781 | @sp 1 | |
4782 | @cartouche | |
4783 | An Ada parameter of a record type @var{T}, of any mode, is passed as a | |
4784 | @code{@var{t}*} argument to a C function, where @var{t} is the C | |
4785 | structure corresponding to the Ada type @var{T}. | |
4786 | @end cartouche | |
ad42149c | 4787 | Followed. This convention may be overridden by the use of the C_Pass_By_Copy |
41af791f GB |
4788 | pragma, or Convention, or by explicitly specifying the mechanism for a given |
4789 | call using an extended import or export pragma. | |
4790 | ||
4791 | @sp 1 | |
4792 | @cartouche | |
4793 | An Ada parameter of an array type with component type @var{T}, of any | |
4794 | mode, is passed as a @code{@var{t}*} argument to a C function, where | |
4795 | @var{t} is the C type corresponding to the Ada type @var{T}. | |
4796 | @end cartouche | |
4797 | Followed. | |
4798 | ||
4799 | @sp 1 | |
4800 | @cartouche | |
4801 | An Ada parameter of an access-to-subprogram type is passed as a pointer | |
4802 | to a C function whose prototype corresponds to the designated | |
4803 | subprogram's specification. | |
4804 | @end cartouche | |
4805 | Followed. | |
4806 | ||
4807 | @cindex COBOL, interfacing with | |
4808 | @item B.4(95-98): Interfacing with COBOL | |
4809 | @sp 1 | |
4810 | @cartouche | |
4811 | An Ada implementation should support the following interface | |
46b58b8c | 4812 | correspondences between Ada and COBOL@. |
41af791f GB |
4813 | @end cartouche |
4814 | Followed. | |
4815 | ||
4816 | @sp 1 | |
4817 | @cartouche | |
ad42149c | 4818 | An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of |
41af791f GB |
4819 | the COBOL type corresponding to @var{T}. |
4820 | @end cartouche | |
4821 | Followed. | |
4822 | ||
4823 | @sp 1 | |
4824 | @cartouche | |
ad42149c | 4825 | An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of |
41af791f GB |
4826 | the corresponding COBOL type. |
4827 | @end cartouche | |
4828 | Followed. | |
4829 | ||
4830 | @sp 1 | |
4831 | @cartouche | |
ad42149c | 4832 | Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the |
41af791f GB |
4833 | COBOL type corresponding to the Ada parameter type; for scalars, a local |
4834 | copy is used if necessary to ensure by-copy semantics. | |
4835 | @end cartouche | |
4836 | Followed. | |
4837 | ||
4838 | @cindex Fortran, interfacing with | |
4839 | @item B.5(22-26): Interfacing with Fortran | |
4840 | @sp 1 | |
4841 | @cartouche | |
4842 | An Ada implementation should support the following interface | |
4843 | correspondences between Ada and Fortran: | |
4844 | @end cartouche | |
4845 | Followed. | |
4846 | ||
4847 | @sp 1 | |
4848 | @cartouche | |
4849 | An Ada procedure corresponds to a Fortran subroutine. | |
4850 | @end cartouche | |
4851 | Followed. | |
4852 | ||
4853 | @sp 1 | |
4854 | @cartouche | |
4855 | An Ada function corresponds to a Fortran function. | |
4856 | @end cartouche | |
4857 | Followed. | |
4858 | ||
4859 | @sp 1 | |
4860 | @cartouche | |
4861 | An Ada parameter of an elementary, array, or record type @var{T} is | |
4862 | passed as a @var{T} argument to a Fortran procedure, where @var{T} is | |
4863 | the Fortran type corresponding to the Ada type @var{T}, and where the | |
4864 | INTENT attribute of the corresponding dummy argument matches the Ada | |
4865 | formal parameter mode; the Fortran implementation's parameter passing | |
ad42149c | 4866 | conventions are used. For elementary types, a local copy is used if |
41af791f GB |
4867 | necessary to ensure by-copy semantics. |
4868 | @end cartouche | |
4869 | Followed. | |
4870 | ||
4871 | @sp 1 | |
4872 | @cartouche | |
4873 | An Ada parameter of an access-to-subprogram type is passed as a | |
4874 | reference to a Fortran procedure whose interface corresponds to the | |
4875 | designated subprogram's specification. | |
4876 | @end cartouche | |
4877 | Followed. | |
4878 | ||
4879 | @cindex Machine operations | |
4880 | @item C.1(3-5): Access to Machine Operations | |
4881 | @sp 1 | |
4882 | @cartouche | |
4883 | The machine code or intrinsic support should allow access to all | |
4884 | operations normally available to assembly language programmers for the | |
4885 | target environment, including privileged instructions, if any. | |
4886 | @end cartouche | |
4887 | Followed. | |
4888 | ||
4889 | @sp 1 | |
4890 | @cartouche | |
4891 | The interfacing pragmas (see Annex B) should support interface to | |
4892 | assembler; the default assembler should be associated with the | |
4893 | convention identifier @code{Assembler}. | |
4894 | @end cartouche | |
4895 | Followed. | |
4896 | ||
4897 | @sp 1 | |
4898 | @cartouche | |
4899 | If an entity is exported to assembly language, then the implementation | |
4900 | should allocate it at an addressable location, and should ensure that it | |
4901 | is retained by the linking process, even if not otherwise referenced | |
ad42149c | 4902 | from the Ada code. The implementation should assume that any call to a |
41af791f GB |
4903 | machine code or assembler subprogram is allowed to read or update every |
4904 | object that is specified as exported. | |
4905 | @end cartouche | |
4906 | Followed. | |
4907 | ||
4908 | @item C.1(10-16): Access to Machine Operations | |
4909 | @sp 1 | |
4910 | @cartouche | |
4911 | The implementation should ensure that little or no overhead is | |
4912 | associated with calling intrinsic and machine-code subprograms. | |
4913 | @end cartouche | |
4914 | Followed for both intrinsics and machine-code subprograms. | |
4915 | ||
4916 | @sp 1 | |
4917 | @cartouche | |
4918 | It is recommended that intrinsic subprograms be provided for convenient | |
4919 | access to any machine operations that provide special capabilities or | |
4920 | efficiency and that are not otherwise available through the language | |
4921 | constructs. | |
4922 | @end cartouche | |
ad42149c | 4923 | Followed. A full set of machine operation intrinsic subprograms is provided. |
41af791f GB |
4924 | |
4925 | @sp 1 | |
4926 | @cartouche | |
ad42149c | 4927 | Atomic read-modify-write operations---e.g.@:, test and set, compare and |
41af791f GB |
4928 | swap, decrement and test, enqueue/dequeue. |
4929 | @end cartouche | |
4930 | Followed on any target supporting such operations. | |
4931 | ||
4932 | @sp 1 | |
4933 | @cartouche | |
ad42149c | 4934 | Standard numeric functions---e.g.@:, sin, log. |
41af791f GB |
4935 | @end cartouche |
4936 | Followed on any target supporting such operations. | |
4937 | ||
4938 | @sp 1 | |
4939 | @cartouche | |
ad42149c | 4940 | String manipulation operations---e.g.@:, translate and test. |
41af791f GB |
4941 | @end cartouche |
4942 | Followed on any target supporting such operations. | |
4943 | ||
4944 | @sp 1 | |
4945 | @cartouche | |
ad42149c | 4946 | Vector operations---e.g.@:, compare vector against thresholds. |
41af791f GB |
4947 | @end cartouche |
4948 | Followed on any target supporting such operations. | |
4949 | ||
4950 | @sp 1 | |
4951 | @cartouche | |
4952 | Direct operations on I/O ports. | |
4953 | @end cartouche | |
4954 | Followed on any target supporting such operations. | |
4955 | ||
4956 | @cindex Interrupt support | |
4957 | @item C.3(28): Interrupt Support | |
4958 | @sp 1 | |
4959 | @cartouche | |
4960 | If the @code{Ceiling_Locking} policy is not in effect, the | |
4961 | implementation should provide means for the application to specify which | |
4962 | interrupts are to be blocked during protected actions, if the underlying | |
4963 | system allows for a finer-grain control of interrupt blocking. | |
4964 | @end cartouche | |
ad42149c | 4965 | Followed. The underlying system does not allow for finer-grain control |
41af791f GB |
4966 | of interrupt blocking. |
4967 | ||
4968 | @cindex Protected procedure handlers | |
4969 | @item C.3.1(20-21): Protected Procedure Handlers | |
4970 | @sp 1 | |
4971 | @cartouche | |
4972 | Whenever possible, the implementation should allow interrupt handlers to | |
4973 | be called directly by the hardware. | |
4974 | @end cartouche | |
4975 | @c SGI info: | |
4976 | @ignore | |
4977 | This is never possible under IRIX, so this is followed by default. | |
4978 | @end ignore | |
4979 | Followed on any target where the underlying operating system permits | |
4980 | such direct calls. | |
4981 | ||
4982 | @sp 1 | |
4983 | @cartouche | |
4984 | Whenever practical, violations of any | |
4985 | implementation-defined restrictions should be detected before run time. | |
4986 | @end cartouche | |
ad42149c | 4987 | Followed. Compile time warnings are given when possible. |
41af791f GB |
4988 | |
4989 | @cindex Package @code{Interrupts} | |
4990 | @findex Interrupts | |
4991 | @item C.3.2(25): Package @code{Interrupts} | |
4992 | ||
4993 | @sp 1 | |
4994 | @cartouche | |
4995 | If implementation-defined forms of interrupt handler procedures are | |
4996 | supported, such as protected procedures with parameters, then for each | |
4997 | such form of a handler, a type analogous to @code{Parameterless_Handler} | |
4998 | should be specified in a child package of @code{Interrupts}, with the | |
4999 | same operations as in the predefined package Interrupts. | |
5000 | @end cartouche | |
5001 | Followed. | |
5002 | ||
5003 | @cindex Pre-elaboration requirements | |
5004 | @item C.4(14): Pre-elaboration Requirements | |
5005 | @sp 1 | |
5006 | @cartouche | |
5007 | It is recommended that pre-elaborated packages be implemented in such a | |
5008 | way that there should be little or no code executed at run time for the | |
5009 | elaboration of entities not already covered by the Implementation | |
5010 | Requirements. | |
5011 | @end cartouche | |
ad42149c | 5012 | Followed. Executable code is generated in some cases, e.g.@: loops |
41af791f GB |
5013 | to initialize large arrays. |
5014 | ||
5015 | @item C.5(8): Pragma @code{Discard_Names} | |
5016 | ||
5017 | @sp 1 | |
5018 | @cartouche | |
5019 | If the pragma applies to an entity, then the implementation should | |
5020 | reduce the amount of storage used for storing names associated with that | |
5021 | entity. | |
5022 | @end cartouche | |
5023 | Followed. | |
5024 | ||
5025 | @cindex Package @code{Task_Attributes} | |
5026 | @findex Task_Attributes | |
5027 | @item C.7.2(30): The Package Task_Attributes | |
5028 | @sp 1 | |
5029 | @cartouche | |
5030 | Some implementations are targeted to domains in which memory use at run | |
ad42149c | 5031 | time must be completely deterministic. For such implementations, it is |
41af791f | 5032 | recommended that the storage for task attributes will be pre-allocated |
ad42149c | 5033 | statically and not from the heap. This can be accomplished by either |
41af791f GB |
5034 | placing restrictions on the number and the size of the task's |
5035 | attributes, or by using the pre-allocated storage for the first @var{N} | |
ad42149c | 5036 | attribute objects, and the heap for the others. In the latter case, |
41af791f GB |
5037 | @var{N} should be documented. |
5038 | @end cartouche | |
ad42149c | 5039 | Not followed. This implementation is not targeted to such a domain. |
41af791f GB |
5040 | |
5041 | @cindex Locking Policies | |
5042 | @item D.3(17): Locking Policies | |
5043 | ||
5044 | @sp 1 | |
5045 | @cartouche | |
5046 | The implementation should use names that end with @samp{_Locking} for | |
5047 | locking policies defined by the implementation. | |
5048 | @end cartouche | |
ad42149c | 5049 | Followed. A single implementation-defined locking policy is defined, |
41af791f GB |
5050 | whose name (@code{Inheritance_Locking}) follows this suggestion. |
5051 | ||
5052 | @cindex Entry queuing policies | |
5053 | @item D.4(16): Entry Queuing Policies | |
5054 | @sp 1 | |
5055 | @cartouche | |
5056 | Names that end with @samp{_Queuing} should be used | |
5057 | for all implementation-defined queuing policies. | |
5058 | @end cartouche | |
ad42149c | 5059 | Followed. No such implementation-defined queueing policies exist. |
41af791f GB |
5060 | |
5061 | @cindex Preemptive abort | |
5062 | @item D.6(9-10): Preemptive Abort | |
5063 | @sp 1 | |
5064 | @cartouche | |
5065 | Even though the @code{abort_statement} is included in the list of | |
5066 | potentially blocking operations (see 9.5.1), it is recommended that this | |
5067 | statement be implemented in a way that never requires the task executing | |
5068 | the @code{abort_statement} to block. | |
5069 | @end cartouche | |
5070 | Followed. | |
5071 | ||
5072 | @sp 1 | |
5073 | @cartouche | |
5074 | On a multi-processor, the delay associated with aborting a task on | |
5075 | another processor should be bounded; the implementation should use | |
5076 | periodic polling, if necessary, to achieve this. | |
5077 | @end cartouche | |
5078 | Followed. | |
5079 | ||
5080 | @cindex Tasking restrictions | |
5081 | @item D.7(21): Tasking Restrictions | |
5082 | @sp 1 | |
5083 | @cartouche | |
5084 | When feasible, the implementation should take advantage of the specified | |
5085 | restrictions to produce a more efficient implementation. | |
5086 | @end cartouche | |
5087 | GNAT currently takes advantage of these restrictions by providing an optimized | |
5088 | run time when the Ravenscar profile and the GNAT restricted run time set | |
ad42149c | 5089 | of restrictions are specified. See pragma @code{Ravenscar} and pragma |
41af791f GB |
5090 | @code{Restricted_Run_Time} for more details. |
5091 | ||
5092 | @cindex Time, monotonic | |
5093 | @item D.8(47-49): Monotonic Time | |
5094 | @sp 1 | |
5095 | @cartouche | |
5096 | When appropriate, implementations should provide configuration | |
5097 | mechanisms to change the value of @code{Tick}. | |
5098 | @end cartouche | |
5099 | Such configuration mechanisms are not appropriate to this implementation | |
5100 | and are thus not supported. | |
5101 | ||
5102 | @sp 1 | |
5103 | @cartouche | |
5104 | It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} | |
5105 | be implemented as transformations of the same time base. | |
5106 | @end cartouche | |
5107 | Followed. | |
5108 | ||
5109 | @sp 1 | |
5110 | @cartouche | |
5111 | It is recommended that the @dfn{best} time base which exists in | |
5112 | the underlying system be available to the application through | |
ad42149c | 5113 | @code{Clock}. @dfn{Best} may mean highest accuracy or largest range. |
41af791f GB |
5114 | @end cartouche |
5115 | Followed. | |
5116 | ||
5117 | @cindex Partition communication subsystem | |
5118 | @cindex PCS | |
5119 | @item E.5(28-29): Partition Communication Subsystem | |
5120 | @sp 1 | |
5121 | @cartouche | |
5122 | Whenever possible, the PCS on the called partition should allow for | |
5123 | multiple tasks to call the RPC-receiver with different messages and | |
5124 | should allow them to block until the corresponding subprogram body | |
5125 | returns. | |
5126 | @end cartouche | |
5127 | Followed by GLADE, a separately supplied PCS that can be used with | |
ad42149c | 5128 | GNAT. |
41af791f GB |
5129 | |
5130 | @sp 1 | |
5131 | @cartouche | |
5132 | The @code{Write} operation on a stream of type @code{Params_Stream_Type} | |
5133 | should raise @code{Storage_Error} if it runs out of space trying to | |
5134 | write the @code{Item} into the stream. | |
5135 | @end cartouche | |
5136 | Followed by GLADE, a separately supplied PCS that can be used with | |
ad42149c | 5137 | GNAT@. |
41af791f GB |
5138 | |
5139 | @cindex COBOL support | |
5140 | @item F(7): COBOL Support | |
5141 | @sp 1 | |
5142 | @cartouche | |
5143 | If COBOL (respectively, C) is widely supported in the target | |
5144 | environment, implementations supporting the Information Systems Annex | |
5145 | should provide the child package @code{Interfaces.COBOL} (respectively, | |
5146 | @code{Interfaces.C}) specified in Annex B and should support a | |
5147 | @code{convention_identifier} of COBOL (respectively, C) in the interfacing | |
5148 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
5149 | programs written in that language. | |
5150 | @end cartouche | |
5151 | Followed. | |
5152 | ||
5153 | @cindex Decimal radix support | |
5154 | @item F.1(2): Decimal Radix Support | |
5155 | @sp 1 | |
5156 | @cartouche | |
5157 | Packed decimal should be used as the internal representation for objects | |
5158 | of subtype @var{S} when @var{S}'Machine_Radix = 10. | |
5159 | @end cartouche | |
ad42149c | 5160 | Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary |
41af791f GB |
5161 | representations. |
5162 | ||
5163 | @cindex Numerics | |
5164 | @item G: Numerics | |
5165 | @sp 2 | |
5166 | @cartouche | |
5167 | If Fortran (respectively, C) is widely supported in the target | |
5168 | environment, implementations supporting the Numerics Annex | |
5169 | should provide the child package @code{Interfaces.Fortran} (respectively, | |
5170 | @code{Interfaces.C}) specified in Annex B and should support a | |
5171 | @code{convention_identifier} of Fortran (respectively, C) in the interfacing | |
5172 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
5173 | programs written in that language. | |
5174 | @end cartouche | |
5175 | Followed. | |
5176 | ||
5177 | @cindex Complex types | |
5178 | @item G.1.1(56-58): Complex Types | |
5179 | @sp 2 | |
5180 | @cartouche | |
5181 | Because the usual mathematical meaning of multiplication of a complex | |
5182 | operand and a real operand is that of the scaling of both components of | |
5183 | the former by the latter, an implementation should not perform this | |
5184 | operation by first promoting the real operand to complex type and then | |
ad42149c | 5185 | performing a full complex multiplication. In systems that, in the |
41af791f GB |
5186 | future, support an Ada binding to IEC 559:1989, the latter technique |
5187 | will not generate the required result when one of the components of the | |
ad42149c | 5188 | complex operand is infinite. (Explicit multiplication of the infinite |
41af791f GB |
5189 | component by the zero component obtained during promotion yields a NaN |
5190 | that propagates into the final result.) Analogous advice applies in the | |
5191 | case of multiplication of a complex operand and a pure-imaginary | |
5192 | operand, and in the case of division of a complex operand by a real or | |
5193 | pure-imaginary operand. | |
5194 | @end cartouche | |
5195 | Not followed. | |
5196 | ||
5197 | @sp 1 | |
5198 | @cartouche | |
5199 | Similarly, because the usual mathematical meaning of addition of a | |
5200 | complex operand and a real operand is that the imaginary operand remains | |
5201 | unchanged, an implementation should not perform this operation by first | |
5202 | promoting the real operand to complex type and then performing a full | |
ad42149c | 5203 | complex addition. In implementations in which the @code{Signed_Zeros} |
41af791f GB |
5204 | attribute of the component type is @code{True} (and which therefore |
5205 | conform to IEC 559:1989 in regard to the handling of the sign of zero in | |
5206 | predefined arithmetic operations), the latter technique will not | |
5207 | generate the required result when the imaginary component of the complex | |
ad42149c | 5208 | operand is a negatively signed zero. (Explicit addition of the negative |
41af791f GB |
5209 | zero to the zero obtained during promotion yields a positive zero.) |
5210 | Analogous advice applies in the case of addition of a complex operand | |
5211 | and a pure-imaginary operand, and in the case of subtraction of a | |
5212 | complex operand and a real or pure-imaginary operand. | |
5213 | @end cartouche | |
5214 | Not followed. | |
5215 | ||
5216 | @sp 1 | |
5217 | @cartouche | |
5218 | Implementations in which @code{Real'Signed_Zeros} is @code{True} should | |
5219 | attempt to provide a rational treatment of the signs of zero results and | |
ad42149c | 5220 | result components. As one example, the result of the @code{Argument} |
41af791f GB |
5221 | function should have the sign of the imaginary component of the |
5222 | parameter @code{X} when the point represented by that parameter lies on | |
5223 | the positive real axis; as another, the sign of the imaginary component | |
5224 | of the @code{Compose_From_Polar} function should be the same as | |
5225 | (respectively, the opposite of) that of the @code{Argument} parameter when that | |
5226 | parameter has a value of zero and the @code{Modulus} parameter has a | |
5227 | nonnegative (respectively, negative) value. | |
5228 | @end cartouche | |
5229 | Followed. | |
5230 | ||
5231 | @cindex Complex elementary functions | |
5232 | @item G.1.2(49): Complex Elementary Functions | |
5233 | @sp 1 | |
5234 | @cartouche | |
5235 | Implementations in which @code{Complex_Types.Real'Signed_Zeros} is | |
5236 | @code{True} should attempt to provide a rational treatment of the signs | |
ad42149c | 5237 | of zero results and result components. For example, many of the complex |
41af791f GB |
5238 | elementary functions have components that are odd functions of one of |
5239 | the parameter components; in these cases, the result component should | |
ad42149c | 5240 | have the sign of the parameter component at the origin. Other complex |
41af791f GB |
5241 | elementary functions have zero components whose sign is opposite that of |
5242 | a parameter component at the origin, or is always positive or always | |
5243 | negative. | |
5244 | @end cartouche | |
5245 | Followed. | |
5246 | ||
5247 | @cindex Accuracy requirements | |
5248 | @item G.2.4(19): Accuracy Requirements | |
5249 | @sp 1 | |
5250 | @cartouche | |
5251 | The versions of the forward trigonometric functions without a | |
5252 | @code{Cycle} parameter should not be implemented by calling the | |
5253 | corresponding version with a @code{Cycle} parameter of | |
5254 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
ad42149c | 5255 | accuracy in some portions of the domain. For the same reason, the |
41af791f GB |
5256 | version of @code{Log} without a @code{Base} parameter should not be |
5257 | implemented by calling the corresponding version with a @code{Base} | |
5258 | parameter of @code{Numerics.e}. | |
5259 | @end cartouche | |
5260 | Followed. | |
5261 | ||
5262 | @cindex Complex arithmetic accuracy | |
5263 | @cindex Accuracy, complex arithmetic | |
5264 | @item G.2.6(15): Complex Arithmetic Accuracy | |
5265 | ||
5266 | @sp 1 | |
5267 | @cartouche | |
5268 | The version of the @code{Compose_From_Polar} function without a | |
5269 | @code{Cycle} parameter should not be implemented by calling the | |
5270 | corresponding version with a @code{Cycle} parameter of | |
5271 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
5272 | accuracy in some portions of the domain. | |
5273 | @end cartouche | |
5274 | Followed. | |
5275 | ||
5276 | @end table | |
5277 | @node Implementation Defined Characteristics | |
5278 | @chapter Implementation Defined Characteristics | |
5279 | In addition to the implementation dependent pragmas and attributes, and | |
5280 | the implementation advice, there are a number of other features of Ada | |
ad42149c | 5281 | 95 that are potentially implementation dependent. These are mentioned |
46b58b8c | 5282 | throughout the Ada 95 Reference Manual, and are summarized in annex M@. |
41af791f GB |
5283 | |
5284 | A requirement for conforming Ada compilers is that they provide | |
5285 | documentation describing how the implementation deals with each of these | |
ad42149c | 5286 | issues. In this chapter, you will find each point in annex M listed |
41af791f GB |
5287 | followed by a description in italic font of how GNAT |
5288 | @c SGI info: | |
5289 | @ignore | |
5290 | in the ProDev Ada | |
5291 | implementation on IRIX 5.3 operating system or greater | |
5292 | @end ignore | |
5293 | handles the implementation dependence. | |
5294 | ||
5295 | You can use this chapter as a guide to minimizing implementation | |
5296 | dependent features in your programs if portability to other compilers | |
5297 | and other operating systems is an important consideration. The numbers | |
5298 | in each section below correspond to the paragraph number in the Ada 95 | |
5299 | Reference Manual. | |
5300 | ||
5301 | @sp 1 | |
5302 | @cartouche | |
5303 | @noindent | |
5304 | @strong{2}. Whether or not each recommendation given in Implementation | |
ad42149c | 5305 | Advice is followed. See 1.1.2(37). |
41af791f GB |
5306 | @end cartouche |
5307 | @noindent | |
5308 | @xref{Implementation Advice}. | |
5309 | ||
5310 | @sp 1 | |
5311 | @cartouche | |
5312 | @noindent | |
ad42149c | 5313 | @strong{3}. Capacity limitations of the implementation. See 1.1.3(3). |
41af791f GB |
5314 | @end cartouche |
5315 | @noindent | |
5316 | The complexity of programs that can be processed is limited only by the | |
5317 | total amount of available virtual memory, and disk space for the | |
5318 | generated object files. | |
5319 | ||
5320 | @sp 1 | |
5321 | @cartouche | |
5322 | @noindent | |
5323 | @strong{4}. Variations from the standard that are impractical to avoid | |
ad42149c | 5324 | given the implementation's execution environment. See 1.1.3(6). |
41af791f GB |
5325 | @end cartouche |
5326 | @noindent | |
5327 | There are no variations from the standard. | |
5328 | ||
5329 | @sp 1 | |
5330 | @cartouche | |
5331 | @noindent | |
5332 | @strong{5}. Which @code{code_statement}s cause external | |
ad42149c | 5333 | interactions. See 1.1.3(10). |
41af791f GB |
5334 | @end cartouche |
5335 | @noindent | |
5336 | Any @code{code_statement} can potentially cause external interactions. | |
5337 | ||
5338 | @sp 1 | |
5339 | @cartouche | |
5340 | @noindent | |
5341 | @strong{6}. The coded representation for the text of an Ada | |
ad42149c | 5342 | program. See 2.1(4). |
41af791f GB |
5343 | @end cartouche |
5344 | @noindent | |
5345 | See separate section on source representation. | |
5346 | ||
5347 | @sp 1 | |
5348 | @cartouche | |
5349 | @noindent | |
ad42149c | 5350 | @strong{7}. The control functions allowed in comments. See 2.1(14). |
41af791f GB |
5351 | @end cartouche |
5352 | @noindent | |
5353 | See separate section on source representation. | |
5354 | ||
5355 | @sp 1 | |
5356 | @cartouche | |
5357 | @noindent | |
ad42149c | 5358 | @strong{8}. The representation for an end of line. See 2.2(2). |
41af791f GB |
5359 | @end cartouche |
5360 | @noindent | |
5361 | See separate section on source representation. | |
5362 | ||
5363 | @sp 1 | |
5364 | @cartouche | |
5365 | @noindent | |
5366 | @strong{9}. Maximum supported line length and lexical element | |
ad42149c | 5367 | length. See 2.2(15). |
41af791f GB |
5368 | @end cartouche |
5369 | @noindent | |
5370 | The maximum line length is 255 characters an the maximum length of a | |
5371 | lexical element is also 255 characters. | |
5372 | ||
5373 | @sp 1 | |
5374 | @cartouche | |
5375 | @noindent | |
ad42149c | 5376 | @strong{10}. Implementation defined pragmas. See 2.8(14). |
41af791f GB |
5377 | @end cartouche |
5378 | @noindent | |
5379 | ||
5380 | @xref{Implementation Defined Pragmas}. | |
5381 | ||
5382 | @sp 1 | |
5383 | @cartouche | |
5384 | @noindent | |
ad42149c | 5385 | @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). |
41af791f GB |
5386 | @end cartouche |
5387 | @noindent | |
5388 | Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} | |
5389 | parameter, checks that the optimization flag is set, and aborts if it is | |
5390 | not. | |
5391 | ||
5392 | @sp 1 | |
5393 | @cartouche | |
5394 | @noindent | |
5395 | @strong{12}. The sequence of characters of the value returned by | |
5396 | @code{@var{S}'Image} when some of the graphic characters of | |
ad42149c | 5397 | @code{@var{S}'Wide_Image} are not defined in @code{Character}. See |
41af791f GB |
5398 | 3.5(37). |
5399 | @end cartouche | |
5400 | @noindent | |
5401 | The sequence of characters is as defined by the wide character encoding | |
ad42149c | 5402 | method used for the source. See section on source representation for |
41af791f GB |
5403 | further details. |
5404 | ||
5405 | @sp 1 | |
5406 | @cartouche | |
5407 | @noindent | |
5408 | @strong{13}. The predefined integer types declared in | |
ad42149c | 5409 | @code{Standard}. See 3.5.4(25). |
41af791f GB |
5410 | @end cartouche |
5411 | @noindent | |
5412 | @table @code | |
5413 | @item Short_Short_Integer | |
5414 | 8 bit signed | |
5415 | @item Short_Integer | |
5416 | (Short) 16 bit signed | |
5417 | @item Integer | |
5418 | 32 bit signed | |
5419 | @item Long_Integer | |
5420 | 64 bit signed (Alpha OpenVMS only) | |
5421 | 32 bit signed (all other targets) | |
5422 | @item Long_Long_Integer | |
5423 | 64 bit signed | |
5424 | @end table | |
5425 | ||
5426 | @sp 1 | |
5427 | @cartouche | |
5428 | @noindent | |
5429 | @strong{14}. Any nonstandard integer types and the operators defined | |
ad42149c | 5430 | for them. See 3.5.4(26). |
41af791f GB |
5431 | @end cartouche |
5432 | @noindent | |
5433 | There are no nonstandard integer types. | |
5434 | ||
5435 | @sp 1 | |
5436 | @cartouche | |
5437 | @noindent | |
5438 | @strong{15}. Any nonstandard real types and the operators defined for | |
ad42149c | 5439 | them. See 3.5.6(8). |
41af791f GB |
5440 | @end cartouche |
5441 | @noindent | |
5442 | There are no nonstandard real types. | |
5443 | ||
5444 | @sp 1 | |
5445 | @cartouche | |
5446 | @noindent | |
5447 | @strong{16}. What combinations of requested decimal precision and range | |
ad42149c | 5448 | are supported for floating point types. See 3.5.7(7). |
41af791f GB |
5449 | @end cartouche |
5450 | @noindent | |
5451 | The precision and range is as defined by the IEEE standard. | |
5452 | ||
5453 | @sp 1 | |
5454 | @cartouche | |
5455 | @noindent | |
5456 | @strong{17}. The predefined floating point types declared in | |
ad42149c | 5457 | @code{Standard}. See 3.5.7(16). |
41af791f GB |
5458 | @end cartouche |
5459 | @noindent | |
5460 | @table @code | |
5461 | @item Short_Float | |
5462 | 32 bit IEEE short | |
5463 | @item Float | |
5464 | (Short) 32 bit IEEE short | |
5465 | @item Long_Float | |
5466 | 64 bit IEEE long | |
5467 | @item Long_Long_Float | |
5468 | 64 bit IEEE long (80 bit IEEE long on x86 processors) | |
5469 | @end table | |
5470 | ||
5471 | @sp 1 | |
5472 | @cartouche | |
5473 | @noindent | |
ad42149c | 5474 | @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). |
41af791f GB |
5475 | @end cartouche |
5476 | @noindent | |
ad42149c | 5477 | @code{Fine_Delta} is 2**(@minus{}63) |
41af791f GB |
5478 | |
5479 | @sp 1 | |
5480 | @cartouche | |
5481 | @noindent | |
5482 | @strong{19}. What combinations of small, range, and digits are | |
ad42149c | 5483 | supported for fixed point types. See 3.5.9(10). |
41af791f GB |
5484 | @end cartouche |
5485 | @noindent | |
5486 | Any combinations are permitted that do not result in a small less than | |
5487 | @code{Fine_Delta} and do not result in a mantissa larger than 63 bits. | |
5488 | If the mantissa is larger than 53 bits on machines where Long_Long_Float | |
5489 | is 64 bits (true of all architectures except ia32), then the output from | |
ad42149c | 5490 | Text_IO is accurate to only 53 bits, rather than the full mantissa. This |
41af791f GB |
5491 | is because floating-point conversions are used to convert fixed point. |
5492 | ||
5493 | @sp 1 | |
5494 | @cartouche | |
5495 | @noindent | |
5496 | @strong{20}. The result of @code{Tags.Expanded_Name} for types declared | |
ad42149c | 5497 | within an unnamed @code{block_statement}. See 3.9(10). |
41af791f GB |
5498 | @end cartouche |
5499 | @noindent | |
5500 | Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a | |
5501 | decimal integer are allocated. | |
5502 | ||
5503 | @sp 1 | |
5504 | @cartouche | |
5505 | @noindent | |
ad42149c | 5506 | @strong{21}. Implementation-defined attributes. See 4.1.4(12). |
41af791f GB |
5507 | @end cartouche |
5508 | @noindent | |
5509 | @xref{Implementation Defined Attributes}. | |
5510 | ||
5511 | @sp 1 | |
5512 | @cartouche | |
5513 | @noindent | |
ad42149c | 5514 | @strong{22}. Any implementation-defined time types. See 9.6(6). |
41af791f GB |
5515 | @end cartouche |
5516 | @noindent | |
5517 | There are no implementation-defined time types. | |
5518 | ||
5519 | @sp 1 | |
5520 | @cartouche | |
5521 | @noindent | |
5522 | @strong{23}. The time base associated with relative delays. | |
5523 | @end cartouche | |
5524 | @noindent | |
ad42149c | 5525 | See 9.6(20). The time base used is that provided by the C library |
41af791f GB |
5526 | function @code{gettimeofday}. |
5527 | ||
5528 | @sp 1 | |
5529 | @cartouche | |
5530 | @noindent | |
ad42149c | 5531 | @strong{24}. The time base of the type @code{Calendar.Time}. See |
41af791f GB |
5532 | 9.6(23). |
5533 | @end cartouche | |
5534 | @noindent | |
5535 | The time base used is that provided by the C library function | |
5536 | @code{gettimeofday}. | |
5537 | ||
5538 | @sp 1 | |
5539 | @cartouche | |
5540 | @noindent | |
5541 | @strong{25}. The time zone used for package @code{Calendar} | |
ad42149c | 5542 | operations. See 9.6(24). |
41af791f GB |
5543 | @end cartouche |
5544 | @noindent | |
5545 | The time zone used by package @code{Calendar} is the current system time zone | |
5546 | setting for local time, as accessed by the C library function | |
5547 | @code{localtime}. | |
5548 | ||
5549 | @sp 1 | |
5550 | @cartouche | |
5551 | @noindent | |
5552 | @strong{26}. Any limit on @code{delay_until_statements} of | |
ad42149c | 5553 | @code{select_statements}. See 9.6(29). |
41af791f GB |
5554 | @end cartouche |
5555 | @noindent | |
5556 | There are no such limits. | |
5557 | ||
5558 | @sp 1 | |
5559 | @cartouche | |
5560 | @noindent | |
5561 | @strong{27}. Whether or not two non overlapping parts of a composite | |
5562 | object are independently addressable, in the case where packing, record | |
ad42149c | 5563 | layout, or @code{Component_Size} is specified for the object. See |
41af791f GB |
5564 | 9.10(1). |
5565 | @end cartouche | |
5566 | @noindent | |
5567 | Separate components are independently addressable if they do not share | |
5568 | overlapping storage units. | |
5569 | ||
5570 | @sp 1 | |
5571 | @cartouche | |
5572 | @noindent | |
ad42149c | 5573 | @strong{28}. The representation for a compilation. See 10.1(2). |
41af791f GB |
5574 | @end cartouche |
5575 | @noindent | |
5576 | A compilation is represented by a sequence of files presented to the | |
ad42149c | 5577 | compiler in a single invocation of the @code{gcc} command. |
41af791f GB |
5578 | |
5579 | @sp 1 | |
5580 | @cartouche | |
5581 | @noindent | |
5582 | @strong{29}. Any restrictions on compilations that contain multiple | |
ad42149c | 5583 | compilation_units. See 10.1(4). |
41af791f GB |
5584 | @end cartouche |
5585 | @noindent | |
5586 | No single file can contain more than one compilation unit, but any | |
5587 | sequence of files can be presented to the compiler as a single | |
5588 | compilation. | |
5589 | ||
5590 | @sp 1 | |
5591 | @cartouche | |
5592 | @noindent | |
5593 | @strong{30}. The mechanisms for creating an environment and for adding | |
ad42149c | 5594 | and replacing compilation units. See 10.1.4(3). |
41af791f GB |
5595 | @end cartouche |
5596 | @noindent | |
5597 | See separate section on compilation model. | |
5598 | ||
5599 | @sp 1 | |
5600 | @cartouche | |
5601 | @noindent | |
5602 | @strong{31}. The manner of explicitly assigning library units to a | |
ad42149c | 5603 | partition. See 10.2(2). |
41af791f GB |
5604 | @end cartouche |
5605 | @noindent | |
5606 | If a unit contains an Ada main program, then the Ada units for the partition | |
5607 | are determined by recursive application of the rules in the Ada Reference | |
ad42149c | 5608 | Manual section 10.2(2-6). In other words, the Ada units will be those that |
41af791f GB |
5609 | are needed by the main program, and then this definition of need is applied |
5610 | recursively to those units, and the partition contains the transitive | |
ad42149c FW |
5611 | closure determined by this relationship. In short, all the necessary units |
5612 | are included, with no need to explicitly specify the list. If additional | |
46b58b8c | 5613 | units are required, e.g.@: by foreign language units, then all units must be |
41af791f GB |
5614 | mentioned in the context clause of one of the needed Ada units. |
5615 | ||
5616 | If the partition contains no main program, or if the main program is in | |
5617 | a language other than Ada, then GNAT | |
ad42149c | 5618 | provides the binder options @code{-z} and @code{-n} respectively, and in this case a |
41af791f GB |
5619 | list of units can be explicitly supplied to the binder for inclusion in |
5620 | the partition (all units needed by these units will also be included | |
ad42149c FW |
5621 | automatically). For full details on the use of these options, refer to |
5622 | the @cite{GNAT User's Guide} sections on Binding and Linking. | |
41af791f GB |
5623 | |
5624 | @sp 1 | |
5625 | @cartouche | |
5626 | @noindent | |
5627 | @strong{32}. The implementation-defined means, if any, of specifying | |
ad42149c | 5628 | which compilation units are needed by a given compilation unit. See |
41af791f GB |
5629 | 10.2(2). |
5630 | @end cartouche | |
5631 | @noindent | |
5632 | The units needed by a given compilation unit are as defined in | |
ad42149c | 5633 | the Ada Reference Manual section 10.2(2-6). There are no |
41af791f GB |
5634 | implementation-defined pragmas or other implementation-defined |
5635 | means for specifying needed units. | |
5636 | ||
5637 | @sp 1 | |
5638 | @cartouche | |
5639 | @noindent | |
5640 | @strong{33}. The manner of designating the main subprogram of a | |
ad42149c | 5641 | partition. See 10.2(7). |
41af791f GB |
5642 | @end cartouche |
5643 | @noindent | |
5644 | The main program is designated by providing the name of the | |
ad42149c | 5645 | corresponding @file{ALI} file as the input parameter to the binder. |
41af791f GB |
5646 | |
5647 | @sp 1 | |
5648 | @cartouche | |
5649 | @noindent | |
ad42149c | 5650 | @strong{34}. The order of elaboration of @code{library_items}. See |
41af791f GB |
5651 | 10.2(18). |
5652 | @end cartouche | |
5653 | @noindent | |
5654 | The first constraint on ordering is that it meets the requirements of | |
ad42149c | 5655 | chapter 10 of the Ada 95 Reference Manual. This still leaves some |
41af791f | 5656 | implementation dependent choices, which are resolved by first |
46b58b8c | 5657 | elaborating bodies as early as possible (i.e.@: in preference to specs |
41af791f GB |
5658 | where there is a choice), and second by evaluating the immediate with |
5659 | clauses of a unit to determine the probably best choice, and | |
5660 | third by elaborating in alphabetical order of unit names | |
5661 | where a choice still remains. | |
5662 | ||
5663 | @sp 1 | |
5664 | @cartouche | |
5665 | @noindent | |
5666 | @strong{35}. Parameter passing and function return for the main | |
ad42149c | 5667 | subprogram. See 10.2(21). |
41af791f GB |
5668 | @end cartouche |
5669 | @noindent | |
ad42149c FW |
5670 | The main program has no parameters. It may be a procedure, or a function |
5671 | returning an integer type. In the latter case, the returned integer | |
41af791f GB |
5672 | value is the return code of the program. |
5673 | ||
5674 | @sp 1 | |
5675 | @cartouche | |
5676 | @noindent | |
ad42149c | 5677 | @strong{36}. The mechanisms for building and running partitions. See |
41af791f GB |
5678 | 10.2(24). |
5679 | @end cartouche | |
5680 | @noindent | |
ad42149c | 5681 | GNAT itself supports programs with only a single partition. The GNATDIST |
41af791f GB |
5682 | tool provided with the GLADE package (which also includes an implementation |
5683 | of the PCS) provides a completely flexible method for building and running | |
ad42149c | 5684 | programs consisting of multiple partitions. See the separate GLADE manual |
41af791f GB |
5685 | for details. |
5686 | ||
5687 | @sp 1 | |
5688 | @cartouche | |
5689 | @noindent | |
5690 | @strong{37}. The details of program execution, including program | |
ad42149c | 5691 | termination. See 10.2(25). |
41af791f GB |
5692 | @end cartouche |
5693 | @noindent | |
5694 | See separate section on compilation model. | |
5695 | ||
5696 | @sp 1 | |
5697 | @cartouche | |
5698 | @noindent | |
5699 | @strong{38}. The semantics of any non-active partitions supported by the | |
ad42149c | 5700 | implementation. See 10.2(28). |
41af791f GB |
5701 | @end cartouche |
5702 | @noindent | |
5703 | Passive partitions are supported on targets where shared memory is | |
ad42149c | 5704 | provided by the operating system. See the GLADE reference manual for |
41af791f GB |
5705 | further details. |
5706 | ||
5707 | @sp 1 | |
5708 | @cartouche | |
5709 | @noindent | |
ad42149c | 5710 | @strong{39}. The information returned by @code{Exception_Message}. See |
41af791f GB |
5711 | 11.4.1(10). |
5712 | @end cartouche | |
5713 | @noindent | |
5714 | Exception message returns the null string unless a specific message has | |
5715 | been passed by the program. | |
5716 | ||
5717 | @sp 1 | |
5718 | @cartouche | |
5719 | @noindent | |
5720 | @strong{40}. The result of @code{Exceptions.Exception_Name} for types | |
ad42149c | 5721 | declared within an unnamed @code{block_statement}. See 11.4.1(12). |
41af791f GB |
5722 | @end cartouche |
5723 | @noindent | |
5724 | Blocks have implementation defined names of the form @code{B@var{nnn}} | |
5725 | where @var{nnn} is an integer. | |
5726 | ||
5727 | @sp 1 | |
5728 | @cartouche | |
5729 | @noindent | |
5730 | @strong{41}. The information returned by | |
ad42149c | 5731 | @code{Exception_Information}. See 11.4.1(13). |
41af791f GB |
5732 | @end cartouche |
5733 | @noindent | |
ad42149c FW |
5734 | @code{Exception_Information} returns a string in the following format: |
5735 | ||
5736 | @smallexample | |
5737 | @emph{Exception_Name:} nnnnn | |
5738 | @emph{Message:} mmmmm | |
5739 | @emph{PID:} ppp | |
5740 | @emph{Call stack traceback locations:} | |
5741 | 0xhhhh 0xhhhh 0xhhhh ... 0xhhh | |
5742 | @end smallexample | |
5743 | ||
5744 | @noindent | |
5745 | where | |
5746 | ||
5747 | @itemize @bullet | |
5748 | @item | |
5749 | @code{nnnn} is the fully qualified name of the exception in all upper | |
5750 | case letters. This line is always present. | |
5751 | ||
5752 | @item | |
5753 | @code{mmmm} is the message (this line present only if message is non-null) | |
5754 | ||
5755 | @item | |
5756 | @code{ppp} is the Process Id value as a decimal integer (this line is | |
5757 | present only if the Process Id is non-zero). Currently we are | |
5758 | not making use of this field. | |
5759 | ||
5760 | @item | |
5761 | The Call stack traceback locations line and the following values | |
5762 | are present only if at least one traceback location was recorded. | |
5763 | The values are given in C style format, with lower case letters | |
5764 | for a-f, and only as many digits present as are necessary. | |
5765 | @end itemize | |
5766 | ||
5767 | @noindent | |
5768 | The line terminator sequence at the end of each line, including | |
5769 | the last line is a single @code{LF} character (@code{16#0A#}). | |
41af791f GB |
5770 | |
5771 | @sp 1 | |
5772 | @cartouche | |
5773 | @noindent | |
ad42149c | 5774 | @strong{42}. Implementation-defined check names. See 11.5(27). |
41af791f GB |
5775 | @end cartouche |
5776 | @noindent | |
5777 | No implementation-defined check names are supported. | |
5778 | ||
5779 | @sp 1 | |
5780 | @cartouche | |
5781 | @noindent | |
ad42149c | 5782 | @strong{43}. The interpretation of each aspect of representation. See |
41af791f GB |
5783 | 13.1(20). |
5784 | @end cartouche | |
5785 | @noindent | |
5786 | See separate section on data representations. | |
5787 | ||
5788 | @sp 1 | |
5789 | @cartouche | |
5790 | @noindent | |
ad42149c | 5791 | @strong{44}. Any restrictions placed upon representation items. See |
41af791f GB |
5792 | 13.1(20). |
5793 | @end cartouche | |
5794 | @noindent | |
5795 | See separate section on data representations. | |
5796 | ||
5797 | @sp 1 | |
5798 | @cartouche | |
5799 | @noindent | |
ad42149c | 5800 | @strong{45}. The meaning of @code{Size} for indefinite subtypes. See |
41af791f GB |
5801 | 13.3(48). |
5802 | @end cartouche | |
5803 | @noindent | |
5804 | Size for an indefinite subtype is the maximum possible size, except that | |
5805 | for the case of a subprogram parameter, the size of the parameter object | |
5806 | is the actual size. | |
5807 | ||
5808 | @sp 1 | |
5809 | @cartouche | |
5810 | @noindent | |
ad42149c | 5811 | @strong{46}. The default external representation for a type tag. See |
41af791f GB |
5812 | 13.3(75). |
5813 | @end cartouche | |
5814 | @noindent | |
5815 | The default external representation for a type tag is the fully expanded | |
5816 | name of the type in upper case letters. | |
5817 | ||
5818 | @sp 1 | |
5819 | @cartouche | |
5820 | @noindent | |
5821 | @strong{47}. What determines whether a compilation unit is the same in | |
ad42149c | 5822 | two different partitions. See 13.3(76). |
41af791f GB |
5823 | @end cartouche |
5824 | @noindent | |
5825 | A compilation unit is the same in two different partitions if and only | |
5826 | if it derives from the same source file. | |
5827 | ||
5828 | @sp 1 | |
5829 | @cartouche | |
5830 | @noindent | |
ad42149c | 5831 | @strong{48}. Implementation-defined components. See 13.5.1(15). |
41af791f GB |
5832 | @end cartouche |
5833 | @noindent | |
5834 | The only implementation defined component is the tag for a tagged type, | |
5835 | which contains a pointer to the dispatching table. | |
5836 | ||
5837 | @sp 1 | |
5838 | @cartouche | |
5839 | @noindent | |
5840 | @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit | |
ad42149c | 5841 | ordering. See 13.5.3(5). |
41af791f GB |
5842 | @end cartouche |
5843 | @noindent | |
5844 | @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this | |
ad42149c | 5845 | implementation, so no non-default bit ordering is supported. The default |
41af791f GB |
5846 | bit ordering corresponds to the natural endianness of the target architecture. |
5847 | ||
5848 | @sp 1 | |
5849 | @cartouche | |
5850 | @noindent | |
5851 | @strong{50}. The contents of the visible part of package @code{System} | |
ad42149c | 5852 | and its language-defined children. See 13.7(2). |
41af791f GB |
5853 | @end cartouche |
5854 | @noindent | |
5855 | See the definition of these packages in files @file{system.ads} and | |
5856 | @file{s-stoele.ads}. | |
5857 | ||
5858 | @sp 1 | |
5859 | @cartouche | |
5860 | @noindent | |
5861 | @strong{51}. The contents of the visible part of package | |
5862 | @code{System.Machine_Code}, and the meaning of | |
ad42149c | 5863 | @code{code_statements}. See 13.8(7). |
41af791f GB |
5864 | @end cartouche |
5865 | @noindent | |
5866 | See the definition and documentation in file @file{s-maccod.ads}. | |
5867 | ||
5868 | @sp 1 | |
5869 | @cartouche | |
5870 | @noindent | |
ad42149c | 5871 | @strong{52}. The effect of unchecked conversion. See 13.9(11). |
41af791f GB |
5872 | @end cartouche |
5873 | @noindent | |
5874 | Unchecked conversion between types of the same size | |
5875 | and results in an uninterpreted transmission of the bits from one type | |
ad42149c | 5876 | to the other. If the types are of unequal sizes, then in the case of |
41af791f GB |
5877 | discrete types, a shorter source is first zero or sign extended as |
5878 | necessary, and a shorter target is simply truncated on the left. | |
5879 | For all non-discrete types, the source is first copied if necessary | |
5880 | to ensure that the alignment requirements of the target are met, then | |
5881 | a pointer is constructed to the source value, and the result is obtained | |
5882 | by dereferencing this pointer after converting it to be a pointer to the | |
5883 | target type. | |
5884 | ||
5885 | @sp 1 | |
5886 | @cartouche | |
5887 | @noindent | |
5888 | @strong{53}. The manner of choosing a storage pool for an access type | |
ad42149c | 5889 | when @code{Storage_Pool} is not specified for the type. See 13.11(17). |
41af791f GB |
5890 | @end cartouche |
5891 | @noindent | |
5892 | There are 3 different standard pools used by the compiler when | |
5893 | @code{Storage_Pool} is not specified depending whether the type is local | |
5894 | to a subprogram or defined at the library level and whether | |
ad42149c | 5895 | @code{Storage_Size}is specified or not. See documentation in the runtime |
41af791f GB |
5896 | library units @code{System.Pool_Global}, @code{System.Pool_Size} and |
5897 | @code{System.Pool_Local} in files @file{s-poosiz.ads}, | |
5898 | @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the | |
5899 | default pools used. | |
5900 | ||
5901 | @sp 1 | |
5902 | @cartouche | |
5903 | @noindent | |
5904 | @strong{54}. Whether or not the implementation provides user-accessible | |
ad42149c | 5905 | names for the standard pool type(s). See 13.11(17). |
41af791f GB |
5906 | @end cartouche |
5907 | @noindent | |
5908 | ||
5909 | See documentation in the sources of the run time mentioned in paragraph | |
ad42149c | 5910 | @strong{53} . All these pools are accessible by means of @code{with}'ing |
41af791f GB |
5911 | these units. |
5912 | ||
5913 | @sp 1 | |
5914 | @cartouche | |
5915 | @noindent | |
ad42149c | 5916 | @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). |
41af791f GB |
5917 | @end cartouche |
5918 | @noindent | |
5919 | @code{Storage_Size} is measured in storage units, and refers to the | |
5920 | total space available for an access type collection, or to the primary | |
5921 | stack space for a task. | |
5922 | ||
5923 | @sp 1 | |
5924 | @cartouche | |
5925 | @noindent | |
ad42149c | 5926 | @strong{56}. Implementation-defined aspects of storage pools. See |
41af791f GB |
5927 | 13.11(22). |
5928 | @end cartouche | |
5929 | @noindent | |
5930 | See documentation in the sources of the run time mentioned in paragraph | |
5931 | @strong{53} for details on GNAT-defined aspects of storage pools. | |
5932 | ||
5933 | @sp 1 | |
5934 | @cartouche | |
5935 | @noindent | |
5936 | @strong{57}. The set of restrictions allowed in a pragma | |
ad42149c | 5937 | @code{Restrictions}. See 13.12(7). |
41af791f GB |
5938 | @end cartouche |
5939 | @noindent | |
ad42149c FW |
5940 | All RM defined Restriction identifiers are implemented. The following |
5941 | additional restriction identifiers are provided. There are two separate | |
5942 | lists of implementation dependent restriction identifiers. The first | |
41af791f GB |
5943 | set requires consistency throughout a partition (in other words, if the |
5944 | restriction identifier is used for any compilation unit in the partition, | |
5945 | then all compilation units in the partition must obey the restriction. | |
5946 | ||
5947 | @table @code | |
5948 | ||
5949 | @item Boolean_Entry_Barriers | |
5950 | @findex Boolean_Entry_Barriers | |
5951 | This restriction ensures at compile time that barriers in entry declarations | |
5952 | for protected types are restricted to references to simple boolean variables | |
ad42149c FW |
5953 | defined in the private part of the protected type. No other form of entry |
5954 | barriers is permitted. This is one of the restrictions of the Ravenscar | |
5955 | profile for limited tasking (see also pragma @code{Ravenscar}). | |
41af791f GB |
5956 | |
5957 | @item Max_Entry_Queue_Depth => Expr | |
5958 | @findex Max_Entry_Queue_Depth | |
5959 | This restriction is a declaration that any protected entry compiled in | |
5960 | the scope of the restriction has at most the specified number of | |
5961 | tasks waiting on the entry | |
ad42149c FW |
5962 | at any one time, and so no queue is required. This restriction is not |
5963 | checked at compile time. A program execution is erroneous if an attempt | |
41af791f GB |
5964 | is made to queue more than the specified number of tasks on such an entry. |
5965 | ||
5966 | @item No_Calendar | |
5967 | @findex No_Calendar | |
5968 | This restriction ensures at compile time that there is no implicit or | |
5969 | explicit dependence on the package @code{Ada.Calendar}. | |
5970 | ||
5971 | @item No_Dynamic_Interrupts | |
5972 | @findex No_Dynamic_Interrupts | |
5973 | This restriction ensures at compile time that there is no attempt to | |
ad42149c | 5974 | dynamically associate interrupts. Only static association is allowed. |
41af791f GB |
5975 | |
5976 | @item No_Enumeration_Maps | |
5977 | @findex No_Enumeration_Maps | |
5978 | This restriction ensures at compile time that no operations requiring | |
5979 | enumeration maps are used (that is Image and Value attributes applied | |
5980 | to enumeration types). | |
5981 | ||
5982 | @item No_Entry_Calls_In_Elaboration_Code | |
5983 | @findex No_Entry_Calls_In_Elaboration_Code | |
5984 | This restriction ensures at compile time that no task or protected entry | |
ad42149c | 5985 | calls are made during elaboration code. As a result of the use of this |
41af791f GB |
5986 | restriction, the compiler can assume that no code past an accept statement |
5987 | in a task can be executed at elaboration time. | |
5988 | ||
5989 | @item No_Exception_Handlers | |
5990 | @findex No_Exception_Handlers | |
5991 | This restriction ensures at compile time that there are no explicit | |
5992 | exception handlers. | |
5993 | ||
5994 | @item No_Implicit_Conditionals | |
5995 | @findex No_Implicit_Conditionals | |
5996 | This restriction ensures that the generated code does not contain any | |
5997 | implicit conditionals, either by modifying the generated code where possible, | |
5998 | or by rejecting any construct that would otherwise generate an implicit | |
ad42149c | 5999 | conditional. The details and use of this restriction are described in |
41af791f GB |
6000 | more detail in the High Integrity product documentation. |
6001 | ||
6002 | @item No_Implicit_Loops | |
6003 | @findex No_Implicit_Loops | |
6004 | This restriction ensures that the generated code does not contain any | |
6005 | implicit @code{for} loops, either by modifying | |
6006 | the generated code where possible, | |
6007 | or by rejecting any construct that would otherwise generate an implicit | |
ad42149c FW |
6008 | @code{for} loop. The details and use of this restriction are described in |
6009 | more detail in the High Integrity product documentation. | |
41af791f GB |
6010 | |
6011 | @item No_Local_Protected_Objects | |
6012 | @findex No_Local_Protected_Objects | |
6013 | This restriction ensures at compile time that protected objects are | |
6014 | only declared at the library level. | |
6015 | ||
6016 | @item No_Protected_Type_Allocators | |
6017 | @findex No_Protected_Type_Allocators | |
6018 | This restriction ensures at compile time that there are no allocator | |
6019 | expressions that attempt to allocate protected objects. | |
6020 | ||
ad42149c FW |
6021 | @item No_Secondary_Stack |
6022 | @findex No_Secondary_Stack | |
6023 | This restriction ensures at compile time that the generated code does not | |
6024 | contain any reference to the secondary stack. The secondary stack is used | |
6025 | to implement functions returning unconstrained objects (arrays or records) | |
6026 | on some targets. | |
6027 | The details and use of this restriction are described in | |
6028 | more detail in the High Integrity product documentation. | |
6029 | ||
41af791f GB |
6030 | @item No_Select_Statements |
6031 | @findex No_Select_Statements | |
6032 | This restriction ensures at compile time no select statements of any kind | |
6033 | are permitted, that is the keyword @code{select} may not appear. | |
6034 | This is one of the restrictions of the Ravenscar | |
ad42149c | 6035 | profile for limited tasking (see also pragma @code{Ravenscar}). |
41af791f GB |
6036 | |
6037 | @item No_Standard_Storage_Pools | |
6038 | @findex No_Standard_Storage_Pools | |
6039 | This restriction ensures at compile time that no access types | |
ad42149c | 6040 | use the standard default storage pool. Any access type declared must |
41af791f GB |
6041 | have an explicit Storage_Pool attribute defined specifying a |
6042 | user-defined storage pool. | |
6043 | ||
6044 | @item No_Streams | |
6045 | @findex No_Streams | |
6046 | This restriction ensures at compile time that there are no implicit or | |
6047 | explicit dependencies on the package @code{Ada.Streams}. | |
6048 | ||
6049 | @item No_Task_Attributes | |
6050 | @findex No_Task_Attributes | |
6051 | This restriction ensures at compile time that there are no implicit or | |
6052 | explicit dependencies on the package @code{Ada.Task_Attributes}. | |
6053 | ||
6054 | @item No_Task_Termination | |
6055 | @findex No_Task_Termination | |
6056 | This restriction ensures at compile time that no terminate alternatives | |
6057 | appear in any task body. | |
6058 | ||
ad42149c FW |
6059 | @item No_Tasking |
6060 | @findex No_Tasking | |
6061 | This restriction prevents the declaration of tasks or task types throughout | |
6062 | the partition. It is similar in effect to the use of @code{Max_Tasks => 0} | |
6063 | except that violations are caught at compile time and cause an error message | |
6064 | to be output either by the compiler or binder. | |
6065 | ||
41af791f GB |
6066 | @item No_Wide_Characters |
6067 | @findex No_Wide_Characters | |
6068 | This restriction ensures at compile time that no uses of the types | |
6069 | @code{Wide_Character} or @code{Wide_String} | |
6070 | appear, and that no wide character literals | |
6071 | appear in the program (that is literals representing characters not in | |
6072 | type @code{Character}. | |
6073 | ||
6074 | @item Static_Priorities | |
6075 | @findex Static_Priorities | |
6076 | This restriction ensures at compile time that all priority expressions | |
6077 | are static, and that there are no dependencies on the package | |
6078 | @code{Ada.Dynamic_Priorities}. | |
6079 | ||
6080 | @item Static_Storage_Size | |
6081 | @findex Static_Storage_Size | |
6082 | This restriction ensures at compile time that any expression appearing | |
6083 | in a Storage_Size pragma or attribute definition clause is static. | |
6084 | ||
6085 | @end table | |
6086 | ||
6087 | @noindent | |
6088 | The second set of implementation dependent restriction identifiers | |
6089 | does not require partition-wide consistency. | |
6090 | The restriction may be enforced for a single | |
6091 | compilation unit without any effect on any of the | |
6092 | other compilation units in the partition. | |
6093 | ||
6094 | @table @code | |
6095 | ||
6096 | @item No_Elaboration_Code | |
6097 | @findex No_Elaboration_Code | |
6098 | This restriction ensures at compile time that no elaboration code is | |
ad42149c FW |
6099 | generated. Note that this is not the same condition as is enforced |
6100 | by pragma @code{Preelaborate}. There are cases in which pragma @code{Preelaborate} | |
46b58b8c | 6101 | still permits code to be generated (e.g.@: code to initialize a large |
41af791f | 6102 | array to all zeroes), and there are cases of units which do not meet |
ad42149c FW |
6103 | the requirements for pragma @code{Preelaborate}, but for which no elaboration |
6104 | code is generated. Generally, it is the case that preelaborable units | |
41af791f GB |
6105 | will meet the restrictions, with the exception of large aggregates |
6106 | initialized with an others_clause, and exception declarations (which | |
ad42149c | 6107 | generate calls to a run-time registry procedure). Note that this restriction |
41af791f GB |
6108 | is enforced on a unit by unit basis, it need not be obeyed consistently |
6109 | throughout a partition. | |
6110 | ||
6111 | @item No_Entry_Queue | |
6112 | @findex No_Entry_Queue | |
6113 | This restriction is a declaration that any protected entry compiled in | |
6114 | the scope of the restriction has at most one task waiting on the entry | |
ad42149c FW |
6115 | at any one time, and so no queue is required. This restriction is not |
6116 | checked at compile time. A program execution is erroneous if an attempt | |
41af791f GB |
6117 | is made to queue a second task on such an entry. |
6118 | ||
6119 | @item No_Implementation_Attributes | |
6120 | @findex No_Implementation_Attributes | |
6121 | This restriction checks at compile time that no GNAT-defined attributes | |
ad42149c | 6122 | are present. With this restriction, the only attributes that can be used |
41af791f GB |
6123 | are those defined in the Ada 95 Reference Manual. |
6124 | ||
6125 | @item No_Implementation_Pragmas | |
6126 | @findex No_Implementation_Pragmas | |
6127 | This restriction checks at compile time that no GNAT-defined pragmas | |
ad42149c | 6128 | are present. With this restriction, the only pragmas that can be used |
41af791f GB |
6129 | are those defined in the Ada 95 Reference Manual. |
6130 | ||
6131 | @item No_Implementation_Restrictions | |
6132 | @findex No_Implementation_Restrictions | |
6133 | This restriction checks at compile time that no GNAT-defined restriction | |
6134 | identifiers (other than @code{No_Implementation_Restrictions} itself) | |
ad42149c | 6135 | are present. With this restriction, the only other restriction identifiers |
41af791f GB |
6136 | that can be used are those defined in the Ada 95 Reference Manual. |
6137 | ||
6138 | @end table | |
6139 | ||
6140 | @sp 1 | |
6141 | @cartouche | |
6142 | @noindent | |
6143 | @strong{58}. The consequences of violating limitations on | |
ad42149c | 6144 | @code{Restrictions} pragmas. See 13.12(9). |
41af791f GB |
6145 | @end cartouche |
6146 | @noindent | |
6147 | Restrictions that can be checked at compile time result in illegalities | |
ad42149c | 6148 | if violated. Currently there are no other consequences of violating |
41af791f GB |
6149 | restrictions. |
6150 | ||
6151 | @sp 1 | |
6152 | @cartouche | |
6153 | @noindent | |
6154 | @strong{59}. The representation used by the @code{Read} and | |
6155 | @code{Write} attributes of elementary types in terms of stream | |
ad42149c | 6156 | elements. See 13.13.2(9). |
41af791f GB |
6157 | @end cartouche |
6158 | @noindent | |
6159 | The representation is the in-memory representation of the base type of | |
6160 | the type, using the number of bits corresponding to the | |
6161 | @code{@var{type}'Size} value, and the natural ordering of the machine. | |
6162 | ||
6163 | @sp 1 | |
6164 | @cartouche | |
6165 | @noindent | |
6166 | @strong{60}. The names and characteristics of the numeric subtypes | |
ad42149c | 6167 | declared in the visible part of package @code{Standard}. See A.1(3). |
41af791f GB |
6168 | @end cartouche |
6169 | @noindent | |
6170 | See items describing the integer and floating-point types supported. | |
6171 | ||
6172 | @sp 1 | |
6173 | @cartouche | |
6174 | @noindent | |
6175 | @strong{61}. The accuracy actually achieved by the elementary | |
ad42149c | 6176 | functions. See A.5.1(1). |
41af791f GB |
6177 | @end cartouche |
6178 | @noindent | |
6179 | The elementary functions correspond to the functions available in the C | |
ad42149c | 6180 | library. Only fast math mode is implemented. |
41af791f GB |
6181 | |
6182 | @sp 1 | |
6183 | @cartouche | |
6184 | @noindent | |
6185 | @strong{62}. The sign of a zero result from some of the operators or | |
6186 | functions in @code{Numerics.Generic_Elementary_Functions}, when | |
ad42149c | 6187 | @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). |
41af791f GB |
6188 | @end cartouche |
6189 | @noindent | |
6190 | The sign of zeroes follows the requirements of the IEEE 754 standard on | |
6191 | floating-point. | |
6192 | ||
6193 | @sp 1 | |
6194 | @cartouche | |
6195 | @noindent | |
6196 | @strong{63}. The value of | |
ad42149c | 6197 | @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). |
41af791f GB |
6198 | @end cartouche |
6199 | @noindent | |
6200 | Maximum image width is 649, see library file @file{a-numran.ads}. | |
6201 | ||
6202 | @sp 1 | |
6203 | @cartouche | |
6204 | @noindent | |
6205 | @strong{64}. The value of | |
ad42149c | 6206 | @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). |
41af791f GB |
6207 | @end cartouche |
6208 | @noindent | |
6209 | Maximum image width is 80, see library file @file{a-nudira.ads}. | |
6210 | ||
6211 | @sp 1 | |
6212 | @cartouche | |
6213 | @noindent | |
ad42149c | 6214 | @strong{65}. The algorithms for random number generation. See |
41af791f GB |
6215 | A.5.2(32). |
6216 | @end cartouche | |
6217 | @noindent | |
6218 | The algorithm is documented in the source files @file{a-numran.ads} and | |
6219 | @file{a-numran.adb}. | |
6220 | ||
6221 | @sp 1 | |
6222 | @cartouche | |
6223 | @noindent | |
6224 | @strong{66}. The string representation of a random number generator's | |
ad42149c | 6225 | state. See A.5.2(38). |
41af791f GB |
6226 | @end cartouche |
6227 | @noindent | |
6228 | See the documentation contained in the file @file{a-numran.adb}. | |
6229 | ||
6230 | @sp 1 | |
6231 | @cartouche | |
6232 | @noindent | |
6233 | @strong{67}. The minimum time interval between calls to the | |
6234 | time-dependent Reset procedure that are guaranteed to initiate different | |
ad42149c | 6235 | random number sequences. See A.5.2(45). |
41af791f GB |
6236 | @end cartouche |
6237 | @noindent | |
6238 | The minimum period between reset calls to guarantee distinct series of | |
6239 | random numbers is one microsecond. | |
6240 | ||
6241 | @sp 1 | |
6242 | @cartouche | |
6243 | @noindent | |
6244 | @strong{68}. The values of the @code{Model_Mantissa}, | |
6245 | @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, | |
6246 | @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics | |
ad42149c | 6247 | Annex is not supported. See A.5.3(72). |
41af791f GB |
6248 | @end cartouche |
6249 | @noindent | |
6250 | See the source file @file{ttypef.ads} for the values of all numeric | |
6251 | attributes. | |
6252 | ||
6253 | @sp 1 | |
6254 | @cartouche | |
6255 | @noindent | |
6256 | @strong{69}. Any implementation-defined characteristics of the | |
ad42149c | 6257 | input-output packages. See A.7(14). |
41af791f GB |
6258 | @end cartouche |
6259 | @noindent | |
6260 | There are no special implementation defined characteristics for these | |
6261 | packages. | |
6262 | ||
6263 | @sp 1 | |
6264 | @cartouche | |
6265 | @noindent | |
ad42149c | 6266 | @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See |
41af791f GB |
6267 | A.9(10). |
6268 | @end cartouche | |
6269 | @noindent | |
6270 | All type representations are contiguous, and the @code{Buffer_Size} is | |
6271 | the value of @code{@var{type}'Size} rounded up to the next storage unit | |
6272 | boundary. | |
6273 | ||
6274 | @sp 1 | |
6275 | @cartouche | |
6276 | @noindent | |
6277 | @strong{71}. External files for standard input, standard output, and | |
6278 | standard error See A.10(5). | |
6279 | @end cartouche | |
6280 | @noindent | |
6281 | These files are mapped onto the files provided by the C streams | |
ad42149c | 6282 | libraries. See source file @file{i-cstrea.ads} for further details. |
41af791f GB |
6283 | |
6284 | @sp 1 | |
6285 | @cartouche | |
6286 | @noindent | |
ad42149c | 6287 | @strong{72}. The accuracy of the value produced by @code{Put}. See |
41af791f GB |
6288 | A.10.9(36). |
6289 | @end cartouche | |
6290 | @noindent | |
6291 | If more digits are requested in the output than are represented by the | |
6292 | precision of the value, zeroes are output in the corresponding least | |
6293 | significant digit positions. | |
6294 | ||
6295 | @sp 1 | |
6296 | @cartouche | |
6297 | @noindent | |
6298 | @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and | |
ad42149c | 6299 | @code{Command_Name}. See A.15(1). |
41af791f GB |
6300 | @end cartouche |
6301 | @noindent | |
6302 | These are mapped onto the @code{argv} and @code{argc} parameters of the | |
6303 | main program in the natural manner. | |
6304 | ||
6305 | @sp 1 | |
6306 | @cartouche | |
6307 | @noindent | |
ad42149c | 6308 | @strong{74}. Implementation-defined convention names. See B.1(11). |
41af791f GB |
6309 | @end cartouche |
6310 | @noindent | |
6311 | The following convention names are supported | |
6312 | ||
6313 | @table @code | |
6314 | @item Ada | |
6315 | Ada | |
41af791f GB |
6316 | @item Assembler |
6317 | Assembly language | |
ad42149c FW |
6318 | @item Asm |
6319 | Synonym for Assembler | |
6320 | @item Assembly | |
6321 | Synonym for Assembler | |
41af791f GB |
6322 | @item C |
6323 | C | |
6324 | @item C_Pass_By_Copy | |
ad42149c FW |
6325 | Allowed only for record types, like C, but also notes that record |
6326 | is to be passed by copy rather than reference. | |
41af791f GB |
6327 | @item COBOL |
6328 | COBOL | |
6329 | @item CPP | |
6330 | C++ | |
6331 | @item Default | |
6332 | Treated the same as C | |
41af791f GB |
6333 | @item External |
6334 | Treated the same as C | |
6335 | @item Fortran | |
6336 | Fortran | |
6337 | @item Intrinsic | |
6338 | For support of pragma @code{Import} with convention Intrinsic, see | |
6339 | separate section on Intrinsic Subprograms. | |
6340 | @item Stdcall | |
ad42149c | 6341 | Stdcall (used for Windows implementations only). This convention correspond |
41af791f | 6342 | to the WINAPI (previously called Pascal convention) C/C++ convention under |
ad42149c FW |
6343 | Windows. A function with this convention cleans the stack before exit. |
6344 | @item DLL | |
6345 | Synonym for Stdcall | |
6346 | @item Win32 | |
6347 | Synonym for Stdcall | |
41af791f GB |
6348 | @item Stubbed |
6349 | Stubbed is a special convention used to indicate that the body of the | |
ad42149c FW |
6350 | subprogram will be entirely ignored. Any call to the subprogram |
6351 | is converted into a raise of the @code{Program_Error} exception. If a | |
41af791f | 6352 | pragma @code{Import} specifies convention @code{stubbed} then no body need |
ad42149c | 6353 | be present at all. This convention is useful during development for the |
41af791f GB |
6354 | inclusion of subprograms whose body has not yet been written. |
6355 | ||
6356 | @end table | |
6357 | @noindent | |
6358 | In addition, all otherwise unrecognized convention names are also | |
ad42149c FW |
6359 | treated as being synonymous with convention C@. In all implementations |
6360 | except for VMS, use of such other names results in a warning. In VMS | |
41af791f GB |
6361 | implementations, these names are accepted silently. |
6362 | ||
6363 | @sp 1 | |
6364 | @cartouche | |
6365 | @noindent | |
ad42149c | 6366 | @strong{75}. The meaning of link names. See B.1(36). |
41af791f GB |
6367 | @end cartouche |
6368 | @noindent | |
6369 | Link names are the actual names used by the linker. | |
6370 | ||
6371 | @sp 1 | |
6372 | @cartouche | |
6373 | @noindent | |
6374 | @strong{76}. The manner of choosing link names when neither the link | |
ad42149c | 6375 | name nor the address of an imported or exported entity is specified. See |
41af791f GB |
6376 | B.1(36). |
6377 | @end cartouche | |
6378 | @noindent | |
6379 | The default linker name is that which would be assigned by the relevant | |
6380 | external language, interpreting the Ada name as being in all lower case | |
6381 | letters. | |
6382 | ||
6383 | @sp 1 | |
6384 | @cartouche | |
6385 | @noindent | |
ad42149c | 6386 | @strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37). |
41af791f GB |
6387 | @end cartouche |
6388 | @noindent | |
6389 | The string passed to @code{Linker_Options} is presented uninterpreted as | |
6390 | an argument to the link command, unless it contains Ascii.NUL characters. | |
6391 | NUL characters if they appear act as argument separators, so for example | |
6392 | ||
6393 | @smallexample | |
6394 | pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); | |
6395 | @end smallexample | |
6396 | ||
6397 | @noindent | |
ad42149c FW |
6398 | causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the |
6399 | linker. The order of linker options is preserved for a given unit. The final | |
6400 | list of options passed to the linker is in reverse order of the elaboration | |
6401 | order. For example, linker options fo a body always appear before the options | |
6402 | from the corresponding package spec. | |
41af791f GB |
6403 | |
6404 | @sp 1 | |
6405 | @cartouche | |
6406 | @noindent | |
6407 | @strong{78}. The contents of the visible part of package | |
ad42149c | 6408 | @code{Interfaces} and its language-defined descendants. See B.2(1). |
41af791f GB |
6409 | @end cartouche |
6410 | @noindent | |
6411 | See files with prefix @file{i-} in the distributed library. | |
6412 | ||
6413 | @sp 1 | |
6414 | @cartouche | |
6415 | @noindent | |
6416 | @strong{79}. Implementation-defined children of package | |
ad42149c FW |
6417 | @code{Interfaces}. The contents of the visible part of package |
6418 | @code{Interfaces}. See B.2(11). | |
41af791f GB |
6419 | @end cartouche |
6420 | @noindent | |
6421 | See files with prefix @file{i-} in the distributed library. | |
6422 | ||
6423 | @sp 1 | |
6424 | @cartouche | |
6425 | @noindent | |
6426 | @strong{80}. The types @code{Floating}, @code{Long_Floating}, | |
6427 | @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and | |
6428 | @code{COBOL_Character}; and the initialization of the variables | |
6429 | @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in | |
ad42149c | 6430 | @code{Interfaces.COBOL}. See B.4(50). |
41af791f GB |
6431 | @end cartouche |
6432 | @noindent | |
6433 | @table @code | |
6434 | @item Floating | |
6435 | Float | |
6436 | @item Long_Floating | |
6437 | (Floating) Long_Float | |
6438 | @item Binary | |
6439 | Integer | |
6440 | @item Long_Binary | |
6441 | Long_Long_Integer | |
6442 | @item Decimal_Element | |
6443 | Character | |
6444 | @item COBOL_Character | |
6445 | Character | |
6446 | @end table | |
6447 | ||
6448 | For initialization, see the file @file{i-cobol.ads} in the distributed library. | |
6449 | ||
6450 | @sp 1 | |
6451 | @cartouche | |
6452 | @noindent | |
ad42149c | 6453 | @strong{81}. Support for access to machine instructions. See C.1(1). |
41af791f GB |
6454 | @end cartouche |
6455 | @noindent | |
6456 | See documentation in file @file{s-maccod.ads} in the distributed library. | |
6457 | ||
6458 | @sp 1 | |
6459 | @cartouche | |
6460 | @noindent | |
6461 | @strong{82}. Implementation-defined aspects of access to machine | |
ad42149c | 6462 | operations. See C.1(9). |
41af791f GB |
6463 | @end cartouche |
6464 | @noindent | |
6465 | See documentation in file @file{s-maccod.ads} in the distributed library. | |
6466 | ||
6467 | @sp 1 | |
6468 | @cartouche | |
6469 | @noindent | |
ad42149c | 6470 | @strong{83}. Implementation-defined aspects of interrupts. See C.3(2). |
41af791f GB |
6471 | @end cartouche |
6472 | @noindent | |
ad42149c | 6473 | Interrupts are mapped to signals or conditions as appropriate. See |
41af791f GB |
6474 | definition of unit |
6475 | @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details | |
6476 | on the interrupts supported on a particular target. | |
6477 | ||
6478 | @sp 1 | |
6479 | @cartouche | |
6480 | @noindent | |
ad42149c | 6481 | @strong{84}. Implementation-defined aspects of pre-elaboration. See |
41af791f GB |
6482 | C.4(13). |
6483 | @end cartouche | |
6484 | @noindent | |
6485 | GNAT does not permit a partition to be restarted without reloading, | |
6486 | except under control of the debugger. | |
6487 | ||
6488 | @sp 1 | |
6489 | @cartouche | |
6490 | @noindent | |
ad42149c | 6491 | @strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7). |
41af791f GB |
6492 | @end cartouche |
6493 | @noindent | |
6494 | Pragma @code{Discard_Names} causes names of enumeration literals to | |
ad42149c | 6495 | be suppressed. In the presence of this pragma, the Image attribute |
41af791f GB |
6496 | provides the image of the Pos of the literal, and Value accepts |
6497 | Pos values. | |
6498 | ||
6499 | @sp 1 | |
6500 | @cartouche | |
6501 | @noindent | |
6502 | @strong{86}. The result of the @code{Task_Identification.Image} | |
ad42149c | 6503 | attribute. See C.7.1(7). |
41af791f GB |
6504 | @end cartouche |
6505 | @noindent | |
6506 | The result of this attribute is an 8-digit hexadecimal string | |
6507 | representing the virtual address of the task control block. | |
6508 | ||
6509 | @sp 1 | |
6510 | @cartouche | |
6511 | @noindent | |
6512 | @strong{87}. The value of @code{Current_Task} when in a protected entry | |
ad42149c | 6513 | or interrupt handler. See C.7.1(17). |
41af791f GB |
6514 | @end cartouche |
6515 | @noindent | |
6516 | Protected entries or interrupt handlers can be executed by any | |
6517 | convenient thread, so the value of @code{Current_Task} is undefined. | |
6518 | ||
6519 | @sp 1 | |
6520 | @cartouche | |
6521 | @noindent | |
6522 | @strong{88}. The effect of calling @code{Current_Task} from an entry | |
ad42149c | 6523 | body or interrupt handler. See C.7.1(19). |
41af791f GB |
6524 | @end cartouche |
6525 | @noindent | |
6526 | The effect of calling @code{Current_Task} from an entry body or | |
6527 | interrupt handler is to return the identification of the task currently | |
6528 | executing the code. | |
6529 | ||
6530 | @sp 1 | |
6531 | @cartouche | |
6532 | @noindent | |
6533 | @strong{89}. Implementation-defined aspects of | |
ad42149c | 6534 | @code{Task_Attributes}. See C.7.2(19). |
41af791f GB |
6535 | @end cartouche |
6536 | @noindent | |
6537 | There are no implementation-defined aspects of @code{Task_Attributes}. | |
6538 | ||
6539 | @sp 1 | |
6540 | @cartouche | |
6541 | @noindent | |
ad42149c | 6542 | @strong{90}. Values of all @code{Metrics}. See D(2). |
41af791f GB |
6543 | @end cartouche |
6544 | @noindent | |
6545 | The metrics information for GNAT depends on the performance of the | |
ad42149c | 6546 | underlying operating system. The sources of the run-time for tasking |
41af791f GB |
6547 | implementation, together with the output from @code{-gnatG} can be |
6548 | used to determine the exact sequence of operating systems calls made | |
ad42149c | 6549 | to implement various tasking constructs. Together with appropriate |
41af791f GB |
6550 | information on the performance of the underlying operating system, |
6551 | on the exact target in use, this information can be used to determine | |
6552 | the required metrics. | |
6553 | ||
6554 | @sp 1 | |
6555 | @cartouche | |
6556 | @noindent | |
6557 | @strong{91}. The declarations of @code{Any_Priority} and | |
ad42149c | 6558 | @code{Priority}. See D.1(11). |
41af791f GB |
6559 | @end cartouche |
6560 | @noindent | |
6561 | See declarations in file @file{system.ads}. | |
6562 | ||
6563 | @sp 1 | |
6564 | @cartouche | |
6565 | @noindent | |
ad42149c | 6566 | @strong{92}. Implementation-defined execution resources. See D.1(15). |
41af791f GB |
6567 | @end cartouche |
6568 | @noindent | |
6569 | There are no implementation-defined execution resources. | |
6570 | ||
6571 | @sp 1 | |
6572 | @cartouche | |
6573 | @noindent | |
6574 | @strong{93}. Whether, on a multiprocessor, a task that is waiting for | |
ad42149c | 6575 | access to a protected object keeps its processor busy. See D.2.1(3). |
41af791f GB |
6576 | @end cartouche |
6577 | @noindent | |
6578 | On a multi-processor, a task that is waiting for access to a protected | |
6579 | object does not keep its processor busy. | |
6580 | ||
6581 | @sp 1 | |
6582 | @cartouche | |
6583 | @noindent | |
6584 | @strong{94}. The affect of implementation defined execution resources | |
ad42149c | 6585 | on task dispatching. See D.2.1(9). |
41af791f GB |
6586 | @end cartouche |
6587 | @noindent | |
6588 | @c SGI info | |
6589 | @ignore | |
6590 | Tasks map to IRIX threads, and the dispatching policy is as defined by | |
6591 | the IRIX implementation of threads. | |
6592 | @end ignore | |
ad42149c | 6593 | Tasks map to threads in the threads package used by GNAT@. Where possible |
41af791f GB |
6594 | and appropriate, these threads correspond to native threads of the |
6595 | underlying operating system. | |
6596 | ||
6597 | @sp 1 | |
6598 | @cartouche | |
6599 | @noindent | |
6600 | @strong{95}. Implementation-defined @code{policy_identifiers} allowed | |
ad42149c | 6601 | in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). |
41af791f GB |
6602 | @end cartouche |
6603 | @noindent | |
6604 | There are no implementation-defined policy-identifiers allowed in this | |
6605 | pragma. | |
6606 | ||
6607 | @sp 1 | |
6608 | @cartouche | |
6609 | @noindent | |
ad42149c | 6610 | @strong{96}. Implementation-defined aspects of priority inversion. See |
41af791f GB |
6611 | D.2.2(16). |
6612 | @end cartouche | |
6613 | @noindent | |
6614 | Execution of a task cannot be preempted by the implementation processing | |
6615 | of delay expirations for lower priority tasks. | |
6616 | ||
6617 | @sp 1 | |
6618 | @cartouche | |
6619 | @noindent | |
ad42149c | 6620 | @strong{97}. Implementation defined task dispatching. See D.2.2(18). |
41af791f GB |
6621 | @end cartouche |
6622 | @noindent | |
6623 | @c SGI info: | |
6624 | @ignore | |
6625 | Tasks map to IRIX threads, and the dispatching policy is as defied by | |
6626 | the IRIX implementation of threads. | |
6627 | @end ignore | |
6628 | The policy is the same as that of the underlying threads implementation. | |
6629 | ||
6630 | @sp 1 | |
6631 | @cartouche | |
6632 | @noindent | |
6633 | @strong{98}. Implementation-defined @code{policy_identifiers} allowed | |
ad42149c | 6634 | in a pragma @code{Locking_Policy}. See D.3(4). |
41af791f GB |
6635 | @end cartouche |
6636 | @noindent | |
6637 | The only implementation defined policy permitted in GNAT is | |
ad42149c | 6638 | @code{Inheritance_Locking}. On targets that support this policy, locking |
46b58b8c | 6639 | is implemented by inheritance, i.e.@: the task owning the lock operates |
41af791f GB |
6640 | at a priority equal to the highest priority of any task currently |
6641 | requesting the lock. | |
6642 | ||
6643 | @sp 1 | |
6644 | @cartouche | |
6645 | @noindent | |
ad42149c | 6646 | @strong{99}. Default ceiling priorities. See D.3(10). |
41af791f GB |
6647 | @end cartouche |
6648 | @noindent | |
6649 | The ceiling priority of protected objects of the type | |
6650 | @code{System.Interrupt_Priority'Last} as described in the Ada 95 | |
6651 | Reference Manual D.3(10), | |
6652 | ||
6653 | @sp 1 | |
6654 | @cartouche | |
6655 | @noindent | |
6656 | @strong{100}. The ceiling of any protected object used internally by | |
ad42149c | 6657 | the implementation. See D.3(16). |
41af791f GB |
6658 | @end cartouche |
6659 | @noindent | |
6660 | The ceiling priority of internal protected objects is | |
6661 | @code{System.Priority'Last}. | |
6662 | ||
6663 | @sp 1 | |
6664 | @cartouche | |
6665 | @noindent | |
ad42149c | 6666 | @strong{101}. Implementation-defined queuing policies. See D.4(1). |
41af791f GB |
6667 | @end cartouche |
6668 | @noindent | |
6669 | There are no implementation-defined queueing policies. | |
6670 | ||
6671 | @sp 1 | |
6672 | @cartouche | |
6673 | @noindent | |
6674 | @strong{102}. On a multiprocessor, any conditions that cause the | |
6675 | completion of an aborted construct to be delayed later than what is | |
ad42149c | 6676 | specified for a single processor. See D.6(3). |
41af791f GB |
6677 | @end cartouche |
6678 | @noindent | |
6679 | The semantics for abort on a multi-processor is the same as on a single | |
6680 | processor, there are no further delays. | |
6681 | ||
6682 | @sp 1 | |
6683 | @cartouche | |
6684 | @noindent | |
6685 | @strong{103}. Any operations that implicitly require heap storage | |
ad42149c | 6686 | allocation. See D.7(8). |
41af791f GB |
6687 | @end cartouche |
6688 | @noindent | |
6689 | The only operation that implicitly requires heap storage allocation is | |
6690 | task creation. | |
6691 | ||
6692 | @sp 1 | |
6693 | @cartouche | |
6694 | @noindent | |
6695 | @strong{104}. Implementation-defined aspects of pragma | |
ad42149c | 6696 | @code{Restrictions}. See D.7(20). |
41af791f GB |
6697 | @end cartouche |
6698 | @noindent | |
6699 | There are no such implementation-defined aspects. | |
6700 | ||
6701 | @sp 1 | |
6702 | @cartouche | |
6703 | @noindent | |
6704 | @strong{105}. Implementation-defined aspects of package | |
ad42149c | 6705 | @code{Real_Time}. See D.8(17). |
41af791f GB |
6706 | @end cartouche |
6707 | @noindent | |
6708 | There are no implementation defined aspects of package @code{Real_Time}. | |
6709 | ||
6710 | @sp 1 | |
6711 | @cartouche | |
6712 | @noindent | |
6713 | @strong{106}. Implementation-defined aspects of | |
ad42149c | 6714 | @code{delay_statements}. See D.9(8). |
41af791f GB |
6715 | @end cartouche |
6716 | @noindent | |
6717 | Any difference greater than one microsecond will cause the task to be | |
6718 | delayed (see D.9(7)). | |
6719 | ||
6720 | @sp 1 | |
6721 | @cartouche | |
6722 | @noindent | |
6723 | @strong{107}. The upper bound on the duration of interrupt blocking | |
ad42149c | 6724 | caused by the implementation. See D.12(5). |
41af791f GB |
6725 | @end cartouche |
6726 | @noindent | |
ad42149c | 6727 | The upper bound is determined by the underlying operating system. In |
41af791f GB |
6728 | no cases is it more than 10 milliseconds. |
6729 | ||
6730 | @sp 1 | |
6731 | @cartouche | |
6732 | @noindent | |
6733 | @strong{108}. The means for creating and executing distributed | |
ad42149c | 6734 | programs. See E(5). |
41af791f GB |
6735 | @end cartouche |
6736 | @noindent | |
6737 | The GLADE package provides a utility GNATDIST for creating and executing | |
ad42149c | 6738 | distributed programs. See the GLADE reference manual for further details. |
41af791f GB |
6739 | |
6740 | @sp 1 | |
6741 | @cartouche | |
6742 | @noindent | |
6743 | @strong{109}. Any events that can result in a partition becoming | |
ad42149c | 6744 | inaccessible. See E.1(7). |
41af791f GB |
6745 | @end cartouche |
6746 | @noindent | |
6747 | See the GLADE reference manual for full details on such events. | |
6748 | ||
6749 | @sp 1 | |
6750 | @cartouche | |
6751 | @noindent | |
6752 | @strong{110}. The scheduling policies, treatment of priorities, and | |
ad42149c | 6753 | management of shared resources between partitions in certain cases. See |
41af791f GB |
6754 | E.1(11). |
6755 | @end cartouche | |
6756 | @noindent | |
6757 | See the GLADE reference manual for full details on these aspects of | |
6758 | multi-partition execution. | |
6759 | ||
6760 | @sp 1 | |
6761 | @cartouche | |
6762 | @noindent | |
6763 | @strong{111}. Events that cause the version of a compilation unit to | |
ad42149c | 6764 | change. See E.3(5). |
41af791f GB |
6765 | @end cartouche |
6766 | @noindent | |
6767 | Editing the source file of a compilation unit, or the source files of | |
6768 | any units on which it is dependent in a significant way cause the version | |
ad42149c | 6769 | to change. No other actions cause the version number to change. All changes |
41af791f GB |
6770 | are significant except those which affect only layout, capitalization or |
6771 | comments. | |
6772 | ||
6773 | @sp 1 | |
6774 | @cartouche | |
6775 | @noindent | |
6776 | @strong{112}. Whether the execution of the remote subprogram is | |
ad42149c | 6777 | immediately aborted as a result of cancellation. See E.4(13). |
41af791f GB |
6778 | @end cartouche |
6779 | @noindent | |
6780 | See the GLADE reference manual for details on the effect of abort in | |
6781 | a distributed application. | |
6782 | ||
6783 | @sp 1 | |
6784 | @cartouche | |
6785 | @noindent | |
ad42149c | 6786 | @strong{113}. Implementation-defined aspects of the PCS@. See E.5(25). |
41af791f GB |
6787 | @end cartouche |
6788 | @noindent | |
6789 | See the GLADE reference manual for a full description of all implementation | |
46b58b8c | 6790 | defined aspects of the PCS@. |
41af791f GB |
6791 | |
6792 | @sp 1 | |
6793 | @cartouche | |
6794 | @noindent | |
ad42149c | 6795 | @strong{114}. Implementation-defined interfaces in the PCS@. See |
41af791f GB |
6796 | E.5(26). |
6797 | @end cartouche | |
6798 | @noindent | |
6799 | See the GLADE reference manual for a full description of all | |
6800 | implementation defined interfaces. | |
6801 | ||
6802 | @sp 1 | |
6803 | @cartouche | |
6804 | @noindent | |
6805 | @strong{115}. The values of named numbers in the package | |
ad42149c | 6806 | @code{Decimal}. See F.2(7). |
41af791f GB |
6807 | @end cartouche |
6808 | @noindent | |
6809 | @table @code | |
6810 | @item Max_Scale | |
6811 | +18 | |
6812 | @item Min_Scale | |
6813 | -18 | |
6814 | @item Min_Delta | |
6815 | 1.0E-18 | |
6816 | @item Max_Delta | |
6817 | 1.0E+18 | |
6818 | @item Max_Decimal_Digits | |
6819 | 18 | |
6820 | @end table | |
6821 | ||
6822 | @sp 1 | |
6823 | @cartouche | |
6824 | @noindent | |
6825 | @strong{116}. The value of @code{Max_Picture_Length} in the package | |
ad42149c | 6826 | @code{Text_IO.Editing}. See F.3.3(16). |
41af791f GB |
6827 | @end cartouche |
6828 | @noindent | |
6829 | 64 | |
6830 | ||
6831 | @sp 1 | |
6832 | @cartouche | |
6833 | @noindent | |
6834 | @strong{117}. The value of @code{Max_Picture_Length} in the package | |
ad42149c | 6835 | @code{Wide_Text_IO.Editing}. See F.3.4(5). |
41af791f GB |
6836 | @end cartouche |
6837 | @noindent | |
6838 | 64 | |
6839 | ||
6840 | @sp 1 | |
6841 | @cartouche | |
6842 | @noindent | |
6843 | @strong{118}. The accuracy actually achieved by the complex elementary | |
ad42149c | 6844 | functions and by other complex arithmetic operations. See G.1(1). |
41af791f GB |
6845 | @end cartouche |
6846 | @noindent | |
6847 | Standard library functions are used for the complex arithmetic | |
ad42149c | 6848 | operations. Only fast math mode is currently supported. |
41af791f GB |
6849 | |
6850 | @sp 1 | |
6851 | @cartouche | |
6852 | @noindent | |
6853 | @strong{119}. The sign of a zero result (or a component thereof) from | |
6854 | any operator or function in @code{Numerics.Generic_Complex_Types}, when | |
ad42149c | 6855 | @code{Real'Signed_Zeros} is True. See G.1.1(53). |
41af791f GB |
6856 | @end cartouche |
6857 | @noindent | |
6858 | The signs of zero values are as recommended by the relevant | |
6859 | implementation advice. | |
6860 | ||
6861 | @sp 1 | |
6862 | @cartouche | |
6863 | @noindent | |
6864 | @strong{120}. The sign of a zero result (or a component thereof) from | |
6865 | any operator or function in | |
6866 | @code{Numerics.Generic_Complex_Elementary_Functions}, when | |
ad42149c | 6867 | @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). |
41af791f GB |
6868 | @end cartouche |
6869 | @noindent | |
6870 | The signs of zero values are as recommended by the relevant | |
6871 | implementation advice. | |
6872 | ||
6873 | @sp 1 | |
6874 | @cartouche | |
6875 | @noindent | |
6876 | @strong{121}. Whether the strict mode or the relaxed mode is the | |
ad42149c | 6877 | default. See G.2(2). |
41af791f GB |
6878 | @end cartouche |
6879 | @noindent | |
ad42149c | 6880 | The strict mode is the default. There is no separate relaxed mode. GNAT |
41af791f GB |
6881 | provides a highly efficient implementation of strict mode. |
6882 | ||
6883 | @sp 1 | |
6884 | @cartouche | |
6885 | @noindent | |
6886 | @strong{122}. The result interval in certain cases of fixed-to-float | |
ad42149c | 6887 | conversion. See G.2.1(10). |
41af791f GB |
6888 | @end cartouche |
6889 | @noindent | |
6890 | For cases where the result interval is implementation dependent, the | |
6891 | accuracy is that provided by performing all operations in 64-bit IEEE | |
6892 | floating-point format. | |
6893 | ||
6894 | @sp 1 | |
6895 | @cartouche | |
6896 | @noindent | |
6897 | @strong{123}. The result of a floating point arithmetic operation in | |
6898 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
ad42149c | 6899 | result type is @code{False}. See G.2.1(13). |
41af791f GB |
6900 | @end cartouche |
6901 | @noindent | |
6902 | Infinite and Nan values are produced as dictated by the IEEE | |
6903 | floating-point standard. | |
6904 | ||
6905 | @sp 1 | |
6906 | @cartouche | |
6907 | @noindent | |
6908 | @strong{124}. The result interval for division (or exponentiation by a | |
6909 | negative exponent), when the floating point hardware implements division | |
ad42149c | 6910 | as multiplication by a reciprocal. See G.2.1(16). |
41af791f GB |
6911 | @end cartouche |
6912 | @noindent | |
6913 | Not relevant, division is IEEE exact. | |
6914 | ||
6915 | @sp 1 | |
6916 | @cartouche | |
6917 | @noindent | |
6918 | @strong{125}. The definition of close result set, which determines the | |
ad42149c | 6919 | accuracy of certain fixed point multiplications and divisions. See |
41af791f GB |
6920 | G.2.3(5). |
6921 | @end cartouche | |
6922 | @noindent | |
6923 | Operations in the close result set are performed using IEEE long format | |
ad42149c | 6924 | floating-point arithmetic. The input operands are converted to |
41af791f GB |
6925 | floating-point, the operation is done in floating-point, and the result |
6926 | is converted to the target type. | |
6927 | ||
6928 | @sp 1 | |
6929 | @cartouche | |
6930 | @noindent | |
6931 | @strong{126}. Conditions on a @code{universal_real} operand of a fixed | |
6932 | point multiplication or division for which the result shall be in the | |
ad42149c | 6933 | perfect result set. See G.2.3(22). |
41af791f GB |
6934 | @end cartouche |
6935 | @noindent | |
6936 | The result is only defined to be in the perfect result set if the result | |
6937 | can be computed by a single scaling operation involving a scale factor | |
6938 | representable in 64-bits. | |
6939 | ||
6940 | @sp 1 | |
6941 | @cartouche | |
6942 | @noindent | |
6943 | @strong{127}. The result of a fixed point arithmetic operation in | |
6944 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
ad42149c | 6945 | result type is @code{False}. See G.2.3(27). |
41af791f GB |
6946 | @end cartouche |
6947 | @noindent | |
6948 | Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point | |
6949 | types. | |
6950 | ||
6951 | @sp 1 | |
6952 | @cartouche | |
6953 | @noindent | |
6954 | @strong{128}. The result of an elementary function reference in | |
6955 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
ad42149c | 6956 | result type is @code{False}. See G.2.4(4). |
41af791f GB |
6957 | @end cartouche |
6958 | @noindent | |
6959 | IEEE infinite and Nan values are produced as appropriate. | |
6960 | ||
6961 | @sp 1 | |
6962 | @cartouche | |
6963 | @noindent | |
6964 | @strong{129}. The value of the angle threshold, within which certain | |
6965 | elementary functions, complex arithmetic operations, and complex | |
6966 | elementary functions yield results conforming to a maximum relative | |
ad42149c | 6967 | error bound. See G.2.4(10). |
41af791f GB |
6968 | @end cartouche |
6969 | @noindent | |
6970 | Information on this subject is not yet available. | |
6971 | ||
6972 | @sp 1 | |
6973 | @cartouche | |
6974 | @noindent | |
6975 | @strong{130}. The accuracy of certain elementary functions for | |
ad42149c | 6976 | parameters beyond the angle threshold. See G.2.4(10). |
41af791f GB |
6977 | @end cartouche |
6978 | @noindent | |
6979 | Information on this subject is not yet available. | |
6980 | ||
6981 | @sp 1 | |
6982 | @cartouche | |
6983 | @noindent | |
6984 | @strong{131}. The result of a complex arithmetic operation or complex | |
6985 | elementary function reference in overflow situations, when the | |
6986 | @code{Machine_Overflows} attribute of the corresponding real type is | |
ad42149c | 6987 | @code{False}. See G.2.6(5). |
41af791f GB |
6988 | @end cartouche |
6989 | @noindent | |
6990 | IEEE infinite and Nan values are produced as appropriate. | |
6991 | ||
6992 | @sp 1 | |
6993 | @cartouche | |
6994 | @noindent | |
6995 | @strong{132}. The accuracy of certain complex arithmetic operations and | |
6996 | certain complex elementary functions for parameters (or components | |
ad42149c | 6997 | thereof) beyond the angle threshold. See G.2.6(8). |
41af791f GB |
6998 | @end cartouche |
6999 | @noindent | |
7000 | Information on those subjects is not yet available. | |
7001 | ||
7002 | @sp 1 | |
7003 | @cartouche | |
7004 | @noindent | |
7005 | @strong{133}. Information regarding bounded errors and erroneous | |
ad42149c | 7006 | execution. See H.2(1). |
41af791f GB |
7007 | @end cartouche |
7008 | @noindent | |
7009 | Information on this subject is not yet available. | |
7010 | ||
7011 | @sp 1 | |
7012 | @cartouche | |
7013 | @noindent | |
7014 | @strong{134}. Implementation-defined aspects of pragma | |
ad42149c | 7015 | @code{Inspection_Point}. See H.3.2(8). |
41af791f GB |
7016 | @end cartouche |
7017 | @noindent | |
7018 | Pragma @code{Inspection_Point} ensures that the variable is live and can | |
7019 | be examined by the debugger at the inspection point. | |
7020 | ||
7021 | @sp 1 | |
7022 | @cartouche | |
7023 | @noindent | |
7024 | @strong{135}. Implementation-defined aspects of pragma | |
ad42149c | 7025 | @code{Restrictions}. See H.4(25). |
41af791f GB |
7026 | @end cartouche |
7027 | @noindent | |
ad42149c | 7028 | There are no implementation-defined aspects of pragma @code{Restrictions}. The |
41af791f | 7029 | use of pragma @code{Restrictions [No_Exceptions]} has no effect on the |
ad42149c | 7030 | generated code. Checks must suppressed by use of pragma @code{Suppress}. |
41af791f GB |
7031 | |
7032 | @sp 1 | |
7033 | @cartouche | |
7034 | @noindent | |
ad42149c | 7035 | @strong{136}. Any restrictions on pragma @code{Restrictions}. See |
41af791f GB |
7036 | H.4(27). |
7037 | @end cartouche | |
7038 | @noindent | |
7039 | There are no restrictions on pragma @code{Restrictions}. | |
7040 | ||
7041 | @node Intrinsic Subprograms | |
7042 | @chapter Intrinsic Subprograms | |
7043 | @cindex Intrinsic Subprograms | |
7044 | ||
7045 | @menu | |
7046 | * Intrinsic Operators:: | |
7047 | * Enclosing_Entity:: | |
7048 | * Exception_Information:: | |
7049 | * Exception_Message:: | |
7050 | * Exception_Name:: | |
7051 | * File:: | |
7052 | * Line:: | |
7053 | * Rotate_Left:: | |
7054 | * Rotate_Right:: | |
7055 | * Shift_Left:: | |
7056 | * Shift_Right:: | |
7057 | * Shift_Right_Arithmetic:: | |
7058 | * Source_Location:: | |
7059 | @end menu | |
7060 | ||
7061 | GNAT allows a user application program to write the declaration: | |
7062 | ||
7063 | @smallexample | |
7064 | pragma Import (Intrinsic, name); | |
7065 | @end smallexample | |
7066 | ||
7067 | @noindent | |
7068 | providing that the name corresponds to one of the implemented intrinsic | |
7069 | subprograms in GNAT, and that the parameter profile of the referenced | |
ad42149c | 7070 | subprogram meets the requirements. This chapter describes the set of |
41af791f GB |
7071 | implemented intrinsic subprograms, and the requirements on parameter profiles. |
7072 | Note that no body is supplied; as with other uses of pragma Import, the | |
ad42149c | 7073 | body is supplied elsewhere (in this case by the compiler itself). Note |
41af791f GB |
7074 | that any use of this feature is potentially non-portable, since the |
7075 | Ada standard does not require Ada compilers to implement this feature. | |
7076 | ||
7077 | @node Intrinsic Operators | |
7078 | @section Intrinsic Operators | |
7079 | @cindex Intrinsic operator | |
7080 | ||
7081 | @noindent | |
ad42149c FW |
7082 | All the predefined numeric operators in package Standard |
7083 | in @code{pragma Import (Intrinsic,..)} | |
7084 | declarations. In the binary operator case, the operands must have the same | |
7085 | size. The operand or operands must also be appropriate for | |
7086 | the operator. For example, for addition, the operands must | |
7087 | both be floating-point or both be fixed-point, and the | |
7088 | right operand for @code{"**"} must have a root type of | |
7089 | @code{Standard.Integer'Base}. | |
7090 | You can use an intrinsic operator declaration as in the following example: | |
41af791f GB |
7091 | |
7092 | @smallexample | |
7093 | type Int1 is new Integer; | |
7094 | type Int2 is new Integer; | |
7095 | ||
7096 | function "+" (X1 : Int1; X2 : Int2) return Int1; | |
7097 | function "+" (X1 : Int1; X2 : Int2) return Int2; | |
7098 | pragma Import (Intrinsic, "+"); | |
7099 | @end smallexample | |
7100 | ||
7101 | @noindent | |
ad42149c FW |
7102 | This declaration would permit ``mixed mode'' arithmetic on items |
7103 | of the differing types @code{Int1} and @code{Int2}. | |
7104 | It is also possible to specify such operators for private types, if the | |
7105 | full views are appropriate arithmetic types. | |
41af791f GB |
7106 | |
7107 | @node Enclosing_Entity | |
7108 | @section Enclosing_Entity | |
7109 | @cindex Enclosing_Entity | |
7110 | @noindent | |
7111 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7112 | library routine @code{GNAT.Source_Info}. The only useful use of the |
41af791f GB |
7113 | intrinsic import in this case is the one in this unit, so an |
7114 | application program should simply call the function | |
7115 | @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of | |
7116 | the current subprogram, package, task, entry, or protected subprogram. | |
7117 | ||
7118 | @node Exception_Information | |
7119 | @section Exception_Information | |
7120 | @cindex Exception_Information' | |
7121 | @noindent | |
7122 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7123 | library routine @code{GNAT.Current_Exception}. The only useful |
41af791f GB |
7124 | use of the intrinsic import in this case is the one in this unit, |
7125 | so an application program should simply call the function | |
7126 | @code{GNAT.Current_Exception.Exception_Information} to obtain | |
7127 | the exception information associated with the current exception. | |
7128 | ||
7129 | @node Exception_Message | |
7130 | @section Exception_Message | |
7131 | @cindex Exception_Message | |
7132 | @noindent | |
7133 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7134 | library routine @code{GNAT.Current_Exception}. The only useful |
41af791f GB |
7135 | use of the intrinsic import in this case is the one in this unit, |
7136 | so an application program should simply call the function | |
7137 | @code{GNAT.Current_Exception.Exception_Message} to obtain | |
7138 | the message associated with the current exception. | |
7139 | ||
7140 | @node Exception_Name | |
7141 | @section Exception_Name | |
7142 | @cindex Exception_Name | |
7143 | @noindent | |
7144 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7145 | library routine @code{GNAT.Current_Exception}. The only useful |
41af791f GB |
7146 | use of the intrinsic import in this case is the one in this unit, |
7147 | so an application program should simply call the function | |
7148 | @code{GNAT.Current_Exception.Exception_Name} to obtain | |
7149 | the name of the current exception. | |
7150 | ||
7151 | @node File | |
7152 | @section File | |
7153 | @cindex File | |
7154 | @noindent | |
7155 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7156 | library routine @code{GNAT.Source_Info}. The only useful use of the |
41af791f GB |
7157 | intrinsic import in this case is the one in this unit, so an |
7158 | application program should simply call the function | |
7159 | @code{GNAT.Source_Info.File} to obtain the name of the current | |
7160 | file. | |
7161 | ||
7162 | @node Line | |
7163 | @section Line | |
7164 | @cindex Line | |
7165 | @noindent | |
7166 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7167 | library routine @code{GNAT.Source_Info}. The only useful use of the |
41af791f GB |
7168 | intrinsic import in this case is the one in this unit, so an |
7169 | application program should simply call the function | |
7170 | @code{GNAT.Source_Info.Line} to obtain the number of the current | |
7171 | source line. | |
7172 | ||
7173 | @node Rotate_Left | |
7174 | @section Rotate_Left | |
7175 | @cindex Rotate_Left | |
7176 | @noindent | |
7177 | In standard Ada 95, the @code{Rotate_Left} function is available only | |
ad42149c | 7178 | for the predefined modular types in package @code{Interfaces}. However, in |
41af791f GB |
7179 | GNAT it is possible to define a Rotate_Left function for a user |
7180 | defined modular type or any signed integer type as in this example: | |
7181 | ||
7182 | @smallexample | |
7183 | function Shift_Left | |
7184 | (Value : My_Modular_Type; | |
7185 | Amount : Natural) | |
7186 | return My_Modular_Type; | |
7187 | @end smallexample | |
7188 | ||
7189 | @noindent | |
7190 | The requirements are that the profile be exactly as in the example | |
ad42149c | 7191 | above. The only modifications allowed are in the formal parameter |
41af791f GB |
7192 | names, and in the type of @code{Value} and the return type, which |
7193 | must be the same, and must be either a signed integer type, or | |
7194 | a modular integer type with a binary modulus, and the size must | |
ad42149c | 7195 | be 8. 16, 32 or 64 bits. |
41af791f GB |
7196 | |
7197 | @node Rotate_Right | |
7198 | @section Rotate_Right | |
7199 | @cindex Rotate_Right | |
7200 | @noindent | |
7201 | A @code{Rotate_Right} function can be defined for any user defined | |
7202 | binary modular integer type, or signed integer type, as described | |
7203 | above for @code{Rotate_Left}. | |
7204 | ||
7205 | @node Shift_Left | |
7206 | @section Shift_Left | |
7207 | @cindex Shift_Left | |
7208 | @noindent | |
7209 | A @code{Shift_Left} function can be defined for any user defined | |
7210 | binary modular integer type, or signed integer type, as described | |
7211 | above for @code{Rotate_Left}. | |
7212 | ||
7213 | @node Shift_Right | |
7214 | @section Shift_Right | |
7215 | @cindex Shift_Right | |
7216 | @noindent | |
7217 | A @code{Shift_Right} function can be defined for any user defined | |
7218 | binary modular integer type, or signed integer type, as described | |
7219 | above for @code{Rotate_Left}. | |
7220 | ||
7221 | @node Shift_Right_Arithmetic | |
7222 | @section Shift_Right_Arithmetic | |
7223 | @cindex Shift_Right_Arithmetic | |
7224 | @noindent | |
7225 | A @code{Shift_Right_Arithmetic} function can be defined for any user | |
7226 | defined binary modular integer type, or signed integer type, as described | |
7227 | above for @code{Rotate_Left}. | |
7228 | ||
7229 | @node Source_Location | |
7230 | @section Source_Location | |
7231 | @cindex Source_Location | |
7232 | @noindent | |
7233 | This intrinsic subprogram is used in the implementation of the | |
ad42149c | 7234 | library routine @code{GNAT.Source_Info}. The only useful use of the |
41af791f GB |
7235 | intrinsic import in this case is the one in this unit, so an |
7236 | application program should simply call the function | |
7237 | @code{GNAT.Source_Info.Source_Location} to obtain the current | |
7238 | source file location. | |
7239 | ||
7240 | @node Representation Clauses and Pragmas | |
7241 | @chapter Representation Clauses and Pragmas | |
7242 | @cindex Representation Clauses | |
7243 | ||
7244 | @menu | |
7245 | * Alignment Clauses:: | |
7246 | * Size Clauses:: | |
7247 | * Storage_Size Clauses:: | |
7248 | * Size of Variant Record Objects:: | |
7249 | * Biased Representation :: | |
7250 | * Value_Size and Object_Size Clauses:: | |
7251 | * Component_Size Clauses:: | |
7252 | * Bit_Order Clauses:: | |
7253 | * Effect of Bit_Order on Byte Ordering:: | |
7254 | * Pragma Pack for Arrays:: | |
7255 | * Pragma Pack for Records:: | |
7256 | * Record Representation Clauses:: | |
7257 | * Enumeration Clauses:: | |
7258 | * Address Clauses:: | |
7259 | * Effect of Convention on Representation:: | |
7260 | * Determining the Representations chosen by GNAT:: | |
7261 | @end menu | |
7262 | ||
7263 | @noindent | |
7264 | @cindex Representation Clause | |
7265 | @cindex Representation Pragma | |
7266 | @cindex Pragma, representation | |
7267 | This section describes the representation clauses accepted by GNAT, and | |
7268 | their effect on the representation of corresponding data objects. | |
7269 | ||
ad42149c | 7270 | GNAT fully implements Annex C (Systems Programming). This means that all |
41af791f GB |
7271 | the implementation advice sections in chapter 13 are fully implemented. |
7272 | However, these sections only require a minimal level of support for | |
ad42149c | 7273 | representation clauses. GNAT provides much more extensive capabilities, |
41af791f GB |
7274 | and this section describes the additional capabilities provided. |
7275 | ||
7276 | @node Alignment Clauses | |
7277 | @section Alignment Clauses | |
7278 | @cindex Alignment Clause | |
7279 | ||
7280 | @noindent | |
7281 | GNAT requires that all alignment clauses specify a power of 2, and all | |
ad42149c | 7282 | default alignments are always a power of 2. The default alignment |
41af791f GB |
7283 | values are as follows: |
7284 | ||
7285 | @itemize @bullet | |
7286 | @item Primitive Types | |
7287 | For primitive types, the alignment is the maximum of the actual size of | |
7288 | objects of the type, and the maximum alignment supported by the target. | |
7289 | For example, for type Long_Float, the object size is 8 bytes, and the | |
7290 | default alignment will be 8 on any target that supports alignments | |
7291 | this large, but on some targets, the maximum alignment may be smaller | |
7292 | than 8, in which case objects of type Long_Float will be maximally | |
7293 | aligned. | |
7294 | ||
7295 | @item Arrays | |
7296 | For arrays, the alignment is equal to the alignment of the component type | |
ad42149c | 7297 | for the normal case where no packing or component size is given. If the |
41af791f GB |
7298 | array is packed, and the packing is effective (see separate section on |
7299 | packed arrays), then the alignment will be one for long packed arrays, | |
ad42149c | 7300 | or arrays whose length is not known at compile time. For short packed |
41af791f | 7301 | arrays, which are handled internally as modular types, the alignment |
46b58b8c | 7302 | will be as described for primitive types, e.g.@: a packed array of length |
41af791f GB |
7303 | 31 bits will have an object size of four bytes, and an alignment of 4. |
7304 | ||
7305 | @item Records | |
7306 | For the normal non-packed case, the alignment of a record is equal to | |
ad42149c FW |
7307 | the maximum alignment of any of its components. For tagged records, this |
7308 | includes the implicit access type used for the tag. If a pragma @code{Pack} is | |
7309 | used and all fields are packable (see separate section on pragma @code{Pack}), | |
41af791f GB |
7310 | then the resulting alignment is 1. |
7311 | ||
ad42149c FW |
7312 | A special case is when the size of the record is given explicitly, or a |
7313 | full record representation clause is given, and the size of the record | |
7314 | is 2, 4, or 8 bytes. In this case, an alignment is chosen to match the | |
7315 | size of the record. For example, if we have: | |
7316 | ||
7317 | @smallexample | |
7318 | type Small is record | |
7319 | A, B : Character; | |
7320 | end record; | |
7321 | @end smallexample | |
7322 | ||
7323 | @noindent | |
7324 | then the default alignment of the record type @code{Small} is 2, not 1. This | |
7325 | leads to more efficient code when the record is treated as a unit, and also | |
7326 | allows the type to specified as @code{Atomic} on architectures requiring | |
7327 | strict alignment. | |
7328 | ||
41af791f GB |
7329 | @end itemize |
7330 | ||
7331 | @noindent | |
7332 | An alignment clause may | |
7333 | always specify a larger alignment than the default value, up to some | |
7334 | maximum value dependent on the target (obtainable by using the | |
ad42149c | 7335 | attribute reference System'Maximum_Alignment). The only case in which |
41af791f GB |
7336 | it is permissible to specify a smaller alignment than the default value |
7337 | is in the case of a record for which a record representation clause is | |
ad42149c | 7338 | given. In this case, packable fields for which a component clause is |
41af791f GB |
7339 | given still result in a default alignment corresponding to the original |
7340 | type, but this may be overridden, since these components in fact only | |
ad42149c | 7341 | require an alignment of one byte. For example, given |
41af791f GB |
7342 | |
7343 | @smallexample | |
7344 | type v is record | |
7345 | a : integer; | |
7346 | end record; | |
7347 | ||
7348 | for v use record | |
7349 | a at 0 range 0 .. 31; | |
7350 | end record; | |
7351 | ||
7352 | for v'alignment use 1; | |
7353 | @end smallexample | |
7354 | ||
7355 | @noindent | |
7356 | @cindex Alignment, default | |
7357 | The default alignment for the type @code{v} is 4, as a result of the | |
7358 | integer field in the record, but since this field is placed with a | |
7359 | component clause, it is permissible, as shown, to override the default | |
7360 | alignment of the record to a smaller value. | |
7361 | ||
7362 | @node Size Clauses | |
7363 | @section Size Clauses | |
7364 | @cindex Size Clause | |
7365 | ||
7366 | @noindent | |
ad42149c | 7367 | The default size of types is as specified in the reference manual. For |
41af791f GB |
7368 | objects, GNAT will generally increase the type size so that the object |
7369 | size is a multiple of storage units, and also a multiple of the | |
ad42149c | 7370 | alignment. For example |
41af791f GB |
7371 | |
7372 | @smallexample | |
7373 | type Smallint is range 1 .. 6; | |
7374 | ||
7375 | type Rec is record | |
7376 | y1 : integer; | |
7377 | y2 : boolean; | |
7378 | end record; | |
7379 | @end smallexample | |
7380 | ||
7381 | @noindent | |
7382 | In this example, @code{Smallint} | |
7383 | has a size of 3, as specified by the RM rules, | |
7384 | but objects of this type will have a size of 8, | |
7385 | since objects by default occupy an integral number | |
ad42149c | 7386 | of storage units. On some targets, notably older |
41af791f GB |
7387 | versions of the Digital Alpha, the size of stand |
7388 | alone objects of this type may be 32, reflecting | |
7389 | the inability of the hardware to do byte load/stores. | |
7390 | ||
7391 | Similarly, the size of type @code{Rec} is 40 bits, but | |
7392 | the alignment is 4, so objects of this type will have | |
7393 | their size increased to 64 bits so that it is a multiple | |
ad42149c | 7394 | of the alignment. The reason for this decision, which is |
41af791f GB |
7395 | in accordance with the specific note in RM 13.3(43): |
7396 | ||
7397 | @smallexample | |
7398 | A Size clause should be supported for an object if the specified | |
7399 | Size is at least as large as its subtype's Size, and corresponds | |
7400 | to a size in storage elements that is a multiple of the object's | |
7401 | Alignment (if the Alignment is nonzero). | |
7402 | @end smallexample | |
7403 | ||
7404 | @noindent | |
7405 | An explicit size clause may be used to override the default size by | |
ad42149c | 7406 | increasing it. For example, if we have: |
41af791f GB |
7407 | |
7408 | @smallexample | |
7409 | type My_Boolean is new Boolean; | |
7410 | for My_Boolean'Size use 32; | |
7411 | @end smallexample | |
7412 | ||
7413 | @noindent | |
ad42149c | 7414 | then objects of this type will always be 32 bits long. In the case of |
41af791f GB |
7415 | discrete types, the size can be increased up to 64 bits, with the effect |
7416 | that the entire specified field is used to hold the value, sign- or | |
ad42149c | 7417 | zero-extended as appropriate. If more than 64 bits is specified, then |
41af791f GB |
7418 | padding space is allocated after the value, and a warning is issued that |
7419 | there are unused bits. | |
7420 | ||
7421 | Similarly the size of records and arrays may be increased, and the effect | |
ad42149c | 7422 | is to add padding bits after the value. This also causes a warning message |
41af791f GB |
7423 | to be generated. |
7424 | ||
ad42149c | 7425 | The largest Size value permitted in GNAT is 2**32@minus{}1. Since this is a |
41af791f | 7426 | Size in bits, this corresponds to an object of size 256 megabytes (minus |
ad42149c | 7427 | one). This limitation is true on all targets. The reason for this |
41af791f GB |
7428 | limitation is that it improves the quality of the code in many cases |
7429 | if it is known that a Size value can be accommodated in an object of | |
7430 | type Integer. | |
7431 | ||
7432 | @node Storage_Size Clauses | |
7433 | @section Storage_Size Clauses | |
7434 | @cindex Storage_Size Clause | |
7435 | ||
7436 | @noindent | |
7437 | For tasks, the @code{Storage_Size} clause specifies the amount of space | |
ad42149c | 7438 | to be allocated for the task stack. This cannot be extended, and if the |
41af791f | 7439 | stack is exhausted, then @code{Storage_Error} will be raised if stack |
ad42149c | 7440 | checking is enabled. If the default size of 20K bytes is insufficient, |
41af791f GB |
7441 | then you need to use a @code{Storage_Size} attribute definition clause, |
7442 | or a @code{Storage_Size} pragma in the task definition to set the | |
ad42149c | 7443 | appropriate required size. A useful technique is to include in every |
41af791f GB |
7444 | task definition a pragma of the form: |
7445 | ||
7446 | @smallexample | |
7447 | pragma Storage_Size (Default_Stack_Size); | |
7448 | @end smallexample | |
7449 | ||
7450 | @noindent | |
7451 | Then Default_Stack_Size can be defined in a global package, and modified | |
ad42149c | 7452 | as required. Any tasks requiring different task stack sizes from the |
41af791f GB |
7453 | default can have an appropriate alternative reference in the pragma. |
7454 | ||
7455 | For access types, the @code{Storage_Size} clause specifies the maximum | |
ad42149c | 7456 | space available for allocation of objects of the type. If this space is |
41af791f GB |
7457 | exceeded then @code{Storage_Error} will be raised by an allocation attempt. |
7458 | In the case where the access type is declared local to a subprogram, the | |
7459 | use of a @code{Storage_Size} clause triggers automatic use of a special | |
7460 | predefined storage pool (@code{System.Pool_Size}) that ensures that all | |
7461 | space for the pool is automatically reclaimed on exit from the scope in | |
7462 | which the type is declared. | |
7463 | ||
7464 | A special case recognized by the compiler is the specification of a | |
ad42149c | 7465 | @code{Storage_Size} of zero for an access type. This means that no |
41af791f GB |
7466 | items can be allocated from the pool, and this is recognized at compile |
7467 | time, and all the overhead normally associated with maintaining a fixed | |
ad42149c | 7468 | size storage pool is eliminated. Consider the following example: |
41af791f GB |
7469 | |
7470 | @smallexample | |
7471 | procedure p is | |
7472 | type R is array (Natural) of Character; | |
7473 | type P is access all R; | |
7474 | for P'Storage_Size use 0; | |
7475 | -- Above access type intended only for interfacing purposes | |
7476 | ||
7477 | y : P; | |
7478 | ||
7479 | procedure g (m : P); | |
7480 | pragma Import (C, g); | |
7481 | ||
ad42149c | 7482 | -- @dots{} |
41af791f GB |
7483 | |
7484 | begin | |
ad42149c | 7485 | -- @dots{} |
41af791f GB |
7486 | y := new R; |
7487 | end; | |
7488 | @end smallexample | |
7489 | ||
7490 | @noindent | |
7491 | As indicated in this example, these dummy storage pools are often useful in | |
ad42149c | 7492 | connection with interfacing where no object will ever be allocated. If you |
41af791f GB |
7493 | compile the above example, you get the warning: |
7494 | ||
7495 | @smallexample | |
7496 | p.adb:16:09: warning: allocation from empty storage pool | |
7497 | p.adb:16:09: warning: Storage_Error will be raised at run time | |
7498 | @end smallexample | |
7499 | ||
7500 | @noindent | |
7501 | Of course in practice, there will not be any explicit allocators in the | |
7502 | case of such an access declaration. | |
7503 | ||
7504 | @node Size of Variant Record Objects | |
7505 | @section Size of Variant Record Objects | |
7506 | @cindex Size, variant record objects | |
7507 | @cindex Variant record objects, size | |
7508 | ||
7509 | @noindent | |
7510 | An issue arises in the case of variant record objects of whether Size gives | |
7511 | information about a particular variant, or the maximum size required | |
ad42149c | 7512 | for any variant. Consider the following program |
41af791f GB |
7513 | |
7514 | @smallexample | |
7515 | with Text_IO; use Text_IO; | |
7516 | procedure q is | |
7517 | type R1 (A : Boolean := False) is record | |
7518 | case A is | |
7519 | when True => X : Character; | |
7520 | when False => null; | |
7521 | end case; | |
7522 | end record; | |
7523 | ||
7524 | V1 : R1 (False); | |
7525 | V2 : R1; | |
7526 | ||
7527 | begin | |
7528 | Put_Line (Integer'Image (V1'Size)); | |
7529 | Put_Line (Integer'Image (V2'Size)); | |
7530 | end q; | |
7531 | @end smallexample | |
7532 | ||
7533 | @noindent | |
7534 | Here we are dealing with a variant record, where the True variant | |
7535 | requires 16 bits, and the False variant requires 8 bits. | |
7536 | In the above example, both V1 and V2 contain the False variant, | |
ad42149c | 7537 | which is only 8 bits long. However, the result of running the |
41af791f GB |
7538 | program is: |
7539 | ||
7540 | @smallexample | |
7541 | 8 | |
7542 | 16 | |
7543 | @end smallexample | |
7544 | ||
7545 | @noindent | |
7546 | The reason for the difference here is that the discriminant value of | |
ad42149c FW |
7547 | V1 is fixed, and will always be False. It is not possible to assign |
7548 | a True variant value to V1, therefore 8 bits is sufficient. On the | |
41af791f GB |
7549 | other hand, in the case of V2, the initial discriminant value is |
7550 | False (from the default), but it is possible to assign a True | |
7551 | variant value to V2, therefore 16 bits must be allocated for V2 | |
7552 | in the general case, even fewer bits may be needed at any particular | |
7553 | point during the program execution. | |
7554 | ||
7555 | As can be seen from the output of this program, the @code{'Size} | |
7556 | attribute applied to such an object in GNAT gives the actual allocated | |
7557 | size of the variable, which is the largest size of any of the variants. | |
7558 | The Ada Reference Manual is not completely clear on what choice should | |
7559 | be made here, but the GNAT behavior seems most consistent with the | |
46b58b8c | 7560 | language in the RM@. |
41af791f GB |
7561 | |
7562 | In some cases, it may be desirable to obtain the size of the current | |
ad42149c | 7563 | variant, rather than the size of the largest variant. This can be |
41af791f GB |
7564 | achieved in GNAT by making use of the fact that in the case of a |
7565 | subprogram parameter, GNAT does indeed return the size of the current | |
7566 | variant (because a subprogram has no way of knowing how much space | |
7567 | is actually allocated for the actual). | |
7568 | ||
7569 | Consider the following modified version of the above program: | |
7570 | ||
7571 | @smallexample | |
7572 | with Text_IO; use Text_IO; | |
7573 | procedure q is | |
7574 | type R1 (A : Boolean := False) is record | |
7575 | case A is | |
7576 | when True => X : Character; | |
7577 | when False => null; | |
7578 | end case; | |
7579 | end record; | |
7580 | ||
7581 | V2 : R1; | |
7582 | ||
7583 | function Size (V : R1) return Integer is | |
7584 | begin | |
7585 | return V'Size; | |
7586 | end Size; | |
7587 | ||
7588 | begin | |
7589 | Put_Line (Integer'Image (V2'Size)); | |
7590 | Put_Line (Integer'IMage (Size (V2))); | |
7591 | V2 := (True, 'x'); | |
7592 | Put_Line (Integer'Image (V2'Size)); | |
7593 | Put_Line (Integer'IMage (Size (V2))); | |
7594 | end q; | |
7595 | @end smallexample | |
7596 | ||
7597 | @noindent | |
7598 | The output from this program is | |
7599 | ||
7600 | @smallexample | |
7601 | 16 | |
7602 | 8 | |
7603 | 16 | |
7604 | 16 | |
7605 | @end smallexample | |
7606 | ||
7607 | @noindent | |
7608 | Here we see that while the @code{'Size} attribute always returns | |
7609 | the maximum size, regardless of the current variant value, the | |
7610 | @code{Size} function does indeed return the size of the current | |
7611 | variant value. | |
7612 | ||
7613 | @node Biased Representation | |
7614 | @section Biased Representation | |
7615 | @cindex Size for biased representation | |
7616 | @cindex Biased representation | |
7617 | ||
7618 | @noindent | |
7619 | In the case of scalars with a range starting at other than zero, it is | |
7620 | possible in some cases to specify a size smaller than the default minimum | |
ad42149c | 7621 | value, and in such cases, GNAT uses an unsigned biased representation, |
41af791f GB |
7622 | in which zero is used to represent the lower bound, and successive values |
7623 | represent successive values of the type. | |
7624 | ||
7625 | For example, suppose we have the declaration: | |
7626 | ||
7627 | @smallexample | |
7628 | type Small is range -7 .. -4; | |
7629 | for Small'Size use 2; | |
7630 | @end smallexample | |
7631 | ||
7632 | @noindent | |
7633 | Although the default size of type @code{Small} is 4, the @code{Size} | |
7634 | clause is accepted by GNAT and results in the following representation | |
7635 | scheme: | |
7636 | ||
7637 | @smallexample | |
7638 | -7 is represented as 2#00# | |
7639 | -6 is represented as 2#01# | |
7640 | -5 is represented as 2#10# | |
7641 | -4 is represented as 2#11# | |
7642 | @end smallexample | |
7643 | ||
7644 | @noindent | |
7645 | Biased representation is only used if the specified @code{Size} clause | |
ad42149c | 7646 | cannot be accepted in any other manner. These reduced sizes that force |
41af791f GB |
7647 | biased representation can be used for all discrete types except for |
7648 | enumeration types for which a representation clause is given. | |
7649 | ||
7650 | @node Value_Size and Object_Size Clauses | |
7651 | @section Value_Size and Object_Size Clauses | |
7652 | @findex Value_Size | |
7653 | @findex Object_Size | |
7654 | @cindex Size, of objects | |
7655 | ||
7656 | @noindent | |
7657 | In Ada 95, the @code{Size} of a discrete type is the minimum number of bits | |
ad42149c | 7658 | required to hold values of the type. Although this interpretation was |
41af791f | 7659 | allowed in Ada 83, it was not required, and this requirement in practice |
ad42149c FW |
7660 | can cause some significant difficulties. For example, in most Ada 83 |
7661 | compilers, @code{Natural'Size} was 32. However, in Ada-95, | |
41af791f | 7662 | @code{Natural'Size} is |
ad42149c FW |
7663 | typically 31. This means that code may change in behavior when moving |
7664 | from Ada 83 to Ada 95. For example, consider: | |
41af791f GB |
7665 | |
7666 | @smallexample | |
7667 | type Rec is record; | |
7668 | A : Natural; | |
7669 | B : Natural; | |
7670 | end record; | |
7671 | ||
7672 | for Rec use record | |
7673 | for A use at 0 range 0 .. Natural'Size - 1; | |
7674 | for B use at 0 range Natural'Size .. 2 * Natural'Size - 1; | |
7675 | end record; | |
7676 | @end smallexample | |
7677 | ||
7678 | @noindent | |
7679 | In the above code, since the typical size of @code{Natural} objects | |
7680 | is 32 bits and @code{Natural'Size} is 31, the above code can cause | |
7681 | unexpected inefficient packing in Ada 95, and in general there are | |
7682 | surprising cases where the fact that the object size can exceed the | |
7683 | size of the type causes surprises. | |
7684 | ||
7685 | To help get around this problem GNAT provides two implementation | |
ad42149c | 7686 | dependent attributes @code{Value_Size} and @code{Object_Size}. When |
41af791f GB |
7687 | applied to a type, these attributes yield the size of the type |
7688 | (corresponding to the RM defined size attribute), and the size of | |
7689 | objects of the type respectively. | |
7690 | ||
7691 | The @code{Object_Size} is used for determining the default size of | |
ad42149c FW |
7692 | objects and components. This size value can be referred to using the |
7693 | @code{Object_Size} attribute. The phrase ``is used'' here means that it is | |
7694 | the basis of the determination of the size. The backend is free to | |
46b58b8c | 7695 | pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone |
41af791f GB |
7696 | character might be stored in 32 bits on a machine with no efficient |
7697 | byte access instructions such as the Alpha. | |
7698 | ||
7699 | The default rules for the value of @code{Object_Size} for fixed-point and | |
7700 | discrete types are as follows: | |
7701 | ||
7702 | @itemize @bullet | |
7703 | @item | |
7704 | The @code{Object_Size} for base subtypes reflect the natural hardware | |
ad42149c FW |
7705 | size in bits (run the utility @code{gnatpsta} to find those values for numeric types). |
7706 | Enumeration types and fixed-point base subtypes have 8, 16, 32 or 64 | |
41af791f GB |
7707 | bits for this size, depending on the range of values to be stored. |
7708 | ||
7709 | @item | |
7710 | The @code{Object_Size} of a subtype is the same as the | |
7711 | @code{Object_Size} of | |
7712 | the type from which it is obtained. | |
7713 | ||
7714 | @item | |
7715 | The @code{Object_Size} of a derived base type is copied from the parent | |
7716 | base type, and the @code{Object_Size} of a derived first subtype is copied | |
7717 | from the parent first subtype. | |
7718 | @end itemize | |
7719 | ||
7720 | @noindent | |
7721 | The @code{Value_Size} attribute | |
7722 | is the number of bits required to store a value | |
ad42149c FW |
7723 | of the type. This size can be referred to using the @code{Value_Size} |
7724 | attribute. This value is used to determine how tightly to pack | |
41af791f GB |
7725 | records or arrays with components of this type, and also affects |
7726 | the semantics of unchecked conversion (unchecked conversions where | |
7727 | the @code{Value_Size} values differ generate a warning, and are potentially | |
7728 | target dependent). | |
7729 | ||
7730 | The default rules for the value of @code{Value_Size} are as follows: | |
7731 | ||
7732 | @itemize @bullet | |
7733 | @item | |
7734 | The @code{Value_Size} for a base subtype is the minimum number of bits | |
7735 | required to store all values of the type (including the sign bit | |
7736 | only if negative values are possible). | |
7737 | ||
7738 | @item | |
7739 | If a subtype statically matches the first subtype of a given type, then it has | |
ad42149c FW |
7740 | by default the same @code{Value_Size} as the first subtype. This is a |
7741 | consequence of RM 13.1(14) (``if two subtypes statically match, | |
7742 | then their subtype-specific aspects are the same''.) | |
41af791f GB |
7743 | |
7744 | @item | |
7745 | All other subtypes have a @code{Value_Size} corresponding to the minimum | |
ad42149c | 7746 | number of bits required to store all values of the subtype. For |
41af791f GB |
7747 | dynamic bounds, it is assumed that the value can range down or up |
7748 | to the corresponding bound of the ancestor | |
7749 | @end itemize | |
7750 | ||
7751 | @noindent | |
7752 | The RM defined attribute @code{Size} corresponds to the | |
7753 | @code{Value_Size} attribute. | |
7754 | ||
ad42149c | 7755 | The @code{Size} attribute may be defined for a first-named subtype. This sets |
41af791f GB |
7756 | the @code{Value_Size} of |
7757 | the first-named subtype to the given value, and the | |
7758 | @code{Object_Size} of this first-named subtype to the given value padded up | |
ad42149c FW |
7759 | to an appropriate boundary. It is a consequence of the default rules |
7760 | above that this @code{Object_Size} will apply to all further subtypes. On the | |
41af791f GB |
7761 | other hand, @code{Value_Size} is affected only for the first subtype, any |
7762 | dynamic subtypes obtained from it directly, and any statically matching | |
ad42149c | 7763 | subtypes. The @code{Value_Size} of any other static subtypes is not affected. |
41af791f GB |
7764 | |
7765 | @code{Value_Size} and | |
7766 | @code{Object_Size} may be explicitly set for any subtype using | |
ad42149c FW |
7767 | an attribute definition clause. Note that the use of these attributes |
7768 | can cause the RM 13.1(14) rule to be violated. If two access types | |
41af791f GB |
7769 | reference aliased objects whose subtypes have differing @code{Object_Size} |
7770 | values as a result of explicit attribute definition clauses, then it | |
7771 | is erroneous to convert from one access subtype to the other. | |
7772 | ||
7773 | At the implementation level, Esize stores the Object_SIze and the | |
7774 | RM_Size field stores the @code{Value_Size} (and hence the value of the | |
7775 | @code{Size} attribute, | |
7776 | which, as noted above, is equivalent to @code{Value_Size}). | |
7777 | ||
7778 | To get a feel for the difference, consider the following examples (note | |
7779 | that in each case the base is short_short_integer with a size of 8): | |
7780 | ||
7781 | @smallexample | |
7782 | Object_Size Value_Size | |
7783 | ||
ad42149c | 7784 | type x1 is range 0 .. 5; 8 3 |
41af791f | 7785 | |
ad42149c | 7786 | type x2 is range 0 .. 5; |
41af791f GB |
7787 | for x2'size use 12; 12 12 |
7788 | ||
7789 | subtype x3 is x2 range 0 .. 3; 12 2 | |
7790 | ||
7791 | subtype x4 is x2'base range 0 .. 10; 8 4 | |
7792 | ||
7793 | subtype x5 is x2 range 0 .. dynamic; 12 (7) | |
7794 | ||
7795 | subtype x6 is x2'base range 0 .. dynamic; 8 (7) | |
7796 | ||
7797 | @end smallexample | |
7798 | ||
7799 | @noindent | |
7800 | Note: the entries marked (7) are not actually specified by the Ada 95 RM, | |
7801 | but it seems in the spirit of the RM rules to allocate the minimum number | |
7802 | of bits known to be large enough to hold the given range of values. | |
7803 | ||
7804 | So far, so good, but GNAT has to obey the RM rules, so the question is | |
7805 | under what conditions must the RM @code{Size} be used. | |
7806 | The following is a list | |
7807 | of the occasions on which the RM @code{Size} must be used: | |
7808 | ||
7809 | @itemize @bullet | |
7810 | @item | |
7811 | Component size for packed arrays or records | |
7812 | ||
7813 | @item | |
7814 | Value of the attribute @code{Size} for a type | |
7815 | ||
7816 | @item | |
7817 | Warning about sizes not matching for unchecked conversion | |
7818 | @end itemize | |
7819 | ||
7820 | @noindent | |
7821 | For types other than discrete and fixed-point types, the @code{Object_Size} | |
7822 | and Value_Size are the same (and equivalent to the RM attribute @code{Size}). | |
7823 | Only @code{Size} may be specified for such types. | |
7824 | ||
7825 | @node Component_Size Clauses | |
7826 | @section Component_Size Clauses | |
7827 | @cindex Component_Size Clause | |
7828 | ||
7829 | @noindent | |
7830 | Normally, the value specified in a component clause must be consistent | |
7831 | with the subtype of the array component with regard to size and alignment. | |
7832 | In other words, the value specified must be at least equal to the size | |
7833 | of this subtype, and must be a multiple of the alignment value. | |
7834 | ||
7835 | In addition, component size clauses are allowed which cause the array | |
ad42149c FW |
7836 | to be packed, by specifying a smaller value. The cases in which this |
7837 | is allowed are for component size values in the range 1 through 63. The value | |
7838 | specified must not be smaller than the Size of the subtype. GNAT will | |
7839 | accurately honor all packing requests in this range. For example, if | |
41af791f GB |
7840 | we have: |
7841 | ||
7842 | @smallexample | |
7843 | type r is array (1 .. 8) of Natural; | |
7844 | for r'Size use 31; | |
7845 | @end smallexample | |
7846 | ||
7847 | @noindent | |
7848 | then the resulting array has a length of 31 bytes (248 bits = 8 * 31). | |
7849 | Of course access to the components of such an array is considerably | |
7850 | less efficient than if the natural component size of 32 is used. | |
7851 | ||
7852 | @node Bit_Order Clauses | |
7853 | @section Bit_Order Clauses | |
7854 | @cindex Bit_Order Clause | |
7855 | @cindex bit ordering | |
7856 | @cindex ordering, of bits | |
7857 | ||
7858 | @noindent | |
7859 | For record subtypes, GNAT permits the specification of the @code{Bit_Order} | |
ad42149c | 7860 | attribute. The specification may either correspond to the default bit |
41af791f GB |
7861 | order for the target, in which case the specification has no effect and |
7862 | places no additional restrictions, or it may be for the non-standard | |
7863 | setting (that is the opposite of the default). | |
7864 | ||
7865 | In the case where the non-standard value is specified, the effect is | |
7866 | to renumber bits within each byte, but the ordering of bytes is not | |
ad42149c | 7867 | affected. There are certain |
41af791f GB |
7868 | restrictions placed on component clauses as follows: |
7869 | ||
7870 | @itemize @bullet | |
7871 | ||
7872 | @item Components fitting within a single storage unit. | |
7873 | @noindent | |
ad42149c | 7874 | These are unrestricted, and the effect is merely to renumber bits. For |
41af791f GB |
7875 | example if we are on a little-endian machine with @code{Low_Order_First} |
7876 | being the default, then the following two declarations have exactly | |
7877 | the same effect: | |
7878 | ||
7879 | @smallexample | |
7880 | type R1 is record | |
7881 | A : Boolean; | |
7882 | B : Integer range 1 .. 120; | |
7883 | end record; | |
7884 | ||
7885 | for R1 use record | |
7886 | A at 0 range 0 .. 0; | |
7887 | B at 0 range 1 .. 7; | |
7888 | end record; | |
7889 | ||
7890 | type R2 is record | |
7891 | A : Boolean; | |
7892 | B : Integer range 1 .. 120; | |
7893 | end record; | |
7894 | ||
7895 | for R2'Bit_Order use High_Order_First; | |
7896 | ||
7897 | for R2 use record | |
7898 | A at 0 range 7 .. 7; | |
7899 | B at 0 range 0 .. 6; | |
7900 | end record; | |
7901 | @end smallexample | |
7902 | ||
7903 | @noindent | |
7904 | The useful application here is to write the second declaration with the | |
7905 | @code{Bit_Order} attribute definition clause, and know that it will be treated | |
7906 | the same, regardless of whether the target is little-endian or big-endian. | |
7907 | ||
7908 | @item Components occupying an integral number of bytes. | |
7909 | @noindent | |
ad42149c | 7910 | These are components that exactly fit in two or more bytes. Such component |
41af791f GB |
7911 | declarations are allowed, but have no effect, since it is important to realize |
7912 | that the @code{Bit_Order} specification does not affect the ordering of bytes. | |
7913 | In particular, the following attempt at getting an endian-independent integer | |
7914 | does not work: | |
7915 | ||
7916 | @smallexample | |
7917 | type R2 is record | |
7918 | A : Integer; | |
7919 | end record; | |
7920 | ||
7921 | for R2'Bit_Order use High_Order_First; | |
7922 | ||
7923 | for R2 use record | |
7924 | A at 0 range 0 .. 31; | |
7925 | end record; | |
7926 | @end smallexample | |
7927 | ||
7928 | @noindent | |
7929 | This declaration will result in a little-endian integer on a | |
7930 | little-endian machine, and a big-endian integer on a big-endian machine. | |
7931 | If byte flipping is required for interoperability between big- and | |
ad42149c | 7932 | little-endian machines, this must be explicitly programmed. This capability |
41af791f GB |
7933 | is not provided by @code{Bit_Order}. |
7934 | ||
7935 | @item Components that are positioned across byte boundaries | |
7936 | @noindent | |
ad42149c | 7937 | but do not occupy an integral number of bytes. Given that bytes are not |
41af791f | 7938 | reordered, such fields would occupy a non-contiguous sequence of bits |
ad42149c | 7939 | in memory, requiring non-trivial code to reassemble. They are for this |
41af791f | 7940 | reason not permitted, and any component clause specifying such a layout |
46b58b8c | 7941 | will be flagged as illegal by GNAT@. |
41af791f GB |
7942 | |
7943 | @end itemize | |
7944 | ||
7945 | @noindent | |
7946 | Since the misconception that Bit_Order automatically deals with all | |
7947 | endian-related incompatibilities is a common one, the specification of | |
7948 | a component field that is an integral number of bytes will always | |
ad42149c FW |
7949 | generate a warning. This warning may be suppressed using |
7950 | @code{pragma Suppress} if desired. The following section contains additional | |
41af791f GB |
7951 | details regarding the issue of byte ordering. |
7952 | ||
7953 | @node Effect of Bit_Order on Byte Ordering | |
7954 | @section Effect of Bit_Order on Byte Ordering | |
7955 | @cindex byte ordering | |
7956 | @cindex ordering, of bytes | |
7957 | ||
7958 | @noindent | |
3a77b68d | 7959 | In this section we will review the effect of the @code{Bit_Order} attribute |
ad42149c FW |
7960 | definition clause on byte ordering. Briefly, it has no effect at all, but |
7961 | a detailed example will be helpful. Before giving this | |
41af791f | 7962 | example, let us review the precise |
ad42149c | 7963 | definition of the effect of defining @code{Bit_Order}. The effect of a |
41af791f GB |
7964 | non-standard bit order is described in section 15.5.3 of the Ada |
7965 | Reference Manual: | |
7966 | ||
7967 | @smallexample | |
7968 | 2 A bit ordering is a method of interpreting the meaning of | |
7969 | the storage place attributes. | |
7970 | @end smallexample | |
7971 | ||
7972 | @noindent | |
7973 | To understand the precise definition of storage place attributes in | |
7974 | this context, we visit section 13.5.1 of the manual: | |
7975 | ||
7976 | @smallexample | |
7977 | 13 A record_representation_clause (without the mod_clause) | |
ad42149c | 7978 | specifies the layout. The storage place attributes (see 13.5.2) |
41af791f GB |
7979 | are taken from the values of the position, first_bit, and last_bit |
7980 | expressions after normalizing those values so that first_bit is | |
7981 | less than Storage_Unit. | |
7982 | @end smallexample | |
7983 | ||
7984 | @noindent | |
7985 | The critical point here is that storage places are taken from | |
ad42149c FW |
7986 | the values after normalization, not before. So the @code{Bit_Order} |
7987 | interpretation applies to normalized values. The interpretation | |
41af791f GB |
7988 | is described in the later part of the 15.5.3 paragraph: |
7989 | ||
7990 | @smallexample | |
7991 | 2 A bit ordering is a method of interpreting the meaning of | |
7992 | the storage place attributes. High_Order_First (known in the | |
ad42149c | 7993 | vernacular as ``big endian'') means that the first bit of a |
41af791f GB |
7994 | storage element (bit 0) is the most significant bit (interpreting |
7995 | the sequence of bits that represent a component as an unsigned | |
ad42149c FW |
7996 | integer value). Low_Order_First (known in the vernacular as |
7997 | ``little endian'') means the opposite: the first bit is the | |
41af791f GB |
7998 | least significant. |
7999 | @end smallexample | |
8000 | ||
8001 | @noindent | |
8002 | Note that the numbering is with respect to the bits of a storage | |
ad42149c | 8003 | unit. In other words, the specification affects only the numbering |
41af791f GB |
8004 | of bits within a single storage unit. |
8005 | ||
8006 | We can make the effect clearer by giving an example. | |
8007 | ||
8008 | Suppose that we have an external device which presents two bytes, the first | |
8009 | byte presented, which is the first (low addressed byte) of the two byte | |
8010 | record is called Master, and the second byte is called Slave. | |
8011 | ||
8012 | The left most (most significant bit is called Control for each byte, and | |
ad42149c FW |
8013 | the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost |
8014 | (least significant) bit. | |
41af791f GB |
8015 | |
8016 | On a big-endian machine, we can write the following representation clause | |
8017 | ||
8018 | @smallexample | |
8019 | type Data is record | |
8020 | Master_Control : Bit; | |
8021 | Master_V1 : Bit; | |
8022 | Master_V2 : Bit; | |
8023 | Master_V3 : Bit; | |
8024 | Master_V4 : Bit; | |
8025 | Master_V5 : Bit; | |
8026 | Master_V6 : Bit; | |
8027 | Master_V7 : Bit; | |
8028 | Slave_Control : Bit; | |
8029 | Slave_V1 : Bit; | |
8030 | Slave_V2 : Bit; | |
8031 | Slave_V3 : Bit; | |
8032 | Slave_V4 : Bit; | |
8033 | Slave_V5 : Bit; | |
8034 | Slave_V6 : Bit; | |
8035 | Slave_V7 : Bit; | |
8036 | end record; | |
8037 | ||
8038 | for Data use record | |
8039 | Master_Control at 0 range 0 .. 0; | |
8040 | Master_V1 at 0 range 1 .. 1; | |
8041 | Master_V2 at 0 range 2 .. 2; | |
8042 | Master_V3 at 0 range 3 .. 3; | |
8043 | Master_V4 at 0 range 4 .. 4; | |
8044 | Master_V5 at 0 range 5 .. 5; | |
8045 | Master_V6 at 0 range 6 .. 6; | |
8046 | Master_V7 at 0 range 7 .. 7; | |
8047 | Slave_Control at 1 range 0 .. 0; | |
8048 | Slave_V1 at 1 range 1 .. 1; | |
8049 | Slave_V2 at 1 range 2 .. 2; | |
8050 | Slave_V3 at 1 range 3 .. 3; | |
8051 | Slave_V4 at 1 range 4 .. 4; | |
8052 | Slave_V5 at 1 range 5 .. 5; | |
8053 | Slave_V6 at 1 range 6 .. 6; | |
8054 | Slave_V7 at 1 range 7 .. 7; | |
8055 | end record; | |
8056 | @end smallexample | |
8057 | ||
8058 | @noindent | |
8059 | Now if we move this to a little endian machine, then the bit ordering within | |
8060 | the byte is backwards, so we have to rewrite the record rep clause as: | |
8061 | ||
8062 | @smallexample | |
8063 | for Data use record | |
8064 | Master_Control at 0 range 7 .. 7; | |
8065 | Master_V1 at 0 range 6 .. 6; | |
8066 | Master_V2 at 0 range 5 .. 5; | |
8067 | Master_V3 at 0 range 4 .. 4; | |
8068 | Master_V4 at 0 range 3 .. 3; | |
8069 | Master_V5 at 0 range 2 .. 2; | |
8070 | Master_V6 at 0 range 1 .. 1; | |
8071 | Master_V7 at 0 range 0 .. 0; | |
8072 | Slave_Control at 1 range 7 .. 7; | |
8073 | Slave_V1 at 1 range 6 .. 6; | |
8074 | Slave_V2 at 1 range 5 .. 5; | |
8075 | Slave_V3 at 1 range 4 .. 4; | |
8076 | Slave_V4 at 1 range 3 .. 3; | |
8077 | Slave_V5 at 1 range 2 .. 2; | |
8078 | Slave_V6 at 1 range 1 .. 1; | |
8079 | Slave_V7 at 1 range 0 .. 0; | |
8080 | end record; | |
8081 | @end smallexample | |
8082 | ||
8083 | It is a nuisance to have to rewrite the clause, especially if | |
ad42149c | 8084 | the code has to be maintained on both machines. However, |
41af791f GB |
8085 | this is a case that we can handle with the |
8086 | @code{Bit_Order} attribute if it is implemented. | |
8087 | Note that the implementation is not required on byte addressed | |
ad42149c | 8088 | machines, but it is indeed implemented in GNAT. |
41af791f GB |
8089 | This means that we can simply use the |
8090 | first record clause, together with the declaration | |
8091 | ||
8092 | @smallexample | |
8093 | for Data'Bit_Order use High_Order_First; | |
8094 | @end smallexample | |
8095 | ||
8096 | @noindent | |
8097 | and the effect is what is desired, namely the layout is exactly the same, | |
ad42149c | 8098 | independent of whether the code is compiled on a big-endian or little-endian |
41af791f GB |
8099 | machine. |
8100 | ||
8101 | The important point to understand is that byte ordering is not affected. | |
8102 | A @code{Bit_Order} attribute definition never affects which byte a field | |
8103 | ends up in, only where it ends up in that byte. | |
8104 | To make this clear, let us rewrite the record rep clause of the previous | |
8105 | example as: | |
8106 | ||
8107 | @smallexample | |
8108 | for Data'Bit_Order use High_Order_First; | |
8109 | for Data use record | |
ad42149c FW |
8110 | Master_Control at 0 range 0 .. 0; |
8111 | Master_V1 at 0 range 1 .. 1; | |
8112 | Master_V2 at 0 range 2 .. 2; | |
8113 | Master_V3 at 0 range 3 .. 3; | |
8114 | Master_V4 at 0 range 4 .. 4; | |
8115 | Master_V5 at 0 range 5 .. 5; | |
8116 | Master_V6 at 0 range 6 .. 6; | |
8117 | Master_V7 at 0 range 7 .. 7; | |
8118 | Slave_Control at 0 range 8 .. 8; | |
8119 | Slave_V1 at 0 range 9 .. 9; | |
41af791f GB |
8120 | Slave_V2 at 0 range 10 .. 10; |
8121 | Slave_V3 at 0 range 11 .. 11; | |
8122 | Slave_V4 at 0 range 12 .. 12; | |
8123 | Slave_V5 at 0 range 13 .. 13; | |
8124 | Slave_V6 at 0 range 14 .. 14; | |
8125 | Slave_V7 at 0 range 15 .. 15; | |
8126 | end record; | |
8127 | @end smallexample | |
8128 | ||
8129 | @noindent | |
8130 | This is exactly equivalent to saying (a repeat of the first example): | |
8131 | ||
8132 | @smallexample | |
8133 | for Data'Bit_Order use High_Order_First; | |
8134 | for Data use record | |
8135 | Master_Control at 0 range 0 .. 0; | |
8136 | Master_V1 at 0 range 1 .. 1; | |
8137 | Master_V2 at 0 range 2 .. 2; | |
8138 | Master_V3 at 0 range 3 .. 3; | |
8139 | Master_V4 at 0 range 4 .. 4; | |
8140 | Master_V5 at 0 range 5 .. 5; | |
8141 | Master_V6 at 0 range 6 .. 6; | |
8142 | Master_V7 at 0 range 7 .. 7; | |
8143 | Slave_Control at 1 range 0 .. 0; | |
8144 | Slave_V1 at 1 range 1 .. 1; | |
8145 | Slave_V2 at 1 range 2 .. 2; | |
8146 | Slave_V3 at 1 range 3 .. 3; | |
8147 | Slave_V4 at 1 range 4 .. 4; | |
8148 | Slave_V5 at 1 range 5 .. 5; | |
8149 | Slave_V6 at 1 range 6 .. 6; | |
8150 | Slave_V7 at 1 range 7 .. 7; | |
8151 | end record; | |
8152 | @end smallexample | |
8153 | ||
8154 | @noindent | |
8155 | Why are they equivalent? Well take a specific field, the @code{Slave_V2} | |
ad42149c FW |
8156 | field. The storage place attributes are obtained by normalizing the |
8157 | values given so that the @code{First_Bit} value is less than 8. After | |
41af791f GB |
8158 | nromalizing the values (0,10,10) we get (1,2,2) which is exactly what |
8159 | we specified in the other case. | |
8160 | ||
8161 | Now one might expect that the @code{Bit_Order} attribute might affect | |
8162 | bit numbering within the entire record component (two bytes in this | |
8163 | case, thus affecting which byte fields end up in), but that is not | |
8164 | the way this feature is defined, it only affects numbering of bits, | |
8165 | not which byte they end up in. | |
8166 | ||
8167 | Consequently it never makes sense to specify a starting bit number | |
8168 | greater than 7 (for a byte addressable field) if an attribute | |
8169 | definition for @code{Bit_Order} has been given, and indeed it | |
8170 | may be actively confusing to specify such a value, so the compiler | |
8171 | generates a warning for such usage. | |
8172 | ||
8173 | If you do need to control byte ordering then appropriate conditional | |
ad42149c | 8174 | values must be used. If in our example, the slave byte came first on |
41af791f GB |
8175 | some machines we might write: |
8176 | ||
8177 | @smallexample | |
ad42149c | 8178 | Master_Byte_First constant Boolean := @dots{}; |
41af791f GB |
8179 | |
8180 | Master_Byte : constant Natural := | |
8181 | 1 - Boolean'Pos (Master_Byte_First); | |
8182 | Slave_Byte : constant Natural := | |
8183 | Boolean'Pos (Master_Byte_First); | |
8184 | ||
8185 | for Data'Bit_Order use High_Order_First; | |
8186 | for Data use record | |
8187 | Master_Control at Master_Byte range 0 .. 0; | |
8188 | Master_V1 at Master_Byte range 1 .. 1; | |
8189 | Master_V2 at Master_Byte range 2 .. 2; | |
8190 | Master_V3 at Master_Byte range 3 .. 3; | |
8191 | Master_V4 at Master_Byte range 4 .. 4; | |
8192 | Master_V5 at Master_Byte range 5 .. 5; | |
8193 | Master_V6 at Master_Byte range 6 .. 6; | |
8194 | Master_V7 at Master_Byte range 7 .. 7; | |
8195 | Slave_Control at Slave_Byte range 0 .. 0; | |
8196 | Slave_V1 at Slave_Byte range 1 .. 1; | |
8197 | Slave_V2 at Slave_Byte range 2 .. 2; | |
8198 | Slave_V3 at Slave_Byte range 3 .. 3; | |
8199 | Slave_V4 at Slave_Byte range 4 .. 4; | |
8200 | Slave_V5 at Slave_Byte range 5 .. 5; | |
8201 | Slave_V6 at Slave_Byte range 6 .. 6; | |
8202 | Slave_V7 at Slave_Byte range 7 .. 7; | |
8203 | end record; | |
8204 | @end smallexample | |
8205 | ||
8206 | @noindent | |
8207 | Now to switch between machines, all that is necessary is | |
8208 | to set the boolean constant @code{Master_Byte_First} in | |
8209 | an appropriate manner. | |
8210 | ||
8211 | @node Pragma Pack for Arrays | |
8212 | @section Pragma Pack for Arrays | |
8213 | @cindex Pragma Pack (for arrays) | |
8214 | ||
8215 | @noindent | |
ad42149c FW |
8216 | Pragma @code{Pack} applied to an array has no effect unless the component type |
8217 | is packable. For a component type to be packable, it must be one of the | |
41af791f GB |
8218 | following cases: |
8219 | ||
8220 | @itemize @bullet | |
8221 | @item | |
8222 | Any scalar type | |
8223 | @item | |
8224 | Any fixed-point type | |
8225 | @item | |
8226 | Any type whose size is specified with a size clause | |
8227 | @item | |
8228 | Any packed array type with a static size | |
8229 | @end itemize | |
8230 | ||
8231 | @noindent | |
8232 | For all these cases, if the component subtype size is in the range | |
ad42149c | 8233 | 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a |
41af791f GB |
8234 | component size were specified giving the component subtype size. |
8235 | For example if we have: | |
8236 | ||
8237 | @smallexample | |
8238 | type r is range 0 .. 17; | |
8239 | ||
8240 | type ar is array (1 .. 8) of r; | |
8241 | pragma Pack (ar); | |
8242 | @end smallexample | |
8243 | ||
8244 | @noindent | |
46b58b8c | 8245 | Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, |
41af791f GB |
8246 | and the size of the array @code{ar} will be exactly 40 bits. |
8247 | ||
8248 | Note that in some cases this rather fierce approach to packing can produce | |
ad42149c | 8249 | unexpected effects. For example, in Ada 95, type Natural typically has a |
41af791f GB |
8250 | size of 31, meaning that if you pack an array of Natural, you get 31-bit |
8251 | close packing, which saves a few bits, but results in far less efficient | |
ad42149c FW |
8252 | access. Since many other Ada compilers will ignore such a packing request, |
8253 | GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses | |
8254 | might not be what is intended. You can easily remove this warning by | |
8255 | using an explicit @code{Component_Size} setting instead, which never generates | |
41af791f GB |
8256 | a warning, since the intention of the programmer is clear in this case. |
8257 | ||
ad42149c | 8258 | GNAT treats packed arrays in one of two ways. If the size of the array is |
41af791f GB |
8259 | known at compile time and is less than 64 bits, then internally the array |
8260 | is represented as a single modular type, of exactly the appropriate number | |
ad42149c | 8261 | of bits. If the length is greater than 63 bits, or is not known at compile |
41af791f GB |
8262 | time, then the packed array is represented as an array of bytes, and the |
8263 | length is always a multiple of 8 bits. | |
8264 | ||
8265 | @node Pragma Pack for Records | |
8266 | @section Pragma Pack for Records | |
8267 | @cindex Pragma Pack (for records) | |
8268 | ||
8269 | @noindent | |
ad42149c | 8270 | Pragma @code{Pack} applied to a record will pack the components to reduce wasted |
41af791f | 8271 | space from alignment gaps and by reducing the amount of space taken by |
ad42149c FW |
8272 | components. We distinguish between package components and non-packable |
8273 | components. Components of the following types are considered packable: | |
41af791f GB |
8274 | |
8275 | @itemize @bullet | |
8276 | @item | |
8277 | All scalar types are packable. | |
8278 | ||
8279 | @item | |
8280 | All fixed-point types are represented internally as integers, and | |
8281 | are packable. | |
8282 | ||
8283 | @item | |
8284 | Small packed arrays, whose size does not exceed 64 bits, and where the | |
8285 | size is statically known at compile time, are represented internally | |
8286 | as modular integers, and so they are also packable. | |
8287 | ||
8288 | @end itemize | |
8289 | ||
8290 | @noindent | |
8291 | All packable components occupy the exact number of bits corresponding to | |
46b58b8c | 8292 | their @code{Size} value, and are packed with no padding bits, i.e.@: they |
41af791f GB |
8293 | can start on an arbitrary bit boundary. |
8294 | ||
8295 | All other types are non-packable, they occupy an integral number of | |
8296 | storage units, and | |
8297 | are placed at a boundary corresponding to their alignment requirements. | |
8298 | ||
8299 | For example, consider the record | |
8300 | ||
8301 | @smallexample | |
8302 | type Rb1 is array (1 .. 13) of Boolean; | |
8303 | pragma Pack (rb1); | |
8304 | ||
8305 | type Rb2 is array (1 .. 65) of Boolean; | |
8306 | pragma Pack (rb2); | |
8307 | ||
8308 | type x2 is record | |
8309 | l1 : Boolean; | |
8310 | l2 : Duration; | |
8311 | l3 : Float; | |
8312 | l4 : Boolean; | |
8313 | l5 : Rb1; | |
8314 | l6 : Rb2; | |
8315 | end record; | |
8316 | pragma Pack (x2); | |
8317 | @end smallexample | |
8318 | ||
8319 | @noindent | |
8320 | The representation for the record x2 is as follows: | |
8321 | ||
8322 | @smallexample | |
8323 | for x2'Size use 224; | |
8324 | for x2 use record | |
ad42149c | 8325 | l1 at 0 range 0 .. 0; |
41af791f GB |
8326 | l2 at 0 range 1 .. 64; |
8327 | l3 at 12 range 0 .. 31; | |
ad42149c | 8328 | l4 at 16 range 0 .. 0; |
41af791f GB |
8329 | l5 at 16 range 1 .. 13; |
8330 | l6 at 18 range 0 .. 71; | |
8331 | end record; | |
8332 | @end smallexample | |
8333 | ||
8334 | @noindent | |
8335 | Studying this example, we see that the packable fields @code{l1} | |
8336 | and @code{l2} are | |
8337 | of length equal to their sizes, and placed at specific bit boundaries (and | |
8338 | not byte boundaries) to | |
ad42149c | 8339 | eliminate padding. But @code{l3} is of a non-packable float type, so |
41af791f GB |
8340 | it is on the next appropriate alignment boundary. |
8341 | ||
8342 | The next two fields are fully packable, so @code{l4} and @code{l5} are | |
ad42149c FW |
8343 | minimally packed with no gaps. However, type @code{Rb2} is a packed |
8344 | array that is longer than 64 bits, so it is itself non-packable. Thus | |
41af791f | 8345 | the @code{l6} field is aligned to the next byte boundary, and takes an |
46b58b8c | 8346 | integral number of bytes, i.e.@: 72 bits. |
41af791f GB |
8347 | |
8348 | @node Record Representation Clauses | |
8349 | @section Record Representation Clauses | |
8350 | @cindex Record Representation Clause | |
8351 | ||
8352 | @noindent | |
8353 | Record representation clauses may be given for all record types, including | |
ad42149c FW |
8354 | types obtained by record extension. Component clauses are allowed for any |
8355 | static component. The restrictions on component clauses depend on the type | |
41af791f GB |
8356 | of the component. |
8357 | ||
8358 | @cindex Component Clause | |
8359 | For all components of an elementary type, the only restriction on component | |
8360 | clauses is that the size must be at least the 'Size value of the type | |
ad42149c | 8361 | (actually the Value_Size). There are no restrictions due to alignment, |
41af791f GB |
8362 | and such components may freely cross storage boundaries. |
8363 | ||
ad42149c | 8364 | Packed arrays with a size up to and including 64 bits are represented |
41af791f | 8365 | internally using a modular type with the appropriate number of bits, and |
ad42149c | 8366 | thus the same lack of restriction applies. For example, if you declare: |
41af791f GB |
8367 | |
8368 | @smallexample | |
8369 | type R is array (1 .. 49) of Boolean; | |
8370 | pragma Pack (R); | |
8371 | for R'Size use 49; | |
8372 | @end smallexample | |
8373 | ||
8374 | @noindent | |
8375 | then a component clause for a component of type R may start on any | |
8376 | specified bit boundary, and may specify a value of 49 bits or greater. | |
8377 | ||
8378 | For non-primitive types, including packed arrays with a size greater than | |
ad42149c | 8379 | 64 bits, component clauses must respect the alignment requirement of the |
41af791f GB |
8380 | type, in particular, always starting on a byte boundary, and the length |
8381 | must be a multiple of the storage unit. | |
8382 | ||
8383 | The tag field of a tagged type always occupies an address sized field at | |
ad42149c | 8384 | the start of the record. No component clause may attempt to overlay this |
41af791f GB |
8385 | tag. |
8386 | ||
8387 | In the case of a record extension T1, of a type T, no component clause applied | |
8388 | to the type T1 can specify a storage location that would overlap the first | |
8389 | T'Size bytes of the record. | |
8390 | ||
8391 | @node Enumeration Clauses | |
8392 | @section Enumeration Clauses | |
8393 | ||
8394 | The only restriction on enumeration clauses is that the range of values | |
ad42149c | 8395 | must be representable. For the signed case, if one or more of the |
41af791f GB |
8396 | representation values are negative, all values must be in the range: |
8397 | ||
8398 | @smallexample | |
8399 | System.Min_Int .. System.Max_Int | |
8400 | @end smallexample | |
8401 | ||
8402 | @noindent | |
8403 | For the unsigned case, where all values are non negative, the values must | |
8404 | be in the range: | |
8405 | ||
8406 | @smallexample | |
8407 | 0 .. System.Max_Binary_Modulus; | |
8408 | @end smallexample | |
8409 | ||
8410 | @noindent | |
ad42149c | 8411 | A @emph{confirming} representation clause is one in which the values range |
46b58b8c | 8412 | from 0 in sequence, i.e.@: a clause that confirms the default representation |
41af791f GB |
8413 | for an enumeration type. |
8414 | Such a confirming representation | |
8415 | is permitted by these rules, and is specially recognized by the compiler so | |
8416 | that no extra overhead results from the use of such a clause. | |
8417 | ||
8418 | If an array has an index type which is an enumeration type to which an | |
8419 | enumeration clause has been applied, then the array is stored in a compact | |
ad42149c | 8420 | manner. Consider the declarations: |
41af791f GB |
8421 | |
8422 | @smallexample | |
8423 | type r is (A, B, C); | |
8424 | for r use (A => 1, B => 5, C => 10); | |
8425 | type t is array (r) of Character; | |
8426 | @end smallexample | |
8427 | ||
8428 | @noindent | |
8429 | The array type t corresponds to a vector with exactly three elements and | |
ad42149c | 8430 | has a default size equal to @code{3*Character'Size}. This ensures efficient |
41af791f GB |
8431 | use of space, but means that accesses to elements of the array will incur |
8432 | the overhead of converting representation values to the corresponding | |
ad42149c | 8433 | positional values, (i.e.@: the value delivered by the @code{Pos} attribute). |
41af791f GB |
8434 | |
8435 | @node Address Clauses | |
8436 | @section Address Clauses | |
8437 | @cindex Address Clause | |
8438 | ||
8439 | The reference manual allows a general restriction on representation clauses, | |
8440 | as found in RM 13.1(22): | |
8441 | ||
8442 | @smallexample | |
8443 | An implementation need not support representation | |
8444 | items containing nonstatic expressions, except that | |
8445 | an implementation should support a representation item | |
8446 | for a given entity if each nonstatic expression in the | |
8447 | representation item is a name that statically denotes | |
8448 | a constant declared before the entity. | |
8449 | @end smallexample | |
8450 | ||
8451 | @noindent | |
8452 | In practice this is applicable only to address clauses, since this is the | |
ad42149c | 8453 | only case in which a non-static expression is permitted by the syntax. As |
41af791f GB |
8454 | the AARM notes in sections 13.1 (22.a-22.h): |
8455 | ||
8456 | @smallexample | |
8457 | 22.a Reason: This is to avoid the following sort | |
8458 | of thing: | |
8459 | ||
ad42149c FW |
8460 | 22.b X : Integer := F(@dots{}); |
8461 | Y : Address := G(@dots{}); | |
41af791f GB |
8462 | for X'Address use Y; |
8463 | ||
8464 | 22.c In the above, we have to evaluate the | |
8465 | initialization expression for X before we | |
ad42149c | 8466 | know where to put the result. This seems |
41af791f GB |
8467 | like an unreasonable implementation burden. |
8468 | ||
8469 | 22.d The above code should instead be written | |
8470 | like this: | |
8471 | ||
ad42149c FW |
8472 | 22.e Y : constant Address := G(@dots{}); |
8473 | X : Integer := F(@dots{}); | |
41af791f GB |
8474 | for X'Address use Y; |
8475 | ||
8476 | 22.f This allows the expression ``Y'' to be safely | |
8477 | evaluated before X is created. | |
8478 | ||
8479 | 22.g The constant could be a formal parameter of mode in. | |
8480 | ||
8481 | 22.h An implementation can support other nonstatic | |
ad42149c | 8482 | expressions if it wants to. Expressions of type |
41af791f GB |
8483 | Address are hardly ever static, but their value |
8484 | might be known at compile time anyway in many | |
8485 | cases. | |
8486 | @end smallexample | |
8487 | ||
8488 | @noindent | |
ad42149c | 8489 | GNAT does indeed permit many additional cases of non-static expressions. In |
41af791f GB |
8490 | particular, if the type involved is elementary there are no restrictions |
8491 | (since in this case, holding a temporary copy of the initialization value, | |
ad42149c FW |
8492 | if one is present, is inexpensive). In addition, if there is no implicit or |
8493 | explicit initialization, then there are no restrictions. GNAT will reject | |
41af791f GB |
8494 | only the case where all three of these conditions hold: |
8495 | ||
8496 | @itemize @bullet | |
8497 | ||
8498 | @item | |
46b58b8c | 8499 | The type of the item is non-elementary (e.g.@: a record or array). |
41af791f GB |
8500 | |
8501 | @item | |
8502 | There is explicit or implicit initialization required for the object. | |
8503 | ||
8504 | @item | |
ad42149c | 8505 | The address value is non-static. Here GNAT is more permissive than the |
41af791f GB |
8506 | RM, and allows the address value to be the address of a previously declared |
8507 | stand-alone variable, as long as it does not itself have an address clause. | |
8508 | ||
8509 | @smallexample | |
8510 | Anchor : Some_Initialized_Type; | |
8511 | Overlay : Some_Initialized_Type; | |
8512 | for Overlay'Address use Anchor'Address; | |
8513 | @end smallexample | |
8514 | ||
8515 | However, the prefix of the address clause cannot be an array component, or | |
8516 | a component of a discriminated record. | |
8517 | ||
8518 | @end itemize | |
8519 | ||
8520 | @noindent | |
ad42149c | 8521 | As noted above in section 22.h, address values are typically non-static. In |
41af791f | 8522 | particular the To_Address function, even if applied to a literal value, is |
ad42149c FW |
8523 | a non-static function call. To avoid this minor annoyance, GNAT provides |
8524 | the implementation defined attribute 'To_Address. The following two | |
41af791f GB |
8525 | expressions have identical values: |
8526 | ||
ad42149c FW |
8527 | Another issue with address clauses is the interaction with alignment |
8528 | requirements. When an address clause is given for an object, the address | |
8529 | value must be consistent with the alignment of the object (which is usually | |
8530 | the same as the alignment of the type of the object). If an address clause | |
8531 | is given that specifies an inappropriately aligned address value, then the | |
8532 | program execution is erroneous. | |
8533 | ||
8534 | Since this source of erroneous behavior can have unfortunate effects, GNAT | |
8535 | checks (at compile time if possible, generating a warning, or at execution | |
8536 | time with a run-time check) that the alignment is appropriate. If the | |
8537 | run-time check fails, then @code{Program_Error} is raised. This run-time | |
8538 | check is suppressed if range checks are suppressed, or if | |
8539 | @code{pragma Restrictions (No_Elaboration_Code)} is in effect. | |
8540 | ||
41af791f GB |
8541 | @findex Attribute |
8542 | @findex To_Address | |
8543 | @smallexample | |
8544 | To_Address (16#1234_0000#) | |
8545 | System'To_Address (16#1234_0000#); | |
8546 | @end smallexample | |
8547 | ||
8548 | @noindent | |
8549 | except that the second form is considered to be a static expression, and | |
8550 | thus when used as an address clause value is always permitted. | |
8551 | ||
8552 | @noindent | |
8553 | Additionally, GNAT treats as static an address clause that is an | |
ad42149c | 8554 | unchecked_conversion of a static integer value. This simplifies the porting |
41af791f GB |
8555 | of legacy code, and provides a portable equivalent to the GNAT attribute |
8556 | To_Address. | |
8557 | ||
8558 | @findex Export | |
ad42149c | 8559 | An address clause cannot be given for an exported object. More |
41af791f | 8560 | understandably the real restriction is that objects with an address |
ad42149c | 8561 | clause cannot be exported. This is because such variables are not |
41af791f GB |
8562 | defined by the Ada program, so there is no external object so export. |
8563 | ||
8564 | @findex Import | |
8565 | It is permissible to give an address clause and a pragma Import for the | |
ad42149c FW |
8566 | same object. In this case, the variable is not really defined by the |
8567 | Ada program, so there is no external symbol to be linked. The link name | |
8568 | and the external name are ignored in this case. The reason that we allow this | |
41af791f GB |
8569 | combination is that it provides a useful idiom to avoid unwanted |
8570 | initializations on objects with address clauses. | |
8571 | ||
8572 | When an address clause is given for an object that has implicit or | |
ad42149c | 8573 | explicit initialization, then by default initialization takes place. This |
41af791f | 8574 | means that the effect of the object declaration is to overwrite the |
ad42149c | 8575 | memory at the specified address. This is almost always not what the |
41af791f GB |
8576 | programmer wants, so GNAT will output a warning: |
8577 | ||
8578 | @smallexample | |
8579 | with System; | |
8580 | package G is | |
8581 | type R is record | |
8582 | M : Integer := 0; | |
8583 | end record; | |
8584 | ||
8585 | Ext : R; | |
8586 | for Ext'Address use System'To_Address (16#1234_1234#); | |
8587 | | | |
8588 | >>> warning: implicit initialization of "Ext" may | |
8589 | modify overlaid storage | |
8590 | >>> warning: use pragma Import for "Ext" to suppress | |
8591 | initialization (RM B(24)) | |
8592 | ||
8593 | end G; | |
8594 | @end smallexample | |
8595 | ||
8596 | @noindent | |
8597 | As indicated by the warning message, the solution is to use a (dummy) pragma | |
ad42149c FW |
8598 | Import to suppress this initialization. The pragma tell the compiler that the |
8599 | object is declared and initialized elsewhere. The following package compiles | |
41af791f GB |
8600 | without warnings (and the initialization is suppressed): |
8601 | ||
8602 | @smallexample | |
8603 | with System; | |
8604 | package G is | |
8605 | type R is record | |
8606 | M : Integer := 0; | |
8607 | end record; | |
8608 | ||
8609 | Ext : R; | |
8610 | for Ext'Address use System'To_Address (16#1234_1234#); | |
8611 | pragma Import (Ada, Ext); | |
8612 | end G; | |
8613 | @end smallexample | |
8614 | ||
8615 | @node Effect of Convention on Representation | |
8616 | @section Effect of Convention on Representation | |
8617 | @cindex Convention, effect on representation | |
8618 | ||
8619 | @noindent | |
8620 | Normally the specification of a foreign language convention for a type or | |
ad42149c | 8621 | an object has no effect on the chosen representation. In particular, the |
41af791f GB |
8622 | representation chosen for data in GNAT generally meets the standard system |
8623 | conventions, and for example records are laid out in a manner that is | |
ad42149c | 8624 | consistent with C@. This means that specifying convention C (for example) |
41af791f GB |
8625 | has no effect. |
8626 | ||
8627 | There are three exceptions to this general rule: | |
8628 | ||
8629 | @itemize @bullet | |
8630 | ||
8631 | @item Convention Fortran and array subtypes | |
8632 | If pragma Convention Fortran is specified for an array subtype, then in | |
8633 | accordance with the implementation advice in section 3.6.2(11) of the | |
8634 | Ada Reference Manual, the array will be stored in a Fortran-compatible | |
8635 | column-major manner, instead of the normal default row-major order. | |
8636 | ||
8637 | @item Convention C and enumeration types | |
8638 | GNAT normally stores enumeration types in 8, 16, or 32 bits as required | |
ad42149c | 8639 | to accommodate all values of the type. For example, for the enumeration |
41af791f GB |
8640 | type declared by: |
8641 | ||
8642 | @smallexample | |
8643 | type Color is (Red, Green, Blue); | |
8644 | @end smallexample | |
8645 | ||
8646 | @noindent | |
8647 | 8 bits is sufficient to store all values of the type, so by default, objects | |
ad42149c FW |
8648 | of type @code{Color} will be represented using 8 bits. However, normal C |
8649 | convention is to use 32 bits for all enum values in C, since enum values | |
8650 | are essentially of type int. If pragma @code{Convention C} is specified for an | |
41af791f GB |
8651 | Ada enumeration type, then the size is modified as necessary (usually to |
8652 | 32 bits) to be consistent with the C convention for enum values. | |
8653 | ||
8654 | @item Convention C/Fortran and Boolean types | |
8655 | In C, the usual convention for boolean values, that is values used for | |
8656 | conditions, is that zero represents false, and nonzero values represent | |
ad42149c | 8657 | true. In Ada, the normal convention is that two specific values, typically |
41af791f GB |
8658 | 0/1, are used to represent false/true respectively. |
8659 | ||
8660 | Fortran has a similar convention for @code{LOGICAL} values (any nonzero | |
8661 | value represents true). | |
8662 | ||
8663 | To accommodate the Fortran and C conventions, if a pragma Convention specifies | |
8664 | C or Fortran convention for a derived Boolean, as in the following example: | |
8665 | ||
8666 | @smallexample | |
8667 | type C_Switch is new Boolean; | |
8668 | pragma Convention (C, C_Switch); | |
8669 | @end smallexample | |
8670 | ||
8671 | @noindent | |
ad42149c | 8672 | then the GNAT generated code will treat any nonzero value as true. For truth |
41af791f GB |
8673 | values generated by GNAT, the conventional value 1 will be used for True, but |
8674 | when one of these values is read, any nonzero value is treated as True. | |
8675 | ||
8676 | @end itemize | |
8677 | ||
8678 | @node Determining the Representations chosen by GNAT | |
8679 | @section Determining the Representations chosen by GNAT | |
8680 | @cindex Representation, determination of | |
ad42149c | 8681 | @cindex @code{-gnatR} switch |
41af791f GB |
8682 | |
8683 | @noindent | |
8684 | Although the descriptions in this section are intended to be complete, it is | |
8685 | often easier to simply experiment to see what GNAT accepts and what the | |
8686 | effect is on the layout of types and objects. | |
8687 | ||
8688 | As required by the Ada RM, if a representation clause is not accepted, then | |
ad42149c | 8689 | it must be rejected as illegal by the compiler. However, when a representation |
41af791f | 8690 | clause or pragma is accepted, there can still be questions of what the |
ad42149c | 8691 | compiler actually does. For example, if a partial record representation |
41af791f | 8692 | clause specifies the location of some components and not others, then where |
ad42149c | 8693 | are the non-specified components placed? Or if pragma @code{Pack} is used on a |
41af791f | 8694 | record, then exactly where are the resulting fields placed? The section |
ad42149c | 8695 | on pragma @code{Pack} in this chapter can be used to answer the second question, |
41af791f GB |
8696 | but it is often easier to just see what the compiler does. |
8697 | ||
ad42149c | 8698 | For this purpose, GNAT provides the option @code{-gnatR}. If you compile |
41af791f GB |
8699 | with this option, then the compiler will output information on the actual |
8700 | representations chosen, in a format similar to source representation | |
ad42149c | 8701 | clauses. For example, if we compile the package: |
41af791f GB |
8702 | |
8703 | @smallexample | |
8704 | package q is | |
8705 | type r (x : boolean) is tagged record | |
8706 | case x is | |
8707 | when True => S : String (1 .. 100); | |
8708 | when False => null; | |
8709 | end case; | |
8710 | end record; | |
8711 | ||
8712 | type r2 is new r (false) with record | |
8713 | y2 : integer; | |
8714 | end record; | |
8715 | ||
8716 | for r2 use record | |
8717 | y2 at 16 range 0 .. 31; | |
8718 | end record; | |
8719 | ||
8720 | type x is record | |
8721 | y : character; | |
8722 | end record; | |
8723 | ||
8724 | type x1 is array (1 .. 10) of x; | |
8725 | for x1'component_size use 11; | |
8726 | ||
8727 | type ia is access integer; | |
8728 | ||
8729 | type Rb1 is array (1 .. 13) of Boolean; | |
8730 | pragma Pack (rb1); | |
8731 | ||
8732 | type Rb2 is array (1 .. 65) of Boolean; | |
8733 | pragma Pack (rb2); | |
8734 | ||
8735 | type x2 is record | |
8736 | l1 : Boolean; | |
8737 | l2 : Duration; | |
8738 | l3 : Float; | |
8739 | l4 : Boolean; | |
8740 | l5 : Rb1; | |
8741 | l6 : Rb2; | |
8742 | end record; | |
8743 | pragma Pack (x2); | |
8744 | end q; | |
8745 | @end smallexample | |
8746 | ||
8747 | @noindent | |
8748 | using the switch @code{-gnatR} we obtain the following output: | |
8749 | ||
8750 | @smallexample | |
8751 | Representation information for unit q | |
8752 | ------------------------------------- | |
8753 | ||
8754 | for r'Size use ??; | |
8755 | for r'Alignment use 4; | |
8756 | for r use record | |
ad42149c | 8757 | x at 4 range 0 .. 7; |
41af791f GB |
8758 | _tag at 0 range 0 .. 31; |
8759 | s at 5 range 0 .. 799; | |
8760 | end record; | |
8761 | ||
8762 | for r2'Size use 160; | |
8763 | for r2'Alignment use 4; | |
8764 | for r2 use record | |
ad42149c | 8765 | x at 4 range 0 .. 7; |
41af791f GB |
8766 | _tag at 0 range 0 .. 31; |
8767 | _parent at 0 range 0 .. 63; | |
8768 | y2 at 16 range 0 .. 31; | |
8769 | end record; | |
8770 | ||
8771 | for x'Size use 8; | |
8772 | for x'Alignment use 1; | |
8773 | for x use record | |
ad42149c | 8774 | y at 0 range 0 .. 7; |
41af791f GB |
8775 | end record; |
8776 | ||
8777 | for x1'Size use 112; | |
8778 | for x1'Alignment use 1; | |
8779 | for x1'Component_Size use 11; | |
8780 | ||
8781 | for rb1'Size use 13; | |
8782 | for rb1'Alignment use 2; | |
8783 | for rb1'Component_Size use 1; | |
8784 | ||
8785 | for rb2'Size use 72; | |
8786 | for rb2'Alignment use 1; | |
8787 | for rb2'Component_Size use 1; | |
8788 | ||
8789 | for x2'Size use 224; | |
8790 | for x2'Alignment use 4; | |
8791 | for x2 use record | |
ad42149c | 8792 | l1 at 0 range 0 .. 0; |
41af791f GB |
8793 | l2 at 0 range 1 .. 64; |
8794 | l3 at 12 range 0 .. 31; | |
ad42149c | 8795 | l4 at 16 range 0 .. 0; |
41af791f GB |
8796 | l5 at 16 range 1 .. 13; |
8797 | l6 at 18 range 0 .. 71; | |
8798 | end record; | |
8799 | @end smallexample | |
8800 | ||
8801 | @noindent | |
46b58b8c | 8802 | The Size values are actually the Object_Size, i.e.@: the default size that |
41af791f GB |
8803 | will be allocated for objects of the type. |
8804 | The ?? size for type r indicates that we have a variant record, and the | |
8805 | actual size of objects will depend on the discriminant value. | |
8806 | ||
8807 | The Alignment values show the actual alignment chosen by the compiler | |
8808 | for each record or array type. | |
8809 | ||
8810 | The record representation clause for type r shows where all fields | |
8811 | are placed, including the compiler generated tag field (whose location | |
8812 | cannot be controlled by the programmer). | |
8813 | ||
8814 | The record representation clause for the type extension r2 shows all the | |
8815 | fields present, including the parent field, which is a copy of the fields | |
46b58b8c | 8816 | of the parent type of r2, i.e.@: r1. |
41af791f GB |
8817 | |
8818 | The component size and size clauses for types rb1 and rb2 show | |
ad42149c FW |
8819 | the exact effect of pragma @code{Pack} on these arrays, and the record |
8820 | representation clause for type x2 shows how pragma @code{Pack} affects | |
41af791f GB |
8821 | this record type. |
8822 | ||
8823 | In some cases, it may be useful to cut and paste the representation clauses | |
8824 | generated by the compiler into the original source to fix and guarantee | |
8825 | the actual representation to be used. | |
8826 | ||
8827 | @node Standard Library Routines | |
8828 | @chapter Standard Library Routines | |
8829 | ||
8830 | @noindent | |
8831 | The Ada 95 Reference Manual contains in Annex A a full description of an | |
8832 | extensive set of standard library routines that can be used in any Ada | |
ad42149c | 8833 | program, and which must be provided by all Ada compilers. They are |
41af791f GB |
8834 | analogous to the standard C library used by C programs. |
8835 | ||
8836 | GNAT implements all of the facilities described in annex A, and for most | |
8837 | purposes the description in the Ada 95 | |
8838 | reference manual, or appropriate Ada | |
8839 | text book, will be sufficient for making use of these facilities. | |
8840 | ||
8841 | In the case of the input-output facilities, @xref{The Implementation of | |
8842 | Standard I/O}, gives details on exactly how GNAT interfaces to the | |
ad42149c FW |
8843 | file system. For the remaining packages, the Ada 95 reference manual |
8844 | should be sufficient. The following is a list of the packages included, | |
41af791f GB |
8845 | together with a brief description of the functionality that is provided. |
8846 | ||
8847 | For completeness, references are included to other predefined library | |
8848 | routines defined in other sections of the Ada 95 reference manual (these are | |
8849 | cross-indexed from annex A). | |
8850 | ||
8851 | @table @code | |
8852 | @item Ada (A.2) | |
ad42149c | 8853 | This is a parent package for all the standard library packages. It is |
41af791f GB |
8854 | usually included implicitly in your program, and itself contains no |
8855 | useful data or routines. | |
8856 | ||
8857 | @item Ada.Calendar (9.6) | |
8858 | @code{Calendar} provides time of day access, and routines for | |
8859 | manipulating times and durations. | |
8860 | ||
8861 | @item Ada.Characters (A.3.1) | |
8862 | This is a dummy parent package that contains no useful entities | |
8863 | ||
8864 | @item Ada.Characters.Handling (A.3.2) | |
8865 | This package provides some basic character handling capabilities, | |
46b58b8c | 8866 | including classification functions for classes of characters (e.g.@: test |
41af791f GB |
8867 | for letters, or digits). |
8868 | ||
8869 | @item Ada.Characters.Latin_1 (A.3.3) | |
8870 | This package includes a complete set of definitions of the characters | |
ad42149c FW |
8871 | that appear in type CHARACTER@. It is useful for writing programs that |
8872 | will run in international environments. For example, if you want an | |
41af791f | 8873 | upper case E with an acute accent in a string, it is often better to use |
ad42149c | 8874 | the definition of @code{UC_E_Acute} in this package. Then your program |
41af791f GB |
8875 | will print in an understandable manner even if your environment does not |
8876 | support these extended characters. | |
8877 | ||
8878 | @item Ada.Command_Line (A.15) | |
8879 | This package provides access to the command line parameters and the name | |
ad42149c | 8880 | of the current program (analogous to the use of @code{argc} and @code{argv} in C), and |
41af791f GB |
8881 | also allows the exit status for the program to be set in a |
8882 | system-independent manner. | |
8883 | ||
8884 | @item Ada.Decimal (F.2) | |
8885 | This package provides constants describing the range of decimal numbers | |
8886 | implemented, and also a decimal divide routine (analogous to the COBOL | |
8887 | verb DIVIDE .. GIVING .. REMAINDER ..) | |
8888 | ||
8889 | @item Ada.Direct_IO (A.8.4) | |
8890 | This package provides input-output using a model of a set of records of | |
8891 | fixed-length, containing an arbitrary definite Ada type, indexed by an | |
8892 | integer record number. | |
8893 | ||
8894 | @item Ada.Dynamic_Priorities (D.5) | |
8895 | This package allows the priorities of a task to be adjusted dynamically | |
8896 | as the task is running. | |
8897 | ||
8898 | @item Ada.Exceptions (11.4.1) | |
8899 | This package provides additional information on exceptions, and also | |
8900 | contains facilities for treating exceptions as data objects, and raising | |
8901 | exceptions with associated messages. | |
8902 | ||
8903 | @item Ada.Finalization (7.6) | |
8904 | This package contains the declarations and subprograms to support the | |
8905 | use of controlled types, providing for automatic initialization and | |
8906 | finalization (analogous to the constructors and destructors of C++) | |
8907 | ||
8908 | @item Ada.Interrupts (C.3.2) | |
8909 | This package provides facilities for interfacing to interrupts, which | |
8910 | includes the set of signals or conditions that can be raised and | |
8911 | recognized as interrupts. | |
8912 | ||
8913 | @item Ada.Interrupts.Names (C.3.2) | |
8914 | This package provides the set of interrupt names (actually signal | |
46b58b8c | 8915 | or condition names) that can be handled by GNAT@. |
41af791f GB |
8916 | |
8917 | @item Ada.IO_Exceptions (A.13) | |
8918 | This package defines the set of exceptions that can be raised by use of | |
8919 | the standard IO packages. | |
8920 | ||
8921 | @item Ada.Numerics | |
8922 | This package contains some standard constants and exceptions used | |
ad42149c | 8923 | throughout the numerics packages. Note that the constants pi and e are |
41af791f GB |
8924 | defined here, and it is better to use these definitions than rolling |
8925 | your own. | |
8926 | ||
8927 | @item Ada.Numerics.Complex_Elementary_Functions | |
8928 | Provides the implementation of standard elementary functions (such as | |
8929 | log and trigonometric functions) operating on complex numbers using the | |
8930 | standard @code{Float} and the @code{Complex} and @code{Imaginary} types | |
8931 | created by the package @code{Numerics.Complex_Types}. | |
8932 | ||
8933 | @item Ada.Numerics.Complex_Types | |
8934 | This is a predefined instantiation of | |
8935 | @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to | |
8936 | build the type @code{Complex} and @code{Imaginary}. | |
8937 | ||
8938 | @item Ada.Numerics.Discrete_Random | |
8939 | This package provides a random number generator suitable for generating | |
8940 | random integer values from a specified range. | |
8941 | ||
8942 | @item Ada.Numerics.Float_Random | |
8943 | This package provides a random number generator suitable for generating | |
8944 | uniformly distributed floating point values. | |
8945 | ||
8946 | @item Ada.Numerics.Generic_Complex_Elementary_Functions | |
8947 | This is a generic version of the package that provides the | |
ad42149c | 8948 | implementation of standard elementary functions (such as log and |
41af791f GB |
8949 | trigonometric functions) for an arbitrary complex type. |
8950 | ||
ad42149c | 8951 | The following predefined instantiations of this package are provided: |
41af791f GB |
8952 | |
8953 | @table @code | |
8954 | @item Short_Float | |
8955 | @code{Ada.Numerics.Short_Complex_Elementary_Functions} | |
8956 | @item Float | |
8957 | @code{Ada.Numerics.Complex_Elementary_Functions} | |
8958 | @item Long_Float | |
8959 | @code{Ada.Numerics. | |
8960 | Long_Complex_Elementary_Functions} | |
8961 | @end table | |
8962 | ||
8963 | @item Ada.Numerics.Generic_Complex_Types | |
8964 | This is a generic package that allows the creation of complex types, | |
8965 | with associated complex arithmetic operations. | |
8966 | ||
8967 | The following predefined instantiations of this package exist | |
8968 | @table @code | |
8969 | @item Short_Float | |
8970 | @code{Ada.Numerics.Short_Complex_Complex_Types} | |
8971 | @item Float | |
8972 | @code{Ada.Numerics.Complex_Complex_Types} | |
8973 | @item Long_Float | |
8974 | @code{Ada.Numerics.Long_Complex_Complex_Types} | |
8975 | @end table | |
8976 | ||
8977 | @item Ada.Numerics.Generic_Elementary_Functions | |
8978 | This is a generic package that provides the implementation of standard | |
8979 | elementary functions (such as log an trigonometric functions) for an | |
8980 | arbitrary float type. | |
8981 | ||
8982 | The following predefined instantiations of this package exist | |
8983 | ||
8984 | @table @code | |
8985 | @item Short_Float | |
8986 | @code{Ada.Numerics.Short_Elementary_Functions} | |
8987 | @item Float | |
8988 | @code{Ada.Numerics.Elementary_Functions} | |
8989 | @item Long_Float | |
8990 | @code{Ada.Numerics.Long_Elementary_Functions} | |
8991 | @end table | |
8992 | ||
8993 | @item Ada.Real_Time (D.8) | |
8994 | This package provides facilities similar to those of @code{Calendar}, but | |
ad42149c FW |
8995 | operating with a finer clock suitable for real time control. Note that |
8996 | annex D requires that there be no backward clock jumps, and GNAT generally | |
8997 | guarantees this behavior, but of course if the external clock on which | |
8998 | the GNAT runtime depends is deliberately reset by some external event, | |
8999 | then such a backward jump may occur. | |
41af791f GB |
9000 | |
9001 | @item Ada.Sequential_IO (A.8.1) | |
9002 | This package provides input-output facilities for sequential files, | |
9003 | which can contain a sequence of values of a single type, which can be | |
9004 | any Ada type, including indefinite (unconstrained) types. | |
9005 | ||
9006 | @item Ada.Storage_IO (A.9) | |
9007 | This package provides a facility for mapping arbitrary Ada types to and | |
ad42149c | 9008 | from a storage buffer. It is primarily intended for the creation of new |
41af791f GB |
9009 | IO packages. |
9010 | ||
9011 | @item Ada.Streams (13.13.1) | |
9012 | This is a generic package that provides the basic support for the | |
9013 | concept of streams as used by the stream attributes (@code{Input}, | |
9014 | @code{Output}, @code{Read} and @code{Write}). | |
9015 | ||
9016 | @item Ada.Streams.Stream_IO (A.12.1) | |
9017 | This package is a specialization of the type @code{Streams} defined in | |
9018 | package @code{Streams} together with a set of operations providing | |
ad42149c | 9019 | Stream_IO capability. The Stream_IO model permits both random and |
41af791f GB |
9020 | sequential access to a file which can contain an arbitrary set of values |
9021 | of one or more Ada types. | |
9022 | ||
9023 | @item Ada.Strings (A.4.1) | |
9024 | This package provides some basic constants used by the string handling | |
9025 | packages. | |
9026 | ||
9027 | @item Ada.Strings.Bounded (A.4.4) | |
9028 | This package provides facilities for handling variable length | |
ad42149c | 9029 | strings. The bounded model requires a maximum length. It is thus |
41af791f GB |
9030 | somewhat more limited than the unbounded model, but avoids the use of |
9031 | dynamic allocation or finalization. | |
9032 | ||
9033 | @item Ada.Strings.Fixed (A.4.3) | |
9034 | This package provides facilities for handling fixed length strings. | |
9035 | ||
9036 | @item Ada.Strings.Maps (A.4.2) | |
9037 | This package provides facilities for handling character mappings and | |
ad42149c | 9038 | arbitrarily defined subsets of characters. For instance it is useful in |
41af791f GB |
9039 | defining specialized translation tables. |
9040 | ||
9041 | @item Ada.Strings.Maps.Constants (A.4.6) | |
9042 | This package provides a standard set of predefined mappings and | |
ad42149c FW |
9043 | predefined character sets. For example, the standard upper to lower case |
9044 | conversion table is found in this package. Note that upper to lower case | |
41af791f GB |
9045 | conversion is non-trivial if you want to take the entire set of |
9046 | characters, including extended characters like E with an acute accent, | |
ad42149c | 9047 | into account. You should use the mappings in this package (rather than |
41af791f GB |
9048 | adding 32 yourself) to do case mappings. |
9049 | ||
9050 | @item Ada.Strings.Unbounded (A.4.5) | |
9051 | This package provides facilities for handling variable length | |
ad42149c | 9052 | strings. The unbounded model allows arbitrary length strings, but |
41af791f GB |
9053 | requires the use of dynamic allocation and finalization. |
9054 | ||
9055 | @item Ada.Strings.Wide_Bounded (A.4.7) | |
9056 | @itemx Ada.Strings.Wide_Fixed (A.4.7) | |
9057 | @itemx Ada.Strings.Wide_Maps (A.4.7) | |
9058 | @itemx Ada.Strings.Wide_Maps.Constants (A.4.7) | |
9059 | @itemx Ada.Strings.Wide_Unbounded (A.4.7) | |
9060 | These package provide analogous capabilities to the corresponding | |
9061 | packages without @samp{Wide_} in the name, but operate with the types | |
9062 | @code{Wide_String} and @code{Wide_Character} instead of @code{String} | |
9063 | and @code{Character}. | |
9064 | ||
9065 | @item Ada.Synchronous_Task_Control (D.10) | |
9066 | This package provides some standard facilities for controlling task | |
9067 | communication in a synchronous manner. | |
9068 | ||
9069 | @item Ada.Tags | |
9070 | This package contains definitions for manipulation of the tags of tagged | |
9071 | values. | |
9072 | ||
9073 | @item Ada.Task_Attributes | |
9074 | This package provides the capability of associating arbitrary | |
9075 | task-specific data with separate tasks. | |
9076 | ||
9077 | @item Ada.Text_IO | |
9078 | This package provides basic text input-output capabilities for | |
ad42149c | 9079 | character, string and numeric data. The subpackages of this |
41af791f GB |
9080 | package are listed next. |
9081 | ||
9082 | @item Ada.Text_IO.Decimal_IO | |
9083 | Provides input-output facilities for decimal fixed-point types | |
9084 | ||
9085 | @item Ada.Text_IO.Enumeration_IO | |
9086 | Provides input-output facilities for enumeration types. | |
9087 | ||
9088 | @item Ada.Text_IO.Fixed_IO | |
9089 | Provides input-output facilities for ordinary fixed-point types. | |
9090 | ||
9091 | @item Ada.Text_IO.Float_IO | |
ad42149c | 9092 | Provides input-output facilities for float types. The following |
41af791f GB |
9093 | predefined instantiations of this generic package are available: |
9094 | ||
9095 | @table @code | |
9096 | @item Short_Float | |
9097 | @code{Short_Float_Text_IO} | |
9098 | @item Float | |
9099 | @code{Float_Text_IO} | |
9100 | @item Long_Float | |
9101 | @code{Long_Float_Text_IO} | |
9102 | @end table | |
9103 | ||
9104 | @item Ada.Text_IO.Integer_IO | |
ad42149c | 9105 | Provides input-output facilities for integer types. The following |
41af791f GB |
9106 | predefined instantiations of this generic package are available: |
9107 | ||
9108 | @table @code | |
9109 | @item Short_Short_Integer | |
9110 | @code{Ada.Short_Short_Integer_Text_IO} | |
9111 | @item Short_Integer | |
9112 | @code{Ada.Short_Integer_Text_IO} | |
9113 | @item Integer | |
9114 | @code{Ada.Integer_Text_IO} | |
9115 | @item Long_Integer | |
9116 | @code{Ada.Long_Integer_Text_IO} | |
9117 | @item Long_Long_Integer | |
9118 | @code{Ada.Long_Long_Integer_Text_IO} | |
9119 | @end table | |
9120 | ||
9121 | @item Ada.Text_IO.Modular_IO | |
9122 | Provides input-output facilities for modular (unsigned) types | |
9123 | ||
9124 | @item Ada.Text_IO.Complex_IO (G.1.3) | |
9125 | This package provides basic text input-output capabilities for complex | |
9126 | data. | |
9127 | ||
9128 | @item Ada.Text_IO.Editing (F.3.3) | |
9129 | This package contains routines for edited output, analogous to the use | |
ad42149c | 9130 | of pictures in COBOL@. The picture formats used by this package are a |
46b58b8c | 9131 | close copy of the facility in COBOL@. |
41af791f GB |
9132 | |
9133 | @item Ada.Text_IO.Text_Streams (A.12.2) | |
9134 | This package provides a facility that allows Text_IO files to be treated | |
9135 | as streams, so that the stream attributes can be used for writing | |
9136 | arbitrary data, including binary data, to Text_IO files. | |
9137 | ||
9138 | @item Ada.Unchecked_Conversion (13.9) | |
9139 | This generic package allows arbitrary conversion from one type to | |
9140 | another of the same size, providing for breaking the type safety in | |
9141 | special circumstances. | |
9142 | ||
9143 | If the types have the same Size (more accurately the same Value_Size), | |
9144 | then the effect is simply to transfer the bits from the source to the | |
ad42149c | 9145 | target type without any modification. This usage is well defined, and |
41af791f GB |
9146 | for simple types whose representation is typically the same across |
9147 | all implementations, gives a portable method of performing such | |
9148 | conversions. | |
9149 | ||
9150 | If the types do not have the same size, then the result is implementation | |
ad42149c | 9151 | defined, and thus may be non-portable. The following describes how GNAT |
41af791f GB |
9152 | handles such unchecked conversion cases. |
9153 | ||
9154 | If the types are of different sizes, and are both discrete types, then | |
9155 | the effect is of a normal type conversion without any constraint checking. | |
9156 | In particular if the result type has a larger size, the result will be | |
ad42149c | 9157 | zero or sign extended. If the result type has a smaller size, the result |
41af791f GB |
9158 | will be truncated by ignoring high order bits. |
9159 | ||
9160 | If the types are of different sizes, and are not both discrete types, | |
9161 | then the conversion works as though pointers were created to the source | |
ad42149c | 9162 | and target, and the pointer value is converted. The effect is that bits |
41af791f GB |
9163 | are copied from successive low order storage units and bits of the source |
9164 | up to the length of the target type. | |
9165 | ||
9166 | A warning is issued if the lengths differ, since the effect in this | |
9167 | case is implementation dependent, and the above behavior may not match | |
9168 | that of some other compiler. | |
9169 | ||
9170 | A pointer to one type may be converted to a pointer to another type using | |
ad42149c FW |
9171 | unchecked conversion. The only case in which the effect is undefined is |
9172 | when one or both pointers are pointers to unconstrained array types. In | |
41af791f GB |
9173 | this case, the bounds information may get incorrectly transferred, and in |
9174 | particular, GNAT uses double size pointers for such types, and it is | |
ad42149c | 9175 | meaningless to convert between such pointer types. GNAT will issue a |
41af791f GB |
9176 | warning if the alignment of the target designated type is more strict |
9177 | than the alignment of the source designated type (since the result may | |
9178 | be unaligned in this case). | |
9179 | ||
9180 | A pointer other than a pointer to an unconstrained array type may be | |
ad42149c | 9181 | converted to and from System.Address. Such usage is common in Ada 83 |
41af791f | 9182 | programs, but note that Ada.Address_To_Access_Conversions is the |
ad42149c | 9183 | preferred method of performing such conversions in Ada 95. Neither |
41af791f GB |
9184 | unchecked conversion nor Ada.Address_To_Access_Conversions should be |
9185 | used in conjunction with pointers to unconstrained objects, since | |
9186 | the bounds information cannot be handled correctly in this case. | |
9187 | ||
9188 | @item Ada.Unchecked_Deallocation (13.11.2) | |
9189 | This generic package allows explicit freeing of storage previously | |
9190 | allocated by use of an allocator. | |
9191 | ||
9192 | @item Ada.Wide_Text_IO (A.11) | |
9193 | This package is similar to @code{Ada.Text_IO}, except that the external | |
9194 | file supports wide character representations, and the internal types are | |
9195 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
ad42149c | 9196 | and @code{String}. It contains generic subpackages listed next. |
41af791f GB |
9197 | |
9198 | @item Ada.Wide_Text_IO.Decimal_IO | |
9199 | Provides input-output facilities for decimal fixed-point types | |
9200 | ||
9201 | @item Ada.Wide_Text_IO.Enumeration_IO | |
9202 | Provides input-output facilities for enumeration types. | |
9203 | ||
9204 | @item Ada.Wide_Text_IO.Fixed_IO | |
9205 | Provides input-output facilities for ordinary fixed-point types. | |
9206 | ||
9207 | @item Ada.Wide_Text_IO.Float_IO | |
ad42149c | 9208 | Provides input-output facilities for float types. The following |
41af791f GB |
9209 | predefined instantiations of this generic package are available: |
9210 | ||
9211 | @table @code | |
9212 | @item Short_Float | |
9213 | @code{Short_Float_Wide_Text_IO} | |
9214 | @item Float | |
9215 | @code{Float_Wide_Text_IO} | |
9216 | @item Long_Float | |
9217 | @code{Long_Float_Wide_Text_IO} | |
9218 | @end table | |
9219 | ||
9220 | @item Ada.Wide_Text_IO.Integer_IO | |
ad42149c | 9221 | Provides input-output facilities for integer types. The following |
41af791f GB |
9222 | predefined instantiations of this generic package are available: |
9223 | ||
9224 | @table @code | |
9225 | @item Short_Short_Integer | |
9226 | @code{Ada.Short_Short_Integer_Wide_Text_IO} | |
9227 | @item Short_Integer | |
9228 | @code{Ada.Short_Integer_Wide_Text_IO} | |
9229 | @item Integer | |
9230 | @code{Ada.Integer_Wide_Text_IO} | |
9231 | @item Long_Integer | |
9232 | @code{Ada.Long_Integer_Wide_Text_IO} | |
9233 | @item Long_Long_Integer | |
9234 | @code{Ada.Long_Long_Integer_Wide_Text_IO} | |
9235 | @end table | |
9236 | ||
9237 | @item Ada.Wide_Text_IO.Modular_IO | |
9238 | Provides input-output facilities for modular (unsigned) types | |
9239 | ||
9240 | @item Ada.Wide_Text_IO.Complex_IO (G.1.3) | |
9241 | This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the | |
9242 | external file supports wide character representations. | |
9243 | ||
9244 | @item Ada.Wide_Text_IO.Editing (F.3.4) | |
9245 | This package is similar to @code{Ada.Text_IO.Editing}, except that the | |
9246 | types are @code{Wide_Character} and @code{Wide_String} instead of | |
9247 | @code{Character} and @code{String}. | |
9248 | ||
9249 | @item Ada.Wide_Text_IO.Streams (A.12.3) | |
9250 | This package is similar to @code{Ada.Text_IO.Streams}, except that the | |
9251 | types are @code{Wide_Character} and @code{Wide_String} instead of | |
9252 | @code{Character} and @code{String}. | |
9253 | @end table | |
9254 | @node The Implementation of Standard I/O | |
9255 | @chapter The Implementation of Standard I/O | |
9256 | ||
9257 | @noindent | |
9258 | GNAT implements all the required input-output facilities described in | |
ad42149c | 9259 | A.6 through A.14. These sections of the Ada 95 reference manual describe the |
41af791f GB |
9260 | required behavior of these packages from the Ada point of view, and if |
9261 | you are writing a portable Ada program that does not need to know the | |
9262 | exact manner in which Ada maps to the outside world when it comes to | |
9263 | reading or writing external files, then you do not need to read this | |
ad42149c | 9264 | chapter. As long as your files are all regular files (not pipes or |
41af791f GB |
9265 | devices), and as long as you write and read the files only from Ada, the |
9266 | description in the Ada 95 reference manual is sufficient. | |
9267 | ||
9268 | However, if you want to do input-output to pipes or other devices, such | |
9269 | as the keyboard or screen, or if the files you are dealing with are | |
9270 | either generated by some other language, or to be read by some other | |
9271 | language, then you need to know more about the details of how the GNAT | |
9272 | implementation of these input-output facilities behaves. | |
9273 | ||
9274 | In this chapter we give a detailed description of exactly how GNAT | |
ad42149c | 9275 | interfaces to the file system. As always, the sources of the system are |
41af791f GB |
9276 | available to you for answering questions at an even more detailed level, |
9277 | but for most purposes the information in this chapter will suffice. | |
9278 | ||
9279 | Another reason that you may need to know more about how input-output is | |
9280 | implemented arises when you have a program written in mixed languages | |
9281 | where, for example, files are shared between the C and Ada sections of | |
ad42149c | 9282 | the same program. GNAT provides some additional facilities, in the form |
41af791f GB |
9283 | of additional child library packages, that facilitate this sharing, and |
9284 | these additional facilities are also described in this chapter. | |
9285 | ||
9286 | @menu | |
9287 | * Standard I/O Packages:: | |
9288 | * FORM Strings:: | |
9289 | * Direct_IO:: | |
9290 | * Sequential_IO:: | |
9291 | * Text_IO:: | |
9292 | * Wide_Text_IO:: | |
9293 | * Stream_IO:: | |
9294 | * Shared Files:: | |
9295 | * Open Modes:: | |
9296 | * Operations on C Streams:: | |
9297 | * Interfacing to C Streams:: | |
9298 | @end menu | |
9299 | ||
9300 | @node Standard I/O Packages | |
9301 | @section Standard I/O Packages | |
9302 | ||
9303 | @noindent | |
9304 | The Standard I/O packages described in Annex A for | |
9305 | ||
9306 | @itemize @bullet | |
9307 | @item | |
9308 | Ada.Text_IO | |
9309 | @item | |
9310 | Ada.Text_IO.Complex_IO | |
9311 | @item | |
9312 | Ada.Text_IO.Text_Streams, | |
9313 | @item | |
9314 | Ada.Wide_Text_IO | |
9315 | @item | |
9316 | Ada.Wide_Text_IO.Complex_IO, | |
9317 | @item | |
9318 | Ada.Wide_Text_IO.Text_Streams | |
9319 | @item | |
9320 | Ada.Stream_IO | |
9321 | @item | |
9322 | Ada.Sequential_IO | |
9323 | @item | |
9324 | Ada.Direct_IO | |
9325 | @end itemize | |
9326 | ||
9327 | @noindent | |
9328 | are implemented using the C | |
9329 | library streams facility; where | |
9330 | ||
9331 | @itemize @bullet | |
9332 | @item | |
9333 | All files are opened using @code{fopen}. | |
9334 | @item | |
9335 | All input/output operations use @code{fread}/@code{fwrite}. | |
9336 | @end itemize | |
9337 | ||
ad42149c | 9338 | There is no internal buffering of any kind at the Ada library level. The |
41af791f | 9339 | only buffering is that provided at the system level in the |
ad42149c | 9340 | implementation of the C library routines that support streams. This |
41af791f GB |
9341 | facilitates shared use of these streams by mixed language programs. |
9342 | ||
9343 | @node FORM Strings | |
9344 | @section FORM Strings | |
9345 | ||
9346 | @noindent | |
9347 | The format of a FORM string in GNAT is: | |
9348 | ||
9349 | @smallexample | |
ad42149c | 9350 | "keyword=value,keyword=value,@dots{},keyword=value" |
41af791f GB |
9351 | @end smallexample |
9352 | ||
9353 | @noindent | |
9354 | where letters may be in upper or lower case, and there are no spaces | |
ad42149c | 9355 | between values. The order of the entries is not important. Currently |
41af791f GB |
9356 | there are two keywords defined. |
9357 | ||
9358 | @smallexample | |
9359 | SHARED=[YES|NO] | |
9360 | WCEM=[n|h|u|s\e] | |
9361 | @end smallexample | |
9362 | ||
9363 | The use of these parameters is described later in this section. | |
9364 | ||
9365 | @node Direct_IO | |
9366 | @section Direct_IO | |
9367 | ||
9368 | @noindent | |
ad42149c | 9369 | Direct_IO can only be instantiated for definite types. This is a |
41af791f GB |
9370 | restriction of the Ada language, which means that the records are fixed |
9371 | length (the length being determined by @code{@var{type}'Size}, rounded | |
9372 | up to the next storage unit boundary if necessary). | |
9373 | ||
9374 | The records of a Direct_IO file are simply written to the file in index | |
9375 | sequence, with the first record starting at offset zero, and subsequent | |
ad42149c | 9376 | records following. There is no control information of any kind. For |
41af791f | 9377 | example, if 32-bit integers are being written, each record takes |
ad42149c FW |
9378 | 4-bytes, so the record at index @var{K} starts at offset |
9379 | (@var{K}@minus{}1)*4. | |
41af791f GB |
9380 | |
9381 | There is no limit on the size of Direct_IO files, they are expanded as | |
9382 | necessary to accommodate whatever records are written to the file. | |
9383 | ||
9384 | @node Sequential_IO | |
9385 | @section Sequential_IO | |
9386 | ||
9387 | @noindent | |
9388 | Sequential_IO may be instantiated with either a definite (constrained) | |
9389 | or indefinite (unconstrained) type. | |
9390 | ||
9391 | For the definite type case, the elements written to the file are simply | |
9392 | the memory images of the data values with no control information of any | |
ad42149c | 9393 | kind. The resulting file should be read using the same type, no validity |
41af791f GB |
9394 | checking is performed on input. |
9395 | ||
9396 | For the indefinite type case, the elements written consist of two | |
ad42149c | 9397 | parts. First is the size of the data item, written as the memory image |
41af791f | 9398 | of a @code{Interfaces.C.size_t} value, followed by the memory image of |
ad42149c FW |
9399 | the data value. The resulting file can only be read using the same |
9400 | (unconstrained) type. Normal assignment checks are performed on these | |
41af791f | 9401 | read operations, and if these checks fail, @code{Data_Error} is |
ad42149c | 9402 | raised. In particular, in the array case, the lengths must match, and in |
41af791f GB |
9403 | the variant record case, if the variable for a particular read operation |
9404 | is constrained, the discriminants must match. | |
9405 | ||
9406 | Note that it is not possible to use Sequential_IO to write variable | |
9407 | length array items, and then read the data back into different length | |
ad42149c | 9408 | arrays. For example, the following will raise @code{Data_Error}: |
41af791f GB |
9409 | |
9410 | @smallexample | |
9411 | package IO is new Sequential_IO (String); | |
9412 | F : IO.File_Type; | |
9413 | S : String (1..4); | |
ad42149c | 9414 | @dots{} |
41af791f GB |
9415 | IO.Create (F) |
9416 | IO.Write (F, "hello!") | |
9417 | IO.Reset (F, Mode=>In_File); | |
9418 | IO.Read (F, S); | |
9419 | Put_Line (S); | |
9420 | ||
9421 | @end smallexample | |
9422 | ||
9423 | On some Ada implementations, this will print @samp{hell}, but the program is | |
9424 | clearly incorrect, since there is only one element in the file, and that | |
9425 | element is the string @samp{hello!}. | |
9426 | ||
9427 | In Ada 95, this kind of behavior can be legitimately achieved using | |
ad42149c | 9428 | Stream_IO, and this is the preferred mechanism. In particular, the above |
41af791f GB |
9429 | program fragment rewritten to use Stream_IO will work correctly. |
9430 | ||
9431 | @node Text_IO | |
9432 | @section Text_IO | |
9433 | ||
9434 | @noindent | |
9435 | Text_IO files consist of a stream of characters containing the following | |
9436 | special control characters: | |
9437 | ||
9438 | @smallexample | |
9439 | LF (line feed, 16#0A#) Line Mark | |
9440 | FF (form feed, 16#0C#) Page Mark | |
9441 | @end smallexample | |
9442 | ||
9443 | A canonical Text_IO file is defined as one in which the following | |
9444 | conditions are met: | |
9445 | ||
9446 | @itemize @bullet | |
9447 | @item | |
46b58b8c | 9448 | The character @code{LF} is used only as a line mark, i.e.@: to mark the end |
41af791f GB |
9449 | of the line. |
9450 | ||
9451 | @item | |
46b58b8c | 9452 | The character @code{FF} is used only as a page mark, i.e.@: to mark the |
41af791f GB |
9453 | end of a page and consequently can appear only immediately following a |
9454 | @code{LF} (line mark) character. | |
9455 | ||
9456 | @item | |
9457 | The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} | |
ad42149c | 9458 | (line mark, page mark). In the former case, the page mark is implicitly |
41af791f GB |
9459 | assumed to be present. |
9460 | @end itemize | |
9461 | ||
9462 | A file written using Text_IO will be in canonical form provided that no | |
9463 | explicit @code{LF} or @code{FF} characters are written using @code{Put} | |
ad42149c | 9464 | or @code{Put_Line}. There will be no @code{FF} character at the end of |
41af791f GB |
9465 | the file unless an explicit @code{New_Page} operation was performed |
9466 | before closing the file. | |
9467 | ||
46b58b8c | 9468 | A canonical Text_IO file that is a regular file, i.e.@: not a device or a |
ad42149c | 9469 | pipe, can be read using any of the routines in Text_IO@. The |
41af791f GB |
9470 | semantics in this case will be exactly as defined in the Ada 95 reference |
9471 | manual and all the routines in Text_IO are fully implemented. | |
9472 | ||
9473 | A text file that does not meet the requirements for a canonical Text_IO | |
9474 | file has one of the following: | |
9475 | ||
9476 | @itemize @bullet | |
9477 | @item | |
9478 | The file contains @code{FF} characters not immediately following a | |
9479 | @code{LF} character. | |
9480 | ||
9481 | @item | |
9482 | The file contains @code{LF} or @code{FF} characters written by | |
9483 | @code{Put} or @code{Put_Line}, which are not logically considered to be | |
9484 | line marks or page marks. | |
9485 | ||
9486 | @item | |
9487 | The file ends in a character other than @code{LF} or @code{FF}, | |
46b58b8c | 9488 | i.e.@: there is no explicit line mark or page mark at the end of the file. |
41af791f GB |
9489 | @end itemize |
9490 | ||
9491 | Text_IO can be used to read such non-standard text files but subprograms | |
ad42149c | 9492 | to do with line or page numbers do not have defined meanings. In |
41af791f GB |
9493 | particular, a @code{FF} character that does not follow a @code{LF} |
9494 | character may or may not be treated as a page mark from the point of | |
ad42149c | 9495 | view of page and line numbering. Every @code{LF} character is considered |
41af791f GB |
9496 | to end a line, and there is an implied @code{LF} character at the end of |
9497 | the file. | |
9498 | ||
9499 | @menu | |
9500 | * Text_IO Stream Pointer Positioning:: | |
9501 | * Text_IO Reading and Writing Non-Regular Files:: | |
9502 | * Get_Immediate:: | |
9503 | * Treating Text_IO Files as Streams:: | |
9504 | * Text_IO Extensions:: | |
9505 | * Text_IO Facilities for Unbounded Strings:: | |
9506 | @end menu | |
9507 | @node Text_IO Stream Pointer Positioning | |
9508 | ||
9509 | @subsection Stream Pointer Positioning | |
9510 | ||
9511 | @noindent | |
9512 | @code{Ada.Text_IO} has a definition of current position for a file that | |
ad42149c | 9513 | is being read. No internal buffering occurs in Text_IO, and usually the |
41af791f | 9514 | physical position in the stream used to implement the file corresponds |
ad42149c | 9515 | to this logical position defined by Text_IO@. There are two exceptions: |
41af791f GB |
9516 | |
9517 | @itemize @bullet | |
9518 | @item | |
9519 | After a call to @code{End_Of_Page} that returns @code{True}, the stream | |
9520 | is positioned past the @code{LF} (line mark) that precedes the page | |
ad42149c | 9521 | mark. Text_IO maintains an internal flag so that subsequent read |
41af791f GB |
9522 | operations properly handle the logical position which is unchanged by |
9523 | the @code{End_Of_Page} call. | |
9524 | ||
9525 | @item | |
9526 | After a call to @code{End_Of_File} that returns @code{True}, if the | |
9527 | Text_IO file was positioned before the line mark at the end of file | |
9528 | before the call, then the logical position is unchanged, but the stream | |
9529 | is physically positioned right at the end of file (past the line mark, | |
ad42149c | 9530 | and past a possible page mark following the line mark. Again Text_IO |
41af791f GB |
9531 | maintains internal flags so that subsequent read operations properly |
9532 | handle the logical position. | |
9533 | @end itemize | |
9534 | ||
9535 | These discrepancies have no effect on the observable behavior of | |
9536 | Text_IO, but if a single Ada stream is shared between a C program and | |
9537 | Ada program, or shared (using @samp{shared=yes} in the form string) | |
9538 | between two Ada files, then the difference may be observable in some | |
9539 | situations. | |
9540 | ||
9541 | @node Text_IO Reading and Writing Non-Regular Files | |
9542 | @subsection Reading and Writing Non-Regular Files | |
9543 | ||
9544 | @noindent | |
ad42149c FW |
9545 | A non-regular file is a device (such as a keyboard), or a pipe. Text_IO |
9546 | can be used for reading and writing. Writing is not affected and the | |
41af791f GB |
9547 | sequence of characters output is identical to the normal file case, but |
9548 | for reading, the behavior of Text_IO is modified to avoid undesirable | |
9549 | look-ahead as follows: | |
9550 | ||
9551 | An input file that is not a regular file is considered to have no page | |
ad42149c | 9552 | marks. Any @code{Ascii.FF} characters (the character normally used for a |
41af791f | 9553 | page mark) appearing in the file are considered to be data |
ad42149c | 9554 | characters. In particular: |
41af791f GB |
9555 | |
9556 | @itemize @bullet | |
9557 | @item | |
9558 | @code{Get_Line} and @code{Skip_Line} do not test for a page mark | |
ad42149c | 9559 | following a line mark. If a page mark appears, it will be treated as a |
41af791f GB |
9560 | data character. |
9561 | ||
9562 | @item | |
9563 | This avoids the need to wait for an extra character to be typed or | |
9564 | entered from the pipe to complete one of these operations. | |
9565 | ||
9566 | @item | |
9567 | @code{End_Of_Page} always returns @code{False} | |
9568 | ||
9569 | @item | |
9570 | @code{End_Of_File} will return @code{False} if there is a page mark at | |
9571 | the end of the file. | |
9572 | @end itemize | |
9573 | ||
ad42149c | 9574 | Output to non-regular files is the same as for regular files. Page marks |
41af791f GB |
9575 | may be written to non-regular files using @code{New_Page}, but as noted |
9576 | above they will not be treated as page marks on input if the output is | |
9577 | piped to another Ada program. | |
9578 | ||
9579 | Another important discrepancy when reading non-regular files is that the end | |
ad42149c FW |
9580 | of file indication is not ``sticky''. If an end of file is entered, e.g.@: by |
9581 | pressing the @key{EOT} key, | |
41af791f | 9582 | then end of file |
46b58b8c | 9583 | is signalled once (i.e.@: the test @code{End_Of_File} |
41af791f GB |
9584 | will yield @code{True}, or a read will |
9585 | raise @code{End_Error}), but then reading can resume | |
9586 | to read data past that end of | |
9587 | file indication, until another end of file indication is entered. | |
9588 | ||
9589 | @node Get_Immediate | |
9590 | @subsection Get_Immediate | |
9591 | @cindex Get_Immediate | |
9592 | ||
9593 | @noindent | |
9594 | Get_Immediate returns the next character (including control characters) | |
ad42149c FW |
9595 | from the input file. In particular, Get_Immediate will return LF or FF |
9596 | characters used as line marks or page marks. Such operations leave the | |
41af791f | 9597 | file positioned past the control character, and it is thus not treated |
ad42149c | 9598 | as having its normal function. This means that page, line and column |
41af791f | 9599 | counts after this kind of Get_Immediate call are set as though the mark |
ad42149c | 9600 | did not occur. In the case where a Get_Immediate leaves the file |
41af791f GB |
9601 | positioned between the line mark and page mark (which is not normally |
9602 | possible), it is undefined whether the FF character will be treated as a | |
9603 | page mark. | |
9604 | ||
9605 | @node Treating Text_IO Files as Streams | |
9606 | @subsection Treating Text_IO Files as Streams | |
9607 | @cindex Stream files | |
9608 | ||
9609 | @noindent | |
9610 | The package @code{Text_IO.Streams} allows a Text_IO file to be treated | |
ad42149c FW |
9611 | as a stream. Data written to a Text_IO file in this stream mode is |
9612 | binary data. If this binary data contains bytes 16#0A# (@code{LF}) or | |
41af791f | 9613 | 16#0C# (@code{FF}), the resulting file may have non-standard |
ad42149c | 9614 | format. Similarly if read operations are used to read from a Text_IO |
41af791f GB |
9615 | file treated as a stream, then @code{LF} and @code{FF} characters may be |
9616 | skipped and the effect is similar to that described above for | |
9617 | @code{Get_Immediate}. | |
9618 | ||
9619 | @node Text_IO Extensions | |
9620 | @subsection Text_IO Extensions | |
9621 | @cindex Text_IO extensions | |
9622 | ||
9623 | @noindent | |
9624 | A package GNAT.IO_Aux in the GNAT library provides some useful extensions | |
9625 | to the standard @code{Text_IO} package: | |
9626 | ||
9627 | @itemize @bullet | |
9628 | @item function File_Exists (Name : String) return Boolean; | |
9629 | Determines if a file of the given name exists and can be successfully | |
9630 | opened (without actually performing the open operation). | |
9631 | ||
9632 | @item function Get_Line return String; | |
ad42149c | 9633 | Reads a string from the standard input file. The value returned is exactly |
41af791f GB |
9634 | the length of the line that was read. |
9635 | ||
9636 | @item function Get_Line (File : Ada.Text_IO.File_Type) return String; | |
9637 | Similar, except that the parameter File specifies the file from which | |
9638 | the string is to be read. | |
9639 | ||
9640 | @end itemize | |
9641 | ||
9642 | @node Text_IO Facilities for Unbounded Strings | |
9643 | @subsection Text_IO Facilities for Unbounded Strings | |
9644 | @cindex Text_IO for unbounded strings | |
9645 | @cindex Unbounded_String, Text_IO operations | |
9646 | ||
9647 | @noindent | |
9648 | The package @code{Ada.Strings.Unbounded.Text_IO} | |
9649 | in library files @code{a-suteio.ads/adb} contains some GNAT-specific | |
9650 | subprograms useful for Text_IO operations on unbounded strings: | |
9651 | ||
9652 | @itemize @bullet | |
9653 | ||
9654 | @item function Get_Line (File : File_Type) return Unbounded_String; | |
9655 | Reads a line from the specified file | |
9656 | and returns the result as an unbounded string. | |
9657 | ||
9658 | @item procedure Put (File : File_Type; U : Unbounded_String); | |
9659 | Writes the value of the given unbounded string to the specified file | |
9660 | Similar to the effect of | |
9661 | @code{Put (To_String (U))} except that an extra copy is avoided. | |
9662 | ||
9663 | @item procedure Put_Line (File : File_Type; U : Unbounded_String); | |
9664 | Writes the value of the given unbounded string to the specified file, | |
9665 | followed by a @code{New_Line}. | |
9666 | Similar to the effect of @code{Put_Line (To_String (U))} except | |
9667 | that an extra copy is avoided. | |
9668 | @end itemize | |
9669 | ||
9670 | @noindent | |
9671 | In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} | |
ad42149c | 9672 | and is optional. If the parameter is omitted, then the standard input or |
41af791f GB |
9673 | output file is referenced as appropriate. |
9674 | ||
9675 | The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library | |
ad42149c | 9676 | files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended @code{Wide_Text_IO} |
41af791f GB |
9677 | functionality for unbounded wide strings. |
9678 | ||
9679 | @node Wide_Text_IO | |
9680 | @section Wide_Text_IO | |
9681 | ||
9682 | @noindent | |
9683 | @code{Wide_Text_IO} is similar in most respects to Text_IO, except that | |
9684 | both input and output files may contain special sequences that represent | |
ad42149c | 9685 | wide character values. The encoding scheme for a given file may be |
41af791f GB |
9686 | specified using a FORM parameter: |
9687 | ||
9688 | @smallexample | |
9689 | WCEM=@var{x} | |
9690 | @end smallexample | |
9691 | ||
9692 | @noindent | |
9693 | as part of the FORM string (WCEM = wide character encoding method), | |
9694 | where @var{x} is one of the following characters | |
9695 | ||
9696 | @table @samp | |
9697 | @item h | |
9698 | Hex ESC encoding | |
9699 | @item u | |
9700 | Upper half encoding | |
9701 | @item s | |
9702 | Shift-JIS encoding | |
9703 | @item e | |
9704 | EUC Encoding | |
9705 | @item 8 | |
9706 | UTF-8 encoding | |
9707 | @item b | |
9708 | Brackets encoding | |
9709 | @end table | |
9710 | ||
9711 | The encoding methods match those that | |
9712 | can be used in a source | |
9713 | program, but there is no requirement that the encoding method used for | |
9714 | the source program be the same as the encoding method used for files, | |
9715 | and different files may use different encoding methods. | |
9716 | ||
9717 | The default encoding method for the standard files, and for opened files | |
9718 | for which no WCEM parameter is given in the FORM string matches the | |
9719 | wide character encoding specified for the main program (the default | |
9720 | being brackets encoding if no coding method was specified with -gnatW). | |
9721 | ||
9722 | @table @asis | |
9723 | @item Hex Coding | |
9724 | In this encoding, a wide character is represented by a five character | |
9725 | sequence: | |
9726 | ||
9727 | @smallexample | |
9728 | ESC a b c d | |
9729 | @end smallexample | |
9730 | ||
9731 | where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal | |
ad42149c | 9732 | characters (using upper case letters) of the wide character code. For |
41af791f | 9733 | example, ESC A345 is used to represent the wide character with code |
ad42149c | 9734 | 16#A345#. This scheme is compatible with use of the full |
41af791f GB |
9735 | @code{Wide_Character} set. |
9736 | ||
9737 | @item Upper Half Coding | |
9738 | The wide character with encoding 16#abcd#, where the upper bit is on | |
46b58b8c | 9739 | (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and |
ad42149c FW |
9740 | 16#cd#. The second byte may never be a format control character, but is |
9741 | not required to be in the upper half. This method can be also used for | |
41af791f GB |
9742 | shift-JIS or EUC where the internal coding matches the external coding. |
9743 | ||
9744 | @item Shift JIS Coding | |
9745 | A wide character is represented by a two character sequence 16#ab# and | |
9746 | 16#cd#, with the restrictions described for upper half encoding as | |
ad42149c | 9747 | described above. The internal character code is the corresponding JIS |
41af791f | 9748 | character according to the standard algorithm for Shift-JIS |
ad42149c | 9749 | conversion. Only characters defined in the JIS code set table can be |
41af791f GB |
9750 | used with this encoding method. |
9751 | ||
9752 | @item EUC Coding | |
9753 | A wide character is represented by a two character sequence 16#ab# and | |
ad42149c | 9754 | 16#cd#, with both characters being in the upper half. The internal |
41af791f | 9755 | character code is the corresponding JIS character according to the EUC |
ad42149c | 9756 | encoding algorithm. Only characters defined in the JIS code set table |
41af791f GB |
9757 | can be used with this encoding method. |
9758 | ||
9759 | @item UTF-8 Coding | |
9760 | A wide character is represented using | |
9761 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
9762 | 10646-1/Am.2. Depending on the character value, the representation | |
9763 | is a one, two, or three byte sequence: | |
9764 | ||
9765 | @smallexample | |
9766 | 16#0000#-16#007f#: 2#0xxxxxxx# | |
9767 | 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# | |
9768 | 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
9769 | @end smallexample | |
9770 | ||
9771 | where the xxx bits correspond to the left-padded bits of the | |
ad42149c | 9772 | 16-bit character value. Note that all lower half ASCII characters |
41af791f GB |
9773 | are represented as ASCII bytes and all upper half characters and |
9774 | other wide characters are represented as sequences of upper-half | |
9775 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
9776 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
9777 | of four or more bytes length will raise a Constraint_Error, as | |
ad42149c | 9778 | will all invalid UTF-8 sequences.) |
41af791f GB |
9779 | |
9780 | @item Brackets Coding | |
9781 | In this encoding, a wide character is represented by the following eight | |
9782 | character sequence: | |
9783 | ||
9784 | @smallexample | |
9785 | [ " a b c d " ] | |
9786 | @end smallexample | |
9787 | ||
9788 | Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
ad42149c | 9789 | characters (using uppercase letters) of the wide character code. For |
41af791f GB |
9790 | example, @code{["A345"]} is used to represent the wide character with code |
9791 | @code{16#A345#}. | |
9792 | This scheme is compatible with use of the full Wide_Character set. | |
9793 | On input, brackets coding can also be used for upper half characters, | |
ad42149c | 9794 | e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation |
41af791f GB |
9795 | is only used for wide characters with a code greater than @code{16#FF#}. |
9796 | ||
9797 | @end table | |
9798 | ||
9799 | For the coding schemes other than Hex and Brackets encoding, | |
9800 | not all wide character | |
ad42149c | 9801 | values can be represented. An attempt to output a character that cannot |
41af791f | 9802 | be represented using the encoding scheme for the file causes |
ad42149c | 9803 | Constraint_Error to be raised. An invalid wide character sequence on |
41af791f GB |
9804 | input also causes Constraint_Error to be raised. |
9805 | ||
9806 | @menu | |
9807 | * Wide_Text_IO Stream Pointer Positioning:: | |
9808 | * Wide_Text_IO Reading and Writing Non-Regular Files:: | |
9809 | @end menu | |
9810 | ||
9811 | @node Wide_Text_IO Stream Pointer Positioning | |
9812 | @subsection Stream Pointer Positioning | |
9813 | ||
9814 | @noindent | |
9815 | @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
ad42149c | 9816 | of stream pointer positioning (@pxref{Text_IO}). There is one additional |
41af791f GB |
9817 | case: |
9818 | ||
9819 | If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the | |
46b58b8c | 9820 | normal lower ASCII set (i.e.@: a character in the range: |
41af791f GB |
9821 | |
9822 | @smallexample | |
9823 | Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) | |
9824 | @end smallexample | |
9825 | ||
9826 | @noindent | |
9827 | then although the logical position of the file pointer is unchanged by | |
9828 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
ad42149c | 9829 | wide character sequence. Again this is to avoid the need for buffering |
41af791f GB |
9830 | or backup, and all @code{Wide_Text_IO} routines check the internal |
9831 | indication that this situation has occurred so that this is not visible | |
ad42149c | 9832 | to a normal program using @code{Wide_Text_IO}. However, this discrepancy |
41af791f GB |
9833 | can be observed if the wide text file shares a stream with another file. |
9834 | ||
9835 | @node Wide_Text_IO Reading and Writing Non-Regular Files | |
9836 | @subsection Reading and Writing Non-Regular Files | |
9837 | ||
9838 | @noindent | |
9839 | As in the case of Text_IO, when a non-regular file is read, it is | |
9840 | assumed that the file contains no page marks (any form characters are | |
9841 | treated as data characters), and @code{End_Of_Page} always returns | |
ad42149c | 9842 | @code{False}. Similarly, the end of file indication is not sticky, so |
41af791f GB |
9843 | it is possible to read beyond an end of file. |
9844 | ||
9845 | @node Stream_IO | |
9846 | @section Stream_IO | |
9847 | ||
9848 | @noindent | |
9849 | A stream file is a sequence of bytes, where individual elements are | |
ad42149c FW |
9850 | written to the file as described in the Ada 95 reference manual. The type |
9851 | @code{Stream_Element} is simply a byte. There are two ways to read or | |
41af791f GB |
9852 | write a stream file. |
9853 | ||
9854 | @itemize @bullet | |
9855 | @item | |
9856 | The operations @code{Read} and @code{Write} directly read or write a | |
9857 | sequence of stream elements with no control information. | |
9858 | ||
9859 | @item | |
9860 | The stream attributes applied to a stream file transfer data in the | |
9861 | manner described for stream attributes. | |
9862 | @end itemize | |
9863 | ||
9864 | @node Shared Files | |
9865 | @section Shared Files | |
9866 | ||
9867 | @noindent | |
9868 | Section A.14 of the Ada 95 Reference Manual allows implementations to | |
9869 | provide a wide variety of behavior if an attempt is made to access the | |
9870 | same external file with two or more internal files. | |
9871 | ||
9872 | To provide a full range of functionality, while at the same time | |
9873 | minimizing the problems of portability caused by this implementation | |
9874 | dependence, GNAT handles file sharing as follows: | |
9875 | ||
9876 | @itemize @bullet | |
9877 | @item | |
9878 | In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt | |
9879 | to open two or more files with the same full name is considered an error | |
ad42149c FW |
9880 | and is not supported. The exception @code{Use_Error} will be |
9881 | raised. Note that a file that is not explicitly closed by the program | |
41af791f GB |
9882 | remains open until the program terminates. |
9883 | ||
9884 | @item | |
9885 | If the form parameter @samp{shared=no} appears in the form string, the | |
9886 | file can be opened or created with its own separate stream identifier, | |
9887 | regardless of whether other files sharing the same external file are | |
ad42149c | 9888 | opened. The exact effect depends on how the C stream routines handle |
41af791f GB |
9889 | multiple accesses to the same external files using separate streams. |
9890 | ||
9891 | @item | |
9892 | If the form parameter @samp{shared=yes} appears in the form string for | |
9893 | each of two or more files opened using the same full name, the same | |
9894 | stream is shared between these files, and the semantics are as described | |
9895 | in Ada 95 Reference Manual, Section A.14. | |
9896 | @end itemize | |
9897 | ||
9898 | When a program that opens multiple files with the same name is ported | |
9899 | from another Ada compiler to GNAT, the effect will be that | |
9900 | @code{Use_Error} is raised. | |
9901 | ||
9902 | The documentation of the original compiler and the documentation of the | |
9903 | program should then be examined to determine if file sharing was | |
9904 | expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} | |
9905 | and @code{Create} calls as required. | |
9906 | ||
9907 | When a program is ported from GNAT to some other Ada compiler, no | |
9908 | special attention is required unless the @samp{shared=@var{xxx}} form | |
ad42149c | 9909 | parameter is used in the program. In this case, you must examine the |
41af791f | 9910 | documentation of the new compiler to see if it supports the required |
ad42149c | 9911 | file sharing semantics, and form strings modified appropriately. Of |
41af791f | 9912 | course it may be the case that the program cannot be ported if the |
ad42149c | 9913 | target compiler does not support the required functionality. The best |
41af791f GB |
9914 | approach in writing portable code is to avoid file sharing (and hence |
9915 | the use of the @samp{shared=@var{xxx}} parameter in the form string) | |
9916 | completely. | |
9917 | ||
9918 | One common use of file sharing in Ada 83 is the use of instantiations of | |
9919 | Sequential_IO on the same file with different types, to achieve | |
ad42149c | 9920 | heterogeneous input-output. Although this approach will work in GNAT if |
41af791f GB |
9921 | @samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO |
9922 | for this purpose (using the stream attributes) | |
9923 | ||
9924 | @node Open Modes | |
9925 | @section Open Modes | |
9926 | ||
9927 | @noindent | |
9928 | @code{Open} and @code{Create} calls result in a call to @code{fopen} | |
9929 | using the mode shown in Table 6.1 | |
9930 | ||
9931 | @sp 2 | |
9932 | @center Table 6-1 @code{Open} and @code{Create} Call Modes | |
9933 | @smallexample | |
9934 | @b{OPEN } @b{CREATE} | |
9935 | Append_File "r+" "w+" | |
9936 | In_File "r" "w+" | |
9937 | Out_File (Direct_IO) "r+" "w" | |
9938 | Out_File (all other cases) "w" "w" | |
9939 | Inout_File "r+" "w+" | |
9940 | @end smallexample | |
9941 | ||
9942 | If text file translation is required, then either @samp{b} or @samp{t} | |
ad42149c | 9943 | is added to the mode, depending on the setting of Text. Text file |
41af791f | 9944 | translation refers to the mapping of CR/LF sequences in an external file |
ad42149c | 9945 | to LF characters internally. This mapping only occurs in DOS and |
41af791f GB |
9946 | DOS-like systems, and is not relevant to other systems. |
9947 | ||
ad42149c | 9948 | A special case occurs with Stream_IO@. As shown in the above table, the |
41af791f | 9949 | file is initially opened in @samp{r} or @samp{w} mode for the |
ad42149c | 9950 | @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation |
41af791f GB |
9951 | subsequently requires switching from reading to writing or vice-versa, |
9952 | then the file is reopened in @samp{r+} mode to permit the required operation. | |
9953 | ||
9954 | @node Operations on C Streams | |
9955 | @section Operations on C Streams | |
9956 | The package @code{Interfaces.C_Streams} provides an Ada program with direct | |
9957 | access to the C library functions for operations on C streams: | |
9958 | ||
9959 | @smallexample | |
9960 | package Interfaces.C_Streams is | |
9961 | -- Note: the reason we do not use the types that are in | |
9962 | -- Interfaces.C is that we want to avoid dragging in the | |
9963 | -- code in this unit if possible. | |
9964 | subtype chars is System.Address; | |
9965 | -- Pointer to null-terminated array of characters | |
9966 | subtype FILEs is System.Address; | |
9967 | -- Corresponds to the C type FILE* | |
9968 | subtype voids is System.Address; | |
9969 | -- Corresponds to the C type void* | |
9970 | subtype int is Integer; | |
9971 | subtype long is Long_Integer; | |
9972 | -- Note: the above types are subtypes deliberately, and it | |
9973 | -- is part of this spec that the above correspondences are | |
ad42149c FW |
9974 | -- guaranteed. This means that it is legitimate to, for |
9975 | -- example, use Integer instead of int. We provide these | |
41af791f GB |
9976 | -- synonyms for clarity, but in some cases it may be |
9977 | -- convenient to use the underlying types (for example to | |
9978 | -- avoid an unnecessary dependency of a spec on the spec | |
9979 | -- of this unit). | |
9980 | type size_t is mod 2 ** Standard'Address_Size; | |
9981 | NULL_Stream : constant FILEs; | |
9982 | -- Value returned (NULL in C) to indicate an | |
9983 | -- fdopen/fopen/tmpfile error | |
9984 | ---------------------------------- | |
9985 | -- Constants Defined in stdio.h -- | |
9986 | ---------------------------------- | |
9987 | EOF : constant int; | |
9988 | -- Used by a number of routines to indicate error or | |
9989 | -- end of file | |
9990 | IOFBF : constant int; | |
9991 | IOLBF : constant int; | |
9992 | IONBF : constant int; | |
9993 | -- Used to indicate buffering mode for setvbuf call | |
9994 | SEEK_CUR : constant int; | |
9995 | SEEK_END : constant int; | |
9996 | SEEK_SET : constant int; | |
9997 | -- Used to indicate origin for fseek call | |
9998 | function stdin return FILEs; | |
9999 | function stdout return FILEs; | |
10000 | function stderr return FILEs; | |
10001 | -- Streams associated with standard files | |
10002 | -------------------------- | |
10003 | -- Standard C functions -- | |
10004 | -------------------------- | |
10005 | -- The functions selected below are ones that are | |
10006 | -- available in DOS, OS/2, UNIX and Xenix (but not | |
ad42149c FW |
10007 | -- necessarily in ANSI C). These are very thin interfaces |
10008 | -- which copy exactly the C headers. For more | |
41af791f GB |
10009 | -- documentation on these functions, see the Microsoft C |
10010 | -- "Run-Time Library Reference" (Microsoft Press, 1990, | |
10011 | -- ISBN 1-55615-225-6), which includes useful information | |
10012 | -- on system compatibility. | |
10013 | procedure clearerr (stream : FILEs); | |
10014 | function fclose (stream : FILEs) return int; | |
10015 | function fdopen (handle : int; mode : chars) return FILEs; | |
10016 | function feof (stream : FILEs) return int; | |
10017 | function ferror (stream : FILEs) return int; | |
10018 | function fflush (stream : FILEs) return int; | |
10019 | function fgetc (stream : FILEs) return int; | |
10020 | function fgets (strng : chars; n : int; stream : FILEs) | |
10021 | return chars; | |
10022 | function fileno (stream : FILEs) return int; | |
10023 | function fopen (filename : chars; Mode : chars) | |
10024 | return FILEs; | |
10025 | -- Note: to maintain target independence, use | |
10026 | -- text_translation_required, a boolean variable defined in | |
10027 | -- a-sysdep.c to deal with the target dependent text | |
ad42149c | 10028 | -- translation requirement. If this variable is set, |
41af791f GB |
10029 | -- then b/t should be appended to the standard mode |
10030 | -- argument to set the text translation mode off or on | |
10031 | -- as required. | |
10032 | function fputc (C : int; stream : FILEs) return int; | |
10033 | function fputs (Strng : chars; Stream : FILEs) return int; | |
10034 | function fread | |
10035 | (buffer : voids; | |
10036 | size : size_t; | |
10037 | count : size_t; | |
10038 | stream : FILEs) | |
10039 | return size_t; | |
10040 | function freopen | |
10041 | (filename : chars; | |
10042 | mode : chars; | |
10043 | stream : FILEs) | |
10044 | return FILEs; | |
10045 | function fseek | |
10046 | (stream : FILEs; | |
10047 | offset : long; | |
10048 | origin : int) | |
10049 | return int; | |
10050 | function ftell (stream : FILEs) return long; | |
10051 | function fwrite | |
10052 | (buffer : voids; | |
10053 | size : size_t; | |
10054 | count : size_t; | |
10055 | stream : FILEs) | |
10056 | return size_t; | |
10057 | function isatty (handle : int) return int; | |
10058 | procedure mktemp (template : chars); | |
10059 | -- The return value (which is just a pointer to template) | |
10060 | -- is discarded | |
10061 | procedure rewind (stream : FILEs); | |
10062 | function rmtmp return int; | |
10063 | function setvbuf | |
10064 | (stream : FILEs; | |
10065 | buffer : chars; | |
10066 | mode : int; | |
10067 | size : size_t) | |
10068 | return int; | |
10069 | ||
10070 | function tmpfile return FILEs; | |
10071 | function ungetc (c : int; stream : FILEs) return int; | |
10072 | function unlink (filename : chars) return int; | |
10073 | --------------------- | |
10074 | -- Extra functions -- | |
10075 | --------------------- | |
10076 | -- These functions supply slightly thicker bindings than | |
ad42149c | 10077 | -- those above. They are derived from functions in the |
41af791f GB |
10078 | -- C Run-Time Library, but may do a bit more work than |
10079 | -- just directly calling one of the Library functions. | |
10080 | function is_regular_file (handle : int) return int; | |
10081 | -- Tests if given handle is for a regular file (result 1) | |
10082 | -- or for a non-regular file (pipe or device, result 0). | |
10083 | --------------------------------- | |
10084 | -- Control of Text/Binary Mode -- | |
10085 | --------------------------------- | |
10086 | -- If text_translation_required is true, then the following | |
10087 | -- functions may be used to dynamically switch a file from | |
ad42149c FW |
10088 | -- binary to text mode or vice versa. These functions have |
10089 | -- no effect if text_translation_required is false (i.e. in | |
10090 | -- normal UNIX mode). Use fileno to get a stream handle. | |
41af791f GB |
10091 | procedure set_binary_mode (handle : int); |
10092 | procedure set_text_mode (handle : int); | |
10093 | ---------------------------- | |
10094 | -- Full Path Name support -- | |
10095 | ---------------------------- | |
10096 | procedure full_name (nam : chars; buffer : chars); | |
10097 | -- Given a NUL terminated string representing a file | |
10098 | -- name, returns in buffer a NUL terminated string | |
10099 | -- representing the full path name for the file name. | |
10100 | -- On systems where it is relevant the drive is also | |
ad42149c | 10101 | -- part of the full path name. It is the responsibility |
41af791f | 10102 | -- of the caller to pass an actual parameter for buffer |
ad42149c | 10103 | -- that is big enough for any full path name. Use |
41af791f GB |
10104 | -- max_path_len given below as the size of buffer. |
10105 | max_path_len : integer; | |
10106 | -- Maximum length of an allowable full path name on the | |
10107 | -- system, including a terminating NUL character. | |
10108 | end Interfaces.C_Streams; | |
10109 | @end smallexample | |
10110 | ||
10111 | @node Interfacing to C Streams | |
10112 | @section Interfacing to C Streams | |
10113 | ||
10114 | @noindent | |
10115 | The packages in this section permit interfacing Ada files to C Stream | |
10116 | operations. | |
10117 | ||
10118 | @smallexample | |
10119 | with Interfaces.C_Streams; | |
10120 | package Ada.Sequential_IO.C_Streams is | |
10121 | function C_Stream (F : File_Type) | |
10122 | return Interfaces.C_Streams.FILEs; | |
10123 | procedure Open | |
10124 | (File : in out File_Type; | |
10125 | Mode : in File_Mode; | |
10126 | C_Stream : in Interfaces.C_Streams.FILEs; | |
10127 | Form : in String := ""); | |
10128 | end Ada.Sequential_IO.C_Streams; | |
10129 | ||
10130 | with Interfaces.C_Streams; | |
10131 | package Ada.Direct_IO.C_Streams is | |
10132 | function C_Stream (F : File_Type) | |
10133 | return Interfaces.C_Streams.FILEs; | |
10134 | procedure Open | |
10135 | (File : in out File_Type; | |
10136 | Mode : in File_Mode; | |
10137 | C_Stream : in Interfaces.C_Streams.FILEs; | |
10138 | Form : in String := ""); | |
10139 | end Ada.Direct_IO.C_Streams; | |
10140 | ||
10141 | with Interfaces.C_Streams; | |
10142 | package Ada.Text_IO.C_Streams is | |
10143 | function C_Stream (F : File_Type) | |
10144 | return Interfaces.C_Streams.FILEs; | |
10145 | procedure Open | |
10146 | (File : in out File_Type; | |
10147 | Mode : in File_Mode; | |
10148 | C_Stream : in Interfaces.C_Streams.FILEs; | |
10149 | Form : in String := ""); | |
10150 | end Ada.Text_IO.C_Streams; | |
10151 | ||
10152 | with Interfaces.C_Streams; | |
10153 | package Ada.Wide_Text_IO.C_Streams is | |
10154 | function C_Stream (F : File_Type) | |
10155 | return Interfaces.C_Streams.FILEs; | |
10156 | procedure Open | |
10157 | (File : in out File_Type; | |
10158 | Mode : in File_Mode; | |
10159 | C_Stream : in Interfaces.C_Streams.FILEs; | |
10160 | Form : in String := ""); | |
10161 | end Ada.Wide_Text_IO.C_Streams; | |
10162 | ||
10163 | with Interfaces.C_Streams; | |
10164 | package Ada.Stream_IO.C_Streams is | |
10165 | function C_Stream (F : File_Type) | |
10166 | return Interfaces.C_Streams.FILEs; | |
10167 | procedure Open | |
10168 | (File : in out File_Type; | |
10169 | Mode : in File_Mode; | |
10170 | C_Stream : in Interfaces.C_Streams.FILEs; | |
10171 | Form : in String := ""); | |
10172 | end Ada.Stream_IO.C_Streams; | |
10173 | @end smallexample | |
10174 | ||
10175 | In each of these five packages, the @code{C_Stream} function obtains the | |
ad42149c | 10176 | @code{FILE} pointer from a currently opened Ada file. It is then |
41af791f GB |
10177 | possible to use the @code{Interfaces.C_Streams} package to operate on |
10178 | this stream, or the stream can be passed to a C program which can | |
ad42149c | 10179 | operate on it directly. Of course the program is responsible for |
41af791f GB |
10180 | ensuring that only appropriate sequences of operations are executed. |
10181 | ||
10182 | One particular use of relevance to an Ada program is that the | |
10183 | @code{setvbuf} function can be used to control the buffering of the | |
ad42149c | 10184 | stream used by an Ada file. In the absence of such a call the standard |
41af791f GB |
10185 | default buffering is used. |
10186 | ||
10187 | The @code{Open} procedures in these packages open a file giving an | |
ad42149c | 10188 | existing C Stream instead of a file name. Typically this stream is |
41af791f GB |
10189 | imported from a C program, allowing an Ada file to operate on an |
10190 | existing C file. | |
10191 | ||
10192 | @node The GNAT Library | |
10193 | @chapter The GNAT Library | |
10194 | ||
10195 | @noindent | |
10196 | The GNAT library contains a number of general and special purpose packages. | |
10197 | It represents functionality that the GNAT developers have found useful, and | |
ad42149c | 10198 | which is made available to GNAT users. The packages described here are fully |
41af791f GB |
10199 | supported, and upwards compatibility will be maintained in future releases, |
10200 | so you can use these facilities with the confidence that the same functionality | |
10201 | will be available in future releases. | |
10202 | ||
10203 | The chapter here simply gives a brief summary of the facilities available. | |
ad42149c | 10204 | The full documentation is found in the spec file for the package. The full |
41af791f | 10205 | sources of these library packages, including both spec and body, are provided |
ad42149c | 10206 | with all GNAT releases. For example, to find out the full specifications of |
41af791f | 10207 | the SPITBOL pattern matching capability, including a full tutorial and |
ad42149c | 10208 | extensive examples, look in the @file{g-spipat.ads} file in the library. |
41af791f GB |
10209 | |
10210 | For each entry here, the package name (as it would appear in a @code{with} | |
10211 | clause) is given, followed by the name of the corresponding spec file in | |
ad42149c | 10212 | parentheses. The packages are children in four hierarchies, @code{Ada}, |
41af791f GB |
10213 | @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a |
10214 | GNAT-specific hierarchy. | |
10215 | ||
10216 | Note that an application program should only use packages in one of these | |
10217 | four hierarchies if the package is defined in the Ada Reference Manual, | |
10218 | or is listed in this section of the GNAT Programmers Reference Manual. | |
10219 | All other units should be considered internal implementation units and | |
ad42149c | 10220 | should not be directly @code{with}'ed by application code. The use of |
41af791f GB |
10221 | a @code{with} statement that references one of these internal implementation |
10222 | units makes an application potentially dependent on changes in versions | |
10223 | of GNAT, and will generate a warning message. | |
10224 | ||
10225 | @menu | |
ad42149c | 10226 | * Ada.Characters.Latin_9 (a-chlat9.ads):: |
41af791f | 10227 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: |
ad42149c | 10228 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: |
41af791f GB |
10229 | * Ada.Command_Line.Remove (a-colire.ads):: |
10230 | * Ada.Direct_IO.C_Streams (a-diocst.ads):: | |
10231 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: | |
10232 | * Ada.Sequential_IO.C_Streams (a-siocst.ads):: | |
10233 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: | |
10234 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: | |
10235 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: | |
10236 | * Ada.Text_IO.C_Streams (a-tiocst.ads):: | |
10237 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: | |
10238 | * GNAT.AWK (g-awk.ads):: | |
10239 | * GNAT.Bubble_Sort_A (g-busora.ads):: | |
10240 | * GNAT.Bubble_Sort_G (g-busorg.ads):: | |
10241 | * GNAT.Calendar (g-calend.ads):: | |
10242 | * GNAT.Calendar.Time_IO (g-catiio.ads):: | |
10243 | * GNAT.CRC32 (g-crc32.ads):: | |
10244 | * GNAT.Case_Util (g-casuti.ads):: | |
10245 | * GNAT.CGI (g-cgi.ads):: | |
10246 | * GNAT.CGI.Cookie (g-cgicoo.ads):: | |
10247 | * GNAT.CGI.Debug (g-cgideb.ads):: | |
10248 | * GNAT.Command_Line (g-comlin.ads):: | |
10249 | * GNAT.Current_Exception (g-curexc.ads):: | |
10250 | * GNAT.Debug_Pools (g-debpoo.ads):: | |
10251 | * GNAT.Debug_Utilities (g-debuti.ads):: | |
10252 | * GNAT.Directory_Operations (g-dirope.ads):: | |
10253 | * GNAT.Dynamic_Tables (g-dyntab.ads):: | |
10254 | * GNAT.Exception_Traces (g-exctra.ads):: | |
10255 | * GNAT.Expect (g-expect.ads):: | |
10256 | * GNAT.Float_Control (g-flocon.ads):: | |
10257 | * GNAT.Heap_Sort_A (g-hesora.ads):: | |
10258 | * GNAT.Heap_Sort_G (g-hesorg.ads):: | |
10259 | * GNAT.HTable (g-htable.ads):: | |
10260 | * GNAT.IO (g-io.ads):: | |
10261 | * GNAT.IO_Aux (g-io_aux.ads):: | |
10262 | * GNAT.Lock_Files (g-locfil.ads):: | |
ad42149c | 10263 | * GNAT.MD5 (g-md5.ads):: |
41af791f GB |
10264 | * GNAT.Most_Recent_Exception (g-moreex.ads):: |
10265 | * GNAT.OS_Lib (g-os_lib.ads):: | |
10266 | * GNAT.Regexp (g-regexp.ads):: | |
10267 | * GNAT.Registry (g-regist.ads):: | |
10268 | * GNAT.Regpat (g-regpat.ads):: | |
10269 | * GNAT.Sockets (g-socket.ads):: | |
10270 | * GNAT.Source_Info (g-souinf.ads):: | |
10271 | * GNAT.Spell_Checker (g-speche.ads):: | |
10272 | * GNAT.Spitbol.Patterns (g-spipat.ads):: | |
10273 | * GNAT.Spitbol (g-spitbo.ads):: | |
10274 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: | |
10275 | * GNAT.Spitbol.Table_Integer (g-sptain.ads):: | |
10276 | * GNAT.Spitbol.Table_VString (g-sptavs.ads):: | |
10277 | * GNAT.Table (g-table.ads):: | |
10278 | * GNAT.Task_Lock (g-tasloc.ads):: | |
10279 | * GNAT.Threads (g-thread.ads):: | |
10280 | * GNAT.Traceback (g-traceb.ads):: | |
10281 | * GNAT.Traceback.Symbolic (g-trasym.ads):: | |
10282 | * Interfaces.C.Extensions (i-cexten.ads):: | |
10283 | * Interfaces.C.Streams (i-cstrea.ads):: | |
10284 | * Interfaces.CPP (i-cpp.ads):: | |
10285 | * Interfaces.Os2lib (i-os2lib.ads):: | |
10286 | * Interfaces.Os2lib.Errors (i-os2err.ads):: | |
10287 | * Interfaces.Os2lib.Synchronization (i-os2syn.ads):: | |
10288 | * Interfaces.Os2lib.Threads (i-os2thr.ads):: | |
10289 | * Interfaces.Packed_Decimal (i-pacdec.ads):: | |
10290 | * Interfaces.VxWorks (i-vxwork.ads):: | |
ad42149c | 10291 | * Interfaces.VxWorks.IO (i-vxwoio.ads):: |
41af791f GB |
10292 | * System.Address_Image (s-addima.ads):: |
10293 | * System.Assertions (s-assert.ads):: | |
10294 | * System.Partition_Interface (s-parint.ads):: | |
10295 | * System.Task_Info (s-tasinf.ads):: | |
10296 | * System.Wch_Cnv (s-wchcnv.ads):: | |
10297 | * System.Wch_Con (s-wchcon.ads):: | |
10298 | @end menu | |
10299 | ||
ad42149c FW |
10300 | @node Ada.Characters.Latin_9 (a-chlat9.ads) |
10301 | @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) | |
10302 | @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) | |
10303 | @cindex Latin_9 constants for Character | |
10304 | ||
10305 | @noindent | |
10306 | This child of @code{Ada.Characters} | |
10307 | provides a set of definitions corresponding to those in the | |
10308 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
10309 | few modifications required for @code{Latin-9} | |
10310 | The provision of such a package | |
10311 | is specifically authorized by the Ada Reference Manual | |
10312 | (RM A.3(27)). | |
10313 | ||
41af791f | 10314 | @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) |
ad42149c FW |
10315 | @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) |
10316 | @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) | |
10317 | @cindex Latin_1 constants for Wide_Character | |
41af791f GB |
10318 | |
10319 | @noindent | |
10320 | This child of @code{Ada.Characters} | |
10321 | provides a set of definitions corresponding to those in the | |
10322 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
10323 | types of the constants being @code{Wide_Character} | |
ad42149c FW |
10324 | instead of @code{Character}. The provision of such a package |
10325 | is specifically authorized by the Ada Reference Manual | |
10326 | (RM A.3(27)). | |
10327 | ||
10328 | @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) | |
10329 | @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) | |
10330 | @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) | |
10331 | @cindex Latin_9 constants for Wide_Character | |
10332 | ||
10333 | @noindent | |
10334 | This child of @code{Ada.Characters} | |
10335 | provides a set of definitions corresponding to those in the | |
10336 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
10337 | types of the constants being @code{Wide_Character} | |
10338 | instead of @code{Character}. The provision of such a package | |
41af791f GB |
10339 | is specifically authorized by the Ada Reference Manual |
10340 | (RM A.3(27)). | |
10341 | ||
10342 | @node Ada.Command_Line.Remove (a-colire.ads) | |
ad42149c FW |
10343 | @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) |
10344 | @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) | |
10345 | @cindex Removing command line arguments | |
10346 | @cindex Command line, argument removal | |
41af791f GB |
10347 | |
10348 | @noindent | |
10349 | This child of @code{Ada.Command_Line} | |
10350 | provides a mechanism for logically removing | |
ad42149c | 10351 | arguments from the argument list. Once removed, an argument is not visible |
41af791f GB |
10352 | to further calls on the subprograms in @code{Ada.Command_Line} will not |
10353 | see the removed argument. | |
10354 | ||
10355 | @node Ada.Direct_IO.C_Streams (a-diocst.ads) | |
ad42149c FW |
10356 | @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) |
10357 | @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) | |
10358 | @cindex C Streams, Interfacing with Direct_IO | |
41af791f GB |
10359 | |
10360 | @noindent | |
10361 | This package provides subprograms that allow interfacing between | |
ad42149c | 10362 | C streams and @code{Direct_IO}. The stream identifier can be |
41af791f GB |
10363 | extracted from a file opened on the Ada side, and an Ada file |
10364 | can be constructed from a stream opened on the C side. | |
10365 | ||
10366 | @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) | |
ad42149c FW |
10367 | @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) |
10368 | @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) | |
10369 | @cindex Null_Occurrence, testing for | |
41af791f GB |
10370 | |
10371 | @noindent | |
10372 | This child subprogram provides a way of testing for the null | |
10373 | exception occurrence (@code{Null_Occurrence}) without raising | |
10374 | an exception. | |
10375 | ||
10376 | @node Ada.Sequential_IO.C_Streams (a-siocst.ads) | |
ad42149c FW |
10377 | @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) |
10378 | @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) | |
10379 | @cindex C Streams, Interfacing with Sequential_IO | |
41af791f GB |
10380 | |
10381 | @noindent | |
10382 | This package provides subprograms that allow interfacing between | |
ad42149c | 10383 | C streams and @code{Sequential_IO}. The stream identifier can be |
41af791f GB |
10384 | extracted from a file opened on the Ada side, and an Ada file |
10385 | can be constructed from a stream opened on the C side. | |
10386 | ||
10387 | @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) | |
ad42149c FW |
10388 | @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) |
10389 | @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) | |
10390 | @cindex C Streams, Interfacing with Stream_IO | |
41af791f GB |
10391 | |
10392 | @noindent | |
10393 | This package provides subprograms that allow interfacing between | |
ad42149c | 10394 | C streams and @code{Stream_IO}. The stream identifier can be |
41af791f GB |
10395 | extracted from a file opened on the Ada side, and an Ada file |
10396 | can be constructed from a stream opened on the C side. | |
10397 | ||
10398 | @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) | |
ad42149c FW |
10399 | @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) |
10400 | @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) | |
10401 | @cindex @code{Unbounded_String}, IO support | |
10402 | @cindex @code{Text_IO}, extensions for unbounded strings | |
41af791f GB |
10403 | |
10404 | @noindent | |
10405 | This package provides subprograms for Text_IO for unbounded | |
10406 | strings, avoiding the necessity for an intermediate operation | |
10407 | with ordinary strings. | |
10408 | ||
10409 | @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) | |
ad42149c FW |
10410 | @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) |
10411 | @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) | |
10412 | @cindex @code{Unbounded_Wide_String}, IO support | |
10413 | @cindex @code{Text_IO}, extensions for unbounded wide strings | |
41af791f GB |
10414 | |
10415 | @noindent | |
10416 | This package provides subprograms for Text_IO for unbounded | |
10417 | wide strings, avoiding the necessity for an intermediate operation | |
10418 | with ordinary wide strings. | |
10419 | ||
10420 | @node Ada.Text_IO.C_Streams (a-tiocst.ads) | |
ad42149c FW |
10421 | @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) |
10422 | @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) | |
10423 | @cindex C Streams, Interfacing with @code{Text_IO} | |
41af791f GB |
10424 | |
10425 | @noindent | |
10426 | This package provides subprograms that allow interfacing between | |
ad42149c | 10427 | C streams and @code{Text_IO}. The stream identifier can be |
41af791f GB |
10428 | extracted from a file opened on the Ada side, and an Ada file |
10429 | can be constructed from a stream opened on the C side. | |
10430 | ||
10431 | @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) | |
ad42149c FW |
10432 | @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) |
10433 | @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) | |
10434 | @cindex C Streams, Interfacing with @code{Wide_Text_IO} | |
41af791f GB |
10435 | |
10436 | @noindent | |
10437 | This package provides subprograms that allow interfacing between | |
ad42149c | 10438 | C streams and @code{Wide_Text_IO}. The stream identifier can be |
41af791f GB |
10439 | extracted from a file opened on the Ada side, and an Ada file |
10440 | can be constructed from a stream opened on the C side. | |
10441 | ||
10442 | @node GNAT.AWK (g-awk.ads) | |
ad42149c FW |
10443 | @section @code{GNAT.AWK} (@file{g-awk.ads}) |
10444 | @cindex @code{GNAT.AWK} (@file{g-awk.ads}) | |
41af791f | 10445 | @cindex Parsing |
ad42149c | 10446 | @cindex AWK |
41af791f GB |
10447 | |
10448 | @noindent | |
10449 | Provides AWK-like parsing functions, with an easy interface for parsing one | |
ad42149c | 10450 | or more files containing formatted data. The file is viewed as a database |
41af791f GB |
10451 | where each record is a line and a field is a data element in this line. |
10452 | ||
10453 | @node GNAT.Bubble_Sort_A (g-busora.ads) | |
ad42149c FW |
10454 | @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) |
10455 | @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) | |
41af791f | 10456 | @cindex Sorting |
ad42149c | 10457 | @cindex Bubble sort |
41af791f GB |
10458 | |
10459 | @noindent | |
10460 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
ad42149c | 10461 | data items. Move and comparison procedures are provided by passing |
41af791f GB |
10462 | access-to-procedure values. |
10463 | ||
10464 | @node GNAT.Bubble_Sort_G (g-busorg.ads) | |
ad42149c FW |
10465 | @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) |
10466 | @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) | |
41af791f | 10467 | @cindex Sorting |
ad42149c | 10468 | @cindex Bubble sort |
41af791f GB |
10469 | |
10470 | @noindent | |
10471 | Similar to @code{Bubble_Sort_A} except that the move and sorting procedures | |
10472 | are provided as generic parameters, this improves efficiency, especially | |
10473 | if the procedures can be inlined, at the expense of duplicating code for | |
10474 | multiple instantiations. | |
10475 | ||
10476 | @node GNAT.Calendar (g-calend.ads) | |
ad42149c FW |
10477 | @section @code{GNAT.Calendar} (@file{g-calend.ads}) |
10478 | @cindex @code{GNAT.Calendar} (@file{g-calend.ads}) | |
10479 | @cindex @code{Calendar} | |
41af791f GB |
10480 | |
10481 | @noindent | |
10482 | Extends the facilities provided by @code{Ada.Calendar} to include handling | |
10483 | of days of the week, an extended @code{Split} and @code{Time_Of} capability. | |
10484 | Also provides conversion of @code{Ada.Calendar.Time} values to and from the | |
10485 | C @code{timeval} format. | |
10486 | ||
10487 | @node GNAT.Calendar.Time_IO (g-catiio.ads) | |
ad42149c FW |
10488 | @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) |
10489 | @cindex @code{Calendar} | |
41af791f | 10490 | @cindex Time |
ad42149c | 10491 | @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) |
41af791f GB |
10492 | |
10493 | @node GNAT.CRC32 (g-crc32.ads) | |
ad42149c FW |
10494 | @section @code{GNAT.CRC32} (@file{g-crc32.ads}) |
10495 | @cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) | |
41af791f | 10496 | @cindex CRC32 |
ad42149c | 10497 | @cindex Cyclic Redundancy Check |
41af791f GB |
10498 | |
10499 | @noindent | |
ad42149c | 10500 | This package implements the CRC-32 algorithm. For a full description |
41af791f | 10501 | of this algorithm you should have a look at: |
ad42149c FW |
10502 | ``Computation of Cyclic Redundancy Checks via Table Look-Up'', @cite{Communications |
10503 | of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, Aug.@: 1988. Sarwate, D.V@. | |
41af791f GB |
10504 | |
10505 | @noindent | |
10506 | Provides an extended capability for formatted output of time values with | |
ad42149c | 10507 | full user control over the format. Modeled on the GNU Date specification. |
41af791f GB |
10508 | |
10509 | @node GNAT.Case_Util (g-casuti.ads) | |
ad42149c FW |
10510 | @section @code{GNAT.Case_Util} (@file{g-casuti.ads}) |
10511 | @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) | |
41af791f | 10512 | @cindex Casing utilities |
ad42149c | 10513 | @cindex Character handling (@code{GNAT.Case_Util}) |
41af791f GB |
10514 | |
10515 | @noindent | |
10516 | A set of simple routines for handling upper and lower casing of strings | |
10517 | without the overhead of the full casing tables | |
10518 | in @code{Ada.Characters.Handling}. | |
10519 | ||
10520 | @node GNAT.CGI (g-cgi.ads) | |
ad42149c FW |
10521 | @section @code{GNAT.CGI} (@file{g-cgi.ads}) |
10522 | @cindex @code{GNAT.CGI} (@file{g-cgi.ads}) | |
41af791f GB |
10523 | @cindex CGI (Common Gateway Interface) |
10524 | ||
10525 | @noindent | |
10526 | This is a package for interfacing a GNAT program with a Web server via the | |
ad42149c FW |
10527 | Common Gateway Interface (CGI)@. Basically this package parses the CGI |
10528 | parameters, which are a set of key/value pairs sent by the Web server. It | |
41af791f GB |
10529 | builds a table whose index is the key and provides some services to deal |
10530 | with this table. | |
10531 | ||
10532 | @node GNAT.CGI.Cookie (g-cgicoo.ads) | |
ad42149c FW |
10533 | @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) |
10534 | @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) | |
10535 | @cindex CGI (Common Gateway Interface) cookie support | |
10536 | @cindex Cookie support in CGI | |
41af791f GB |
10537 | |
10538 | @noindent | |
10539 | This is a package to interface a GNAT program with a Web server via the | |
ad42149c | 10540 | Common Gateway Interface (CGI). It exports services to deal with Web |
41af791f GB |
10541 | cookies (piece of information kept in the Web client software). |
10542 | ||
10543 | @node GNAT.CGI.Debug (g-cgideb.ads) | |
ad42149c FW |
10544 | @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) |
10545 | @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) | |
41af791f GB |
10546 | @cindex CGI (Common Gateway Interface) debugging |
10547 | ||
10548 | @noindent | |
10549 | This is a package to help debugging CGI (Common Gateway Interface) | |
10550 | programs written in Ada. | |
10551 | ||
10552 | @node GNAT.Command_Line (g-comlin.ads) | |
ad42149c FW |
10553 | @section @code{GNAT.Command_Line} (@file{g-comlin.ads}) |
10554 | @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) | |
41af791f GB |
10555 | @cindex Command line |
10556 | ||
10557 | @noindent | |
10558 | Provides a high level interface to @code{Ada.Command_Line} facilities, | |
10559 | including the ability to scan for named switches with optional parameters | |
10560 | and expand file names using wild card notations. | |
10561 | ||
10562 | @node GNAT.Current_Exception (g-curexc.ads) | |
ad42149c FW |
10563 | @section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) |
10564 | @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) | |
41af791f GB |
10565 | @cindex Current exception |
10566 | @cindex Exception retrieval | |
10567 | ||
10568 | @noindent | |
10569 | Provides access to information on the current exception that has been raised | |
10570 | without the need for using the Ada-95 exception choice parameter specification | |
ad42149c | 10571 | syntax. This is particularly useful in simulating typical facilities for |
41af791f GB |
10572 | obtaining information about exceptions provided by Ada 83 compilers. |
10573 | ||
10574 | @node GNAT.Debug_Pools (g-debpoo.ads) | |
ad42149c FW |
10575 | @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) |
10576 | @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) | |
41af791f | 10577 | @cindex Debugging |
ad42149c FW |
10578 | @cindex Debug pools |
10579 | @cindex Memory corruption debugging | |
41af791f GB |
10580 | |
10581 | @noindent | |
10582 | Provide a debugging storage pools that helps tracking memory corruption | |
ad42149c FW |
10583 | problems. See section ``Finding memory problems with GNAT Debug Pool'' in |
10584 | the @cite{GNAT User's Guide}. | |
41af791f GB |
10585 | |
10586 | @node GNAT.Debug_Utilities (g-debuti.ads) | |
ad42149c FW |
10587 | @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) |
10588 | @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) | |
41af791f GB |
10589 | @cindex Debugging |
10590 | ||
10591 | @noindent | |
10592 | Provides a few useful utilities for debugging purposes, including conversion | |
10593 | to and from string images of address values. | |
10594 | ||
10595 | @node GNAT.Directory_Operations (g-dirope.ads) | |
ad42149c FW |
10596 | @section @code{GNAT.Directory_Operations} (g-dirope.ads) |
10597 | @cindex @code{GNAT.Directory_Operations} (g-dirope.ads) | |
41af791f GB |
10598 | @cindex Directory operations |
10599 | ||
10600 | @noindent | |
10601 | Provides a set of routines for manipulating directories, including changing | |
10602 | the current directory, making new directories, and scanning the files in a | |
10603 | directory. | |
10604 | ||
10605 | @node GNAT.Dynamic_Tables (g-dyntab.ads) | |
ad42149c FW |
10606 | @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) |
10607 | @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) | |
41af791f GB |
10608 | @cindex Table implementation |
10609 | @cindex Arrays, extendable | |
10610 | ||
10611 | @noindent | |
10612 | A generic package providing a single dimension array abstraction where the | |
10613 | length of the array can be dynamically modified. | |
10614 | ||
10615 | @noindent | |
10616 | This package provides a facility similar to that of GNAT.Table, except | |
10617 | that this package declares a type that can be used to define dynamic | |
10618 | instances of the table, while an instantiation of GNAT.Table creates a | |
10619 | single instance of the table type. | |
10620 | ||
10621 | @node GNAT.Exception_Traces (g-exctra.ads) | |
ad42149c FW |
10622 | @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) |
10623 | @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) | |
41af791f GB |
10624 | @cindex Exception traces |
10625 | @cindex Debugging | |
10626 | ||
10627 | @noindent | |
10628 | Provides an interface allowing to control automatic output upon exception | |
10629 | occurrences. | |
10630 | ||
10631 | @node GNAT.Expect (g-expect.ads) | |
ad42149c FW |
10632 | @section @code{GNAT.Expect} (@file{g-expect.ads}) |
10633 | @cindex @code{GNAT.Expect} (@file{g-expect.ads}) | |
41af791f GB |
10634 | |
10635 | @noindent | |
10636 | Provides a set of subprograms similar to what is available | |
10637 | with the standard Tcl Expect tool. | |
10638 | It allows you to easily spawn and communicate with an external process. | |
10639 | You can send commands or inputs to the process, and compare the output | |
10640 | with some expected regular expression. | |
10641 | Currently GNAT.Expect is implemented on all native GNAT ports except for | |
ad42149c | 10642 | OpenVMS@. It is not implemented for cross ports, and in particular is not |
46b58b8c | 10643 | implemented for VxWorks or LynxOS@. |
41af791f GB |
10644 | |
10645 | @node GNAT.Float_Control (g-flocon.ads) | |
ad42149c FW |
10646 | @section @code{GNAT.Float_Control} (@file{g-flocon.ads}) |
10647 | @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) | |
41af791f GB |
10648 | @cindex Floating-Point Processor |
10649 | ||
10650 | @noindent | |
10651 | Provides an interface for resetting the floating-point processor into the | |
ad42149c | 10652 | mode required for correct semantic operation in Ada. Some third party |
41af791f GB |
10653 | library calls may cause this mode to be modified, and the Reset procedure |
10654 | in this package can be used to reestablish the required mode. | |
10655 | ||
10656 | @node GNAT.Heap_Sort_A (g-hesora.ads) | |
ad42149c FW |
10657 | @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) |
10658 | @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) | |
41af791f GB |
10659 | @cindex Sorting |
10660 | ||
10661 | @noindent | |
10662 | Provides a general implementation of heap sort usable for sorting arbitrary | |
ad42149c FW |
10663 | data items. Move and comparison procedures are provided by passing |
10664 | access-to-procedure values. The algorithm used is a modified heap sort | |
41af791f GB |
10665 | that performs approximately N*log(N) comparisons in the worst case. |
10666 | ||
10667 | @node GNAT.Heap_Sort_G (g-hesorg.ads) | |
ad42149c FW |
10668 | @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) |
10669 | @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) | |
41af791f GB |
10670 | @cindex Sorting |
10671 | ||
10672 | @noindent | |
10673 | Similar to @code{Heap_Sort_A} except that the move and sorting procedures | |
10674 | are provided as generic parameters, this improves efficiency, especially | |
10675 | if the procedures can be inlined, at the expense of duplicating code for | |
10676 | multiple instantiations. | |
10677 | ||
10678 | @node GNAT.HTable (g-htable.ads) | |
ad42149c FW |
10679 | @section @code{GNAT.HTable} (@file{g-htable.ads}) |
10680 | @cindex @code{GNAT.HTable} (@file{g-htable.ads}) | |
41af791f GB |
10681 | @cindex Hash tables |
10682 | ||
10683 | @noindent | |
10684 | A generic implementation of hash tables that can be used to hash arbitrary | |
ad42149c | 10685 | data. Provides two approaches, one a simple static approach, and the other |
41af791f GB |
10686 | allowing arbitrary dynamic hash tables. |
10687 | ||
10688 | @node GNAT.IO (g-io.ads) | |
ad42149c FW |
10689 | @section @code{GNAT.IO} (@file{g-io.ads}) |
10690 | @cindex @code{GNAT.IO} (@file{g-io.ads}) | |
41af791f GB |
10691 | @cindex Simple I/O |
10692 | @cindex Input/Output facilities | |
10693 | ||
10694 | @noindent | |
10695 | A simple preealborable input-output package that provides a subset of | |
10696 | simple Text_IO functions for reading characters and strings from | |
10697 | Standard_Input, and writing characters, strings and integers to either | |
10698 | Standard_Output or Standard_Error. | |
10699 | ||
10700 | @node GNAT.IO_Aux (g-io_aux.ads) | |
ad42149c FW |
10701 | @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) |
10702 | @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) | |
41af791f GB |
10703 | @cindex Text_IO |
10704 | @cindex Input/Output facilities | |
10705 | ||
10706 | Provides some auxiliary functions for use with Text_IO, including a test | |
10707 | for whether a file exists, and functions for reading a line of text. | |
10708 | ||
10709 | @node GNAT.Lock_Files (g-locfil.ads) | |
ad42149c FW |
10710 | @section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) |
10711 | @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) | |
41af791f GB |
10712 | @cindex File locking |
10713 | @cindex Locking using files | |
10714 | ||
10715 | @noindent | |
ad42149c | 10716 | Provides a general interface for using files as locks. Can be used for |
41af791f GB |
10717 | providing program level synchronization. |
10718 | ||
ad42149c FW |
10719 | @node GNAT.MD5 (g-md5.ads) |
10720 | @section @code{GNAT.MD5} (@file{g-md5.ads}) | |
10721 | @cindex @code{GNAT.MD5} (@file{g-md5.ads}) | |
10722 | @cindex Message Digest MD5 | |
10723 | ||
10724 | @noindent | |
10725 | Implements the MD5 Message-Digest Algorithm as described in RFC 1321. | |
10726 | ||
41af791f | 10727 | @node GNAT.Most_Recent_Exception (g-moreex.ads) |
ad42149c FW |
10728 | @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) |
10729 | @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) | |
41af791f GB |
10730 | @cindex Exception, obtaining most recent |
10731 | ||
10732 | @noindent | |
ad42149c | 10733 | Provides access to the most recently raised exception. Can be used for |
41af791f GB |
10734 | various logging purposes, including duplicating functionality of some |
10735 | Ada 83 implementation dependent extensions. | |
10736 | ||
10737 | @node GNAT.OS_Lib (g-os_lib.ads) | |
ad42149c FW |
10738 | @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) |
10739 | @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) | |
41af791f GB |
10740 | @cindex Operating System interface |
10741 | @cindex Spawn capability | |
10742 | ||
10743 | @noindent | |
10744 | Provides a range of target independent operating system interface functions, | |
10745 | including time/date management, file operations, subprocess management, | |
10746 | including a portable spawn procedure, and access to environment variables | |
10747 | and error return codes. | |
10748 | ||
10749 | @node GNAT.Regexp (g-regexp.ads) | |
ad42149c FW |
10750 | @section @code{GNAT.Regexp} (@file{g-regexp.ads}) |
10751 | @cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) | |
41af791f GB |
10752 | @cindex Regular expressions |
10753 | @cindex Pattern matching | |
10754 | ||
10755 | @noindent | |
10756 | A simple implementation of regular expressions, using a subset of regular | |
ad42149c | 10757 | expression syntax copied from familiar Unix style utilities. This is the |
41af791f | 10758 | simples of the three pattern matching packages provided, and is particularly |
ad42149c | 10759 | suitable for ``file globbing'' applications. |
41af791f GB |
10760 | |
10761 | @node GNAT.Registry (g-regist.ads) | |
ad42149c FW |
10762 | @section @code{GNAT.Registry} (@file{g-regist.ads}) |
10763 | @cindex @code{GNAT.Registry} (@file{g-regist.ads}) | |
41af791f GB |
10764 | @cindex Windows Registry |
10765 | ||
10766 | @noindent | |
ad42149c FW |
10767 | This is a high level binding to the Windows registry. It is possible to |
10768 | do simple things like reading a key value, creating a new key. For full | |
41af791f GB |
10769 | registry API, but at a lower level of abstraction, refer to the Win32.Winreg |
10770 | package provided with the Win32Ada binding | |
10771 | ||
10772 | @node GNAT.Regpat (g-regpat.ads) | |
ad42149c FW |
10773 | @section @code{GNAT.Regpat} (@file{g-regpat.ads}) |
10774 | @cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) | |
41af791f GB |
10775 | @cindex Regular expressions |
10776 | @cindex Pattern matching | |
10777 | ||
10778 | @noindent | |
10779 | A complete implementation of Unix-style regular expression matching, copied | |
10780 | from the original V7 style regular expression library written in C by | |
10781 | Henry Spencer (and binary compatible with this C library). | |
10782 | ||
10783 | @node GNAT.Sockets (g-socket.ads) | |
ad42149c FW |
10784 | @section @code{GNAT.Sockets} (@file{g-socket.ads}) |
10785 | @cindex @code{GNAT.Sockets} (@file{g-socket.ads}) | |
41af791f GB |
10786 | @cindex Sockets |
10787 | ||
10788 | @noindent | |
10789 | A high level and portable interface to develop sockets based applications. | |
10790 | This package is based on the sockets thin binding found in GNAT.Sockets.Thin. | |
10791 | Currently GNAT.Sockets is implemented on all native GNAT ports except for | |
ad42149c | 10792 | OpenVMS@. It is not implemented for the LynxOS@ cross port. |
41af791f GB |
10793 | |
10794 | @node GNAT.Source_Info (g-souinf.ads) | |
ad42149c FW |
10795 | @section @code{GNAT.Source_Info} (@file{g-souinf.ads}) |
10796 | @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) | |
41af791f GB |
10797 | @cindex Source Information |
10798 | ||
10799 | @noindent | |
10800 | Provides subprograms that give access to source code information known at | |
10801 | compile time, such as the current file name and line number. | |
10802 | ||
10803 | @node GNAT.Spell_Checker (g-speche.ads) | |
ad42149c FW |
10804 | @section @code{GNAT.Spell_Checker} (@file{g-speche.ads}) |
10805 | @cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads}) | |
41af791f GB |
10806 | @cindex Spell checking |
10807 | ||
10808 | @noindent | |
10809 | Provides a function for determining whether one string is a plausible | |
10810 | near misspelling of another string. | |
10811 | ||
10812 | @node GNAT.Spitbol.Patterns (g-spipat.ads) | |
ad42149c FW |
10813 | @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) |
10814 | @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) | |
41af791f GB |
10815 | @cindex SPITBOL pattern matching |
10816 | @cindex Pattern matching | |
10817 | ||
10818 | @noindent | |
ad42149c FW |
10819 | A complete implementation of SNOBOL4 style pattern matching. This is the |
10820 | most elaborate of the pattern matching packages provided. It fully duplicates | |
41af791f GB |
10821 | the SNOBOL4 dynamic pattern construction and matching capabilities, using the |
10822 | efficient algorithm developed by Robert Dewar for the SPITBOL system. | |
10823 | ||
10824 | @node GNAT.Spitbol (g-spitbo.ads) | |
ad42149c FW |
10825 | @section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) |
10826 | @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) | |
41af791f GB |
10827 | @cindex SPITBOL interface |
10828 | ||
10829 | @noindent | |
10830 | The top level package of the collection of SPITBOL-style functionality, this | |
10831 | package provides basic SNOBOL4 string manipulation functions, such as | |
10832 | Pad, Reverse, Trim, Substr capability, as well as a generic table function | |
10833 | useful for constructing arbitrary mappings from strings in the style of | |
10834 | the SNOBOL4 TABLE function. | |
10835 | ||
10836 | @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) | |
ad42149c FW |
10837 | @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) |
10838 | @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) | |
41af791f GB |
10839 | @cindex Sets of strings |
10840 | @cindex SPITBOL Tables | |
10841 | ||
10842 | @noindent | |
10843 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
10844 | for type @code{Standard.Boolean}, giving an implementation of sets of | |
10845 | string values. | |
10846 | ||
10847 | @node GNAT.Spitbol.Table_Integer (g-sptain.ads) | |
ad42149c FW |
10848 | @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) |
10849 | @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) | |
41af791f GB |
10850 | @cindex Integer maps |
10851 | @cindex Maps | |
10852 | @cindex SPITBOL Tables | |
10853 | ||
10854 | @noindent | |
10855 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
10856 | for type @code{Standard.Integer}, giving an implementation of maps | |
10857 | from string to integer values. | |
10858 | ||
10859 | @node GNAT.Spitbol.Table_VString (g-sptavs.ads) | |
ad42149c FW |
10860 | @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) |
10861 | @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) | |
41af791f GB |
10862 | @cindex String maps |
10863 | @cindex Maps | |
10864 | @cindex SPITBOL Tables | |
10865 | ||
10866 | @noindent | |
10867 | A library level of instantiation of GNAT.Spitbol.Patterns.Table for | |
10868 | a variable length string type, giving an implementation of general | |
10869 | maps from strings to strings. | |
10870 | ||
10871 | @node GNAT.Table (g-table.ads) | |
ad42149c FW |
10872 | @section @code{GNAT.Table} (@file{g-table.ads}) |
10873 | @cindex @code{GNAT.Table} (@file{g-table.ads}) | |
41af791f GB |
10874 | @cindex Table implementation |
10875 | @cindex Arrays, extendable | |
10876 | ||
10877 | @noindent | |
10878 | A generic package providing a single dimension array abstraction where the | |
10879 | length of the array can be dynamically modified. | |
10880 | ||
10881 | @noindent | |
10882 | This package provides a facility similar to that of GNAT.Dynamic_Tables, | |
10883 | except that this package declares a single instance of the table type, | |
10884 | while an instantiation of GNAT.Dynamic_Tables creates a type that can be | |
10885 | used to define dynamic instances of the table. | |
10886 | ||
10887 | @node GNAT.Task_Lock (g-tasloc.ads) | |
ad42149c FW |
10888 | @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) |
10889 | @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) | |
41af791f GB |
10890 | @cindex Task synchronization |
10891 | @cindex Task locking | |
10892 | @cindex Locking | |
10893 | ||
10894 | @noindent | |
10895 | A very simple facility for locking and unlocking sections of code using a | |
ad42149c | 10896 | single global task lock. Appropriate for use in situations where contention |
41af791f GB |
10897 | between tasks is very rarely expected. |
10898 | ||
10899 | @node GNAT.Threads (g-thread.ads) | |
ad42149c FW |
10900 | @section @code{GNAT.Threads} (@file{g-thread.ads}) |
10901 | @cindex @code{GNAT.Threads} (@file{g-thread.ads}) | |
41af791f GB |
10902 | @cindex Foreign threads |
10903 | @cindex Threads, foreign | |
10904 | ||
10905 | @noindent | |
10906 | Provides facilities for creating and destroying threads with explicit calls. | |
ad42149c | 10907 | These threads are known to the GNAT run-time system. These subprograms are |
41af791f GB |
10908 | exported C-convention procedures intended to be called from foreign code. |
10909 | By using these primitives rather than directly calling operating systems | |
10910 | routines, compatibility with the Ada tasking runt-time is provided. | |
10911 | ||
10912 | @node GNAT.Traceback (g-traceb.ads) | |
ad42149c FW |
10913 | @section @code{GNAT.Traceback} (@file{g-traceb.ads}) |
10914 | @cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) | |
41af791f GB |
10915 | @cindex Trace back facilities |
10916 | ||
10917 | @noindent | |
10918 | Provides a facility for obtaining non-symbolic traceback information, useful | |
10919 | in various debugging situations. | |
10920 | ||
10921 | @node GNAT.Traceback.Symbolic (g-trasym.ads) | |
ad42149c FW |
10922 | @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) |
10923 | @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) | |
41af791f GB |
10924 | @cindex Trace back facilities |
10925 | ||
10926 | @noindent | |
10927 | Provides symbolic traceback information that includes the subprogram | |
10928 | name and line number information. | |
10929 | ||
10930 | @node Interfaces.C.Extensions (i-cexten.ads) | |
ad42149c FW |
10931 | @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) |
10932 | @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) | |
41af791f GB |
10933 | |
10934 | @noindent | |
10935 | This package contains additional C-related definitions, intended | |
10936 | for use with either manually or automatically generated bindings | |
10937 | to C libraries. | |
10938 | ||
10939 | @node Interfaces.C.Streams (i-cstrea.ads) | |
ad42149c FW |
10940 | @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) |
10941 | @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) | |
41af791f GB |
10942 | @cindex C streams, interfacing |
10943 | ||
10944 | @noindent | |
10945 | This package is a binding for the most commonly used operations | |
10946 | on C streams. | |
10947 | ||
10948 | @node Interfaces.CPP (i-cpp.ads) | |
ad42149c FW |
10949 | @section @code{Interfaces.CPP} (@file{i-cpp.ads}) |
10950 | @cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) | |
41af791f GB |
10951 | @cindex C++ interfacing |
10952 | @cindex Interfacing, to C++ | |
10953 | ||
10954 | @noindent | |
ad42149c | 10955 | This package provides facilities for use in interfacing to C++. It |
41af791f GB |
10956 | is primarily intended to be used in connection with automated tools |
10957 | for the generation of C++ interfaces. | |
10958 | ||
10959 | @node Interfaces.Os2lib (i-os2lib.ads) | |
ad42149c FW |
10960 | @section @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) |
10961 | @cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) | |
41af791f GB |
10962 | @cindex Interfacing, to OS/2 |
10963 | @cindex OS/2 interfacing | |
10964 | ||
10965 | @noindent | |
10966 | This package provides interface definitions to the OS/2 library. | |
10967 | It is a thin binding which is a direct translation of the | |
10968 | various @file{<bse@.h>} files. | |
10969 | ||
10970 | @node Interfaces.Os2lib.Errors (i-os2err.ads) | |
ad42149c FW |
10971 | @section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) |
10972 | @cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) | |
41af791f GB |
10973 | @cindex OS/2 Error codes |
10974 | @cindex Interfacing, to OS/2 | |
10975 | @cindex OS/2 interfacing | |
10976 | ||
10977 | @noindent | |
10978 | This package provides definitions of the OS/2 error codes. | |
10979 | ||
10980 | @node Interfaces.Os2lib.Synchronization (i-os2syn.ads) | |
ad42149c FW |
10981 | @section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) |
10982 | @cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) | |
41af791f GB |
10983 | @cindex Interfacing, to OS/2 |
10984 | @cindex Synchronization, OS/2 | |
10985 | @cindex OS/2 synchronization primitives | |
10986 | ||
10987 | @noindent | |
10988 | This is a child package that provides definitions for interfacing | |
10989 | to the @code{OS/2} synchronization primitives. | |
10990 | ||
10991 | @node Interfaces.Os2lib.Threads (i-os2thr.ads) | |
ad42149c FW |
10992 | @section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) |
10993 | @cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) | |
41af791f GB |
10994 | @cindex Interfacing, to OS/2 |
10995 | @cindex Thread control, OS/2 | |
10996 | @cindex OS/2 thread interfacing | |
10997 | ||
10998 | @noindent | |
10999 | This is a child package that provides definitions for interfacing | |
11000 | to the @code{OS/2} thread primitives. | |
11001 | ||
11002 | @node Interfaces.Packed_Decimal (i-pacdec.ads) | |
ad42149c FW |
11003 | @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) |
11004 | @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) | |
41af791f GB |
11005 | @cindex IBM Packed Format |
11006 | @cindex Packed Decimal | |
11007 | ||
11008 | @noindent | |
11009 | This package provides a set of routines for conversions to and | |
11010 | from a packed decimal format compatible with that used on IBM | |
11011 | mainframes. | |
11012 | ||
11013 | @node Interfaces.VxWorks (i-vxwork.ads) | |
ad42149c FW |
11014 | @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) |
11015 | @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) | |
41af791f GB |
11016 | @cindex Interfacing to VxWorks |
11017 | @cindex VxWorks, interfacing | |
11018 | ||
11019 | @noindent | |
ad42149c | 11020 | This package provides a limited binding to the VxWorks API. |
41af791f | 11021 | In particular, it interfaces with the |
ad42149c FW |
11022 | VxWorks hardware interrupt facilities. |
11023 | ||
11024 | @node Interfaces.VxWorks.IO (i-vxwoio.ads) | |
11025 | @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) | |
11026 | @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) | |
11027 | @cindex Interfacing to VxWorks' I/O | |
11028 | @cindex VxWorks, I/O interfacing | |
11029 | @cindex VxWorks, Get_Immediate | |
11030 | ||
11031 | @noindent | |
11032 | This package provides a limited binding to the VxWorks' I/O API. | |
11033 | In particular, it provides procedures that enable the use of | |
11034 | Get_Immediate under VxWorks. | |
41af791f GB |
11035 | |
11036 | @node System.Address_Image (s-addima.ads) | |
ad42149c FW |
11037 | @section @code{System.Address_Image} (@file{s-addima.ads}) |
11038 | @cindex @code{System.Address_Image} (@file{s-addima.ads}) | |
41af791f GB |
11039 | @cindex Address image |
11040 | @cindex Image, of an address | |
11041 | ||
11042 | @noindent | |
11043 | This function provides a useful debugging | |
11044 | function that gives an (implementation dependent) | |
11045 | string which identifies an address. | |
11046 | ||
11047 | @node System.Assertions (s-assert.ads) | |
ad42149c FW |
11048 | @section @code{System.Assertions} (@file{s-assert.ads}) |
11049 | @cindex @code{System.Assertions} (@file{s-assert.ads}) | |
11050 | @cindex Assertions | |
11051 | @cindex Assert_Failure, exception | |
41af791f GB |
11052 | |
11053 | @noindent | |
11054 | This package provides the declaration of the exception raised | |
11055 | by an run-time assertion failure, as well as the routine that | |
11056 | is used internally to raise this assertion. | |
11057 | ||
11058 | @node System.Partition_Interface (s-parint.ads) | |
ad42149c FW |
11059 | @section @code{System.Partition_Interface} (@file{s-parint.ads}) |
11060 | @cindex @code{System.Partition_Interface} (@file{s-parint.ads}) | |
41af791f GB |
11061 | @cindex Partition intefacing functions |
11062 | ||
11063 | @noindent | |
ad42149c | 11064 | This package provides facilities for partition interfacing. It |
41af791f GB |
11065 | is used primarily in a distribution context when using Annex E |
11066 | with @code{GLADE}. | |
11067 | ||
11068 | @node System.Task_Info (s-tasinf.ads) | |
ad42149c FW |
11069 | @section @code{System.Task_Info} (@file{s-tasinf.ads}) |
11070 | @cindex @code{System.Task_Info} (@file{s-tasinf.ads}) | |
11071 | @cindex Task_Info pragma | |
41af791f GB |
11072 | |
11073 | @noindent | |
11074 | This package provides target dependent functionality that is used | |
11075 | to support the @code{Task_Info} pragma | |
11076 | ||
11077 | @node System.Wch_Cnv (s-wchcnv.ads) | |
ad42149c FW |
11078 | @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) |
11079 | @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) | |
41af791f GB |
11080 | @cindex Wide Character, Representation |
11081 | @cindex Wide String, Conversion | |
11082 | @cindex Representation of wide characters | |
11083 | ||
11084 | @noindent | |
11085 | This package provides routines for converting between | |
11086 | wide characters and a representation as a value of type | |
11087 | @code{Standard.String}, using a specified wide character | |
ad42149c FW |
11088 | encoding method. It uses definitions in |
11089 | package @code{System.Wch_Con}. | |
41af791f GB |
11090 | |
11091 | @node System.Wch_Con (s-wchcon.ads) | |
ad42149c FW |
11092 | @section @code{System.Wch_Con} (@file{s-wchcon.ads}) |
11093 | @cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) | |
41af791f GB |
11094 | |
11095 | @noindent | |
11096 | This package provides definitions and descriptions of | |
11097 | the various methods used for encoding wide characters | |
ad42149c | 11098 | in ordinary strings. These definitions are used by |
41af791f GB |
11099 | the package @code{System.Wch_Cnv}. |
11100 | ||
11101 | @node Interfacing to Other Languages | |
11102 | @chapter Interfacing to Other Languages | |
11103 | @noindent | |
11104 | The facilities in annex B of the Ada 95 Reference Manual are fully | |
11105 | implemented in GNAT, and in addition, a full interface to C++ is | |
11106 | provided. | |
11107 | ||
11108 | @menu | |
11109 | * Interfacing to C:: | |
11110 | * Interfacing to C++:: | |
11111 | * Interfacing to COBOL:: | |
11112 | * Interfacing to Fortran:: | |
11113 | * Interfacing to non-GNAT Ada code:: | |
11114 | @end menu | |
11115 | ||
11116 | @node Interfacing to C | |
11117 | @section Interfacing to C | |
11118 | ||
11119 | @noindent | |
11120 | Interfacing to C with GNAT can use one of two approaches: | |
11121 | ||
11122 | @enumerate | |
11123 | @item | |
11124 | The types in the package @code{Interfaces.C} may be used. | |
11125 | @item | |
ad42149c | 11126 | Standard Ada types may be used directly. This may be less portable to |
41af791f GB |
11127 | other compilers, but will work on all GNAT compilers, which guarantee |
11128 | correspondence between the C and Ada types. | |
11129 | @end enumerate | |
11130 | ||
11131 | @noindent | |
11132 | Pragma @code{Convention C} maybe applied to Ada types, but mostly has no | |
ad42149c | 11133 | effect, since this is the default. The following table shows the |
41af791f GB |
11134 | correspondence between Ada scalar types and the corresponding C types. |
11135 | ||
11136 | @table @code | |
11137 | @item Integer | |
11138 | @code{int} | |
11139 | @item Short_Integer | |
11140 | @code{short} | |
11141 | @item Short_Short_Integer | |
11142 | @code{signed char} | |
11143 | @item Long_Integer | |
11144 | @code{long} | |
11145 | @item Long_Long_Integer | |
11146 | @code{long long} | |
11147 | @item Short_Float | |
11148 | @code{float} | |
11149 | @item Float | |
11150 | @code{float} | |
11151 | @item Long_Float | |
11152 | @code{double} | |
11153 | @item Long_Long_Float | |
11154 | This is the longest floating-point type supported by the hardware. | |
11155 | @end table | |
11156 | ||
11157 | @itemize @bullet | |
11158 | @item | |
11159 | Ada enumeration types map to C enumeration types directly if pragma | |
11160 | @code{Convention C} is specified, which causes them to have int | |
ad42149c FW |
11161 | length. Without pragma @code{Convention C}, Ada enumeration types map to |
11162 | 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, @code{int}, respectively) | |
11163 | depending on the number of values passed. This is the only case in which | |
41af791f GB |
11164 | pragma @code{Convention C} affects the representation of an Ada type. |
11165 | ||
11166 | @item | |
11167 | Ada access types map to C pointers, except for the case of pointers to | |
11168 | unconstrained types in Ada, which have no direct C equivalent. | |
11169 | ||
11170 | @item | |
11171 | Ada arrays map directly to C arrays. | |
11172 | ||
11173 | @item | |
11174 | Ada records map directly to C structures. | |
11175 | ||
11176 | @item | |
11177 | Packed Ada records map to C structures where all members are bit fields | |
11178 | of the length corresponding to the @code{@var{type}'Size} value in Ada. | |
11179 | @end itemize | |
11180 | ||
11181 | @node Interfacing to C++ | |
11182 | @section Interfacing to C++ | |
11183 | ||
11184 | @noindent | |
11185 | The interface to C++ makes use of the following pragmas, which are | |
11186 | primarily intended to be constructed automatically using a binding generator | |
ad42149c | 11187 | tool, although it is possible to construct them by hand. Ada Core |
41af791f GB |
11188 | Technologies does not currently supply a suitable binding generator tool. |
11189 | ||
11190 | Using these pragmas it is possible to achieve complete | |
11191 | inter-operability between Ada tagged types and C class definitions. | |
11192 | See @ref{Implementation Defined Pragmas} for more details. | |
11193 | ||
11194 | @table @code | |
11195 | @item pragma CPP_Class ([Entity =>] @var{local_name}) | |
11196 | The argument denotes an entity in the current declarative region that is | |
ad42149c | 11197 | declared as a tagged or untagged record type. It indicates that the type |
41af791f GB |
11198 | corresponds to an externally declared C++ class type, and is to be laid |
11199 | out the same way that C++ would lay out the type. | |
11200 | ||
11201 | @item pragma CPP_Constructor ([Entity =>] @var{local_name}) | |
11202 | This pragma identifies an imported function (imported in the usual way | |
11203 | with pragma @code{Import}) as corresponding to a C++ constructor. | |
11204 | ||
11205 | @item pragma CPP_Vtable @dots{} | |
11206 | One @code{CPP_Vtable} pragma can be present for each component of type | |
11207 | @code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class} | |
11208 | applies. | |
11209 | @end table | |
11210 | ||
11211 | @node Interfacing to COBOL | |
11212 | @section Interfacing to COBOL | |
11213 | ||
11214 | @noindent | |
11215 | Interfacing to COBOL is achieved as described in section B.4 of | |
11216 | the Ada 95 reference manual. | |
11217 | ||
11218 | @node Interfacing to Fortran | |
11219 | @section Interfacing to Fortran | |
11220 | ||
11221 | @noindent | |
11222 | Interfacing to Fortran is achieved as described in section B.5 of the | |
ad42149c FW |
11223 | reference manual. The pragma @code{Convention Fortran}, applied to a |
11224 | multi-dimensional array causes the array to be stored in column-major | |
41af791f GB |
11225 | order as required for convenient interface to Fortran. |
11226 | ||
11227 | @node Interfacing to non-GNAT Ada code | |
11228 | @section Interfacing to non-GNAT Ada code | |
11229 | ||
ad42149c FW |
11230 | It is possible to specify the convention @code{Ada} in a pragma @code{Import} or |
11231 | pragma @code{Export}. However this refers to the calling conventions used | |
41af791f GB |
11232 | by GNAT, which may or may not be similar enough to those used by |
11233 | some other Ada 83 or Ada 95 compiler to allow interoperation. | |
11234 | ||
11235 | If arguments types are kept simple, and if the foreign compiler generally | |
11236 | follows system calling conventions, then it may be possible to integrate | |
11237 | files compiled by other Ada compilers, provided that the elaboration | |
11238 | issues are adequately addressed (for example by eliminating the | |
11239 | need for any load time elaboration). | |
11240 | ||
11241 | In particular, GNAT running on VMS is designed to | |
11242 | be highly compatible with the DEC Ada 83 compiler, so this is one | |
11243 | case in which it is possible to import foreign units of this type, | |
11244 | provided that the data items passed are restricted to simple scalar | |
11245 | values or simple record types without variants, or simple array | |
11246 | types with fixed bounds. | |
11247 | ||
11248 | @node Machine Code Insertions | |
11249 | @chapter Machine Code Insertions | |
11250 | ||
11251 | @noindent | |
11252 | Package @code{Machine_Code} provides machine code support as described | |
11253 | in the Ada 95 Reference Manual in two separate forms: | |
11254 | @itemize @bullet | |
11255 | @item | |
11256 | Machine code statements, consisting of qualified expressions that | |
11257 | fit the requirements of RM section 13.8. | |
11258 | @item | |
11259 | An intrinsic callable procedure, providing an alternative mechanism of | |
11260 | including machine instructions in a subprogram. | |
11261 | @end itemize | |
11262 | ||
11263 | The two features are similar, and both closely related to the mechanism | |
ad42149c | 11264 | provided by the asm instruction in the GNU C compiler. Full understanding |
41af791f | 11265 | and use of the facilities in this package requires understanding the asm |
ad42149c FW |
11266 | instruction as described in |
11267 | @cite{Using and Porting the GNU Compiler Collection (GCC)} by Richard | |
41af791f GB |
11268 | Stallman. Calls to the function @code{Asm} and the procedure @code{Asm} |
11269 | have identical semantic restrictions and effects as described below. | |
11270 | Both are provided so that the procedure call can be used as a statement, | |
11271 | and the function call can be used to form a code_statement. | |
11272 | ||
ad42149c | 11273 | The first example given in the GCC documentation is the C @code{asm} |
41af791f GB |
11274 | instruction: |
11275 | @smallexample | |
11276 | asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); | |
11277 | @end smallexample | |
11278 | ||
11279 | @noindent | |
11280 | The equivalent can be written for GNAT as: | |
11281 | ||
11282 | @smallexample | |
11283 | Asm ("fsinx %1 %0", | |
11284 | My_Float'Asm_Output ("=f", result), | |
11285 | My_Float'Asm_Input ("f", angle)); | |
11286 | @end smallexample | |
11287 | ||
11288 | The first argument to @code{Asm} is the assembler template, and is | |
ad42149c FW |
11289 | identical to what is used in GNU C@. This string must be a static |
11290 | expression. The second argument is the output operand list. It is | |
41af791f GB |
11291 | either a single @code{Asm_Output} attribute reference, or a list of such |
11292 | references enclosed in parentheses (technically an array aggregate of | |
11293 | such references). | |
11294 | ||
11295 | The @code{Asm_Output} attribute denotes a function that takes two | |
11296 | parameters. The first is a string, the second is the name of a variable | |
ad42149c | 11297 | of the type designated by the attribute prefix. The first (string) |
41af791f | 11298 | argument is required to be a static expression and designates the |
46b58b8c | 11299 | constraint for the parameter (e.g.@: what kind of register is |
ad42149c FW |
11300 | required). The second argument is the variable to be updated with the |
11301 | result. The possible values for constraint are the same as those used in | |
41af791f GB |
11302 | the RTL, and are dependent on the configuration file used to build the |
11303 | GCC back end. If there are no output operands, then this argument may | |
11304 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
11305 | ||
11306 | The second argument of @code{@var{my_float}'Asm_Output} functions as | |
11307 | though it were an @code{out} parameter, which is a little curious, but | |
11308 | all names have the form of expressions, so there is no syntactic | |
11309 | irregularity, even though normally functions would not be permitted | |
11310 | @code{out} parameters. The third argument is the list of input | |
ad42149c | 11311 | operands. It is either a single @code{Asm_Input} attribute reference, or |
41af791f GB |
11312 | a list of such references enclosed in parentheses (technically an array |
11313 | aggregate of such references). | |
11314 | ||
11315 | The @code{Asm_Input} attribute denotes a function that takes two | |
11316 | parameters. The first is a string, the second is an expression of the | |
ad42149c | 11317 | type designated by the prefix. The first (string) argument is required |
41af791f | 11318 | to be a static expression, and is the constraint for the parameter, |
ad42149c FW |
11319 | (e.g.@: what kind of register is required). The second argument is the |
11320 | value to be used as the input argument. The possible values for the | |
41af791f GB |
11321 | constant are the same as those used in the RTL, and are dependent on |
11322 | the configuration file used to built the GCC back end. | |
11323 | ||
11324 | If there are no input operands, this argument may either be omitted, or | |
11325 | explicitly given as @code{No_Input_Operands}. The fourth argument, not | |
11326 | present in the above example, is a list of register names, called the | |
ad42149c | 11327 | @dfn{clobber} argument. This argument, if given, must be a static string |
41af791f | 11328 | expression, and is a space or comma separated list of names of registers |
ad42149c | 11329 | that must be considered destroyed as a result of the @code{Asm} call. If |
41af791f GB |
11330 | this argument is the null string (the default value), then the code |
11331 | generator assumes that no additional registers are destroyed. | |
11332 | ||
11333 | The fifth argument, not present in the above example, called the | |
ad42149c | 11334 | @dfn{volatile} argument, is by default @code{False}. It can be set to |
41af791f GB |
11335 | the literal value @code{True} to indicate to the code generator that all |
11336 | optimizations with respect to the instruction specified should be | |
11337 | suppressed, and that in particular, for an instruction that has outputs, | |
11338 | the instruction will still be generated, even if none of the outputs are | |
ad42149c | 11339 | used. See the full description in the GCC manual for further details. |
41af791f | 11340 | |
ad42149c | 11341 | The @code{Asm} subprograms may be used in two ways. First the procedure |
41af791f | 11342 | forms can be used anywhere a procedure call would be valid, and |
ad42149c | 11343 | correspond to what the RM calls ``intrinsic'' routines. Such calls can |
41af791f GB |
11344 | be used to intersperse machine instructions with other Ada statements. |
11345 | Second, the function forms, which return a dummy value of the limited | |
11346 | private type @code{Asm_Insn}, can be used in code statements, and indeed | |
11347 | this is the only context where such calls are allowed. Code statements | |
11348 | appear as aggregates of the form: | |
11349 | ||
11350 | @smallexample | |
11351 | Asm_Insn'(Asm (@dots{})); | |
11352 | Asm_Insn'(Asm_Volatile (@dots{})); | |
11353 | @end smallexample | |
11354 | ||
11355 | In accordance with RM rules, such code statements are allowed only | |
11356 | within subprograms whose entire body consists of such statements. It is | |
11357 | not permissible to intermix such statements with other Ada statements. | |
11358 | ||
11359 | Typically the form using intrinsic procedure calls is more convenient | |
ad42149c | 11360 | and more flexible. The code statement form is provided to meet the RM |
41af791f GB |
11361 | suggestion that such a facility should be made available. The following |
11362 | is the exact syntax of the call to @code{Asm} (of course if named notation is | |
11363 | used, the arguments may be given in arbitrary order, following the | |
11364 | normal rules for use of positional and named arguments) | |
11365 | ||
11366 | @smallexample | |
11367 | ASM_CALL ::= Asm ( | |
11368 | [Template =>] static_string_EXPRESSION | |
11369 | [,[Outputs =>] OUTPUT_OPERAND_LIST ] | |
11370 | [,[Inputs =>] INPUT_OPERAND_LIST ] | |
11371 | [,[Clobber =>] static_string_EXPRESSION ] | |
11372 | [,[Volatile =>] static_boolean_EXPRESSION] ) | |
11373 | OUTPUT_OPERAND_LIST ::= | |
11374 | No_Output_Operands | |
11375 | | OUTPUT_OPERAND_ATTRIBUTE | |
11376 | | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) | |
11377 | OUTPUT_OPERAND_ATTRIBUTE ::= | |
11378 | SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) | |
11379 | INPUT_OPERAND_LIST ::= | |
11380 | No_Input_Operands | |
11381 | | INPUT_OPERAND_ATTRIBUTE | |
11382 | | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) | |
11383 | INPUT_OPERAND_ATTRIBUTE ::= | |
11384 | SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) | |
11385 | @end smallexample | |
11386 | ||
11387 | @node GNAT Implementation of Tasking | |
11388 | @chapter GNAT Implementation of Tasking | |
11389 | @menu | |
11390 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
11391 | * Ensuring Compliance with the Real-Time Annex:: | |
11392 | @end menu | |
11393 | ||
11394 | @node Mapping Ada Tasks onto the Underlying Kernel Threads | |
11395 | @section Mapping Ada Tasks onto the Underlying Kernel Threads | |
11396 | ||
11397 | GNAT run-time system comprises two layers: | |
11398 | ||
11399 | @itemize @bullet | |
11400 | @item GNARL (GNAT Run-time Layer) | |
11401 | @item GNULL (GNAT Low-level Library) | |
11402 | @end itemize | |
11403 | ||
11404 | In GNAT, Ada's tasking services rely on a platform and OS independent | |
ad42149c | 11405 | layer known as GNARL@. This code is responsible for implementing the |
41af791f GB |
11406 | correct semantics of Ada's task creation, rendezvous, protected |
11407 | operations etc. | |
11408 | ||
11409 | GNARL decomposes Ada's tasking semantics into simpler lower level | |
11410 | operations such as create a thread, set the priority of a thread, | |
ad42149c FW |
11411 | yield, create a lock, lock/unlock, etc. The spec for these low-level |
11412 | operations constitutes GNULLI, the GNULL Interface. This interface is | |
46b58b8c | 11413 | directly inspired from the POSIX real-time API@. |
41af791f GB |
11414 | |
11415 | If the underlying executive or OS implements the POSIX standard | |
11416 | faithfully, the GNULL Interface maps as is to the services offered by | |
ad42149c | 11417 | the underlying kernel. Otherwise, some target dependent glue code maps |
41af791f | 11418 | the services offered by the underlying kernel to the semantics expected |
46b58b8c | 11419 | by GNARL@. |
41af791f GB |
11420 | |
11421 | Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the | |
11422 | key point is that each Ada task is mapped on a thread in the underlying | |
ad42149c | 11423 | kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. |
41af791f GB |
11424 | |
11425 | In addition Ada task priorities map onto the underlying thread priorities. | |
11426 | Mapping Ada tasks onto the underlying kernel threads has several advantages: | |
11427 | ||
11428 | @enumerate | |
11429 | ||
11430 | @item | |
ad42149c | 11431 | The underlying scheduler is used to schedule the Ada tasks. This |
41af791f GB |
11432 | makes Ada tasks as efficient as kernel threads from a scheduling |
11433 | standpoint. | |
11434 | ||
11435 | @item | |
11436 | Interaction with code written in C containing threads is eased | |
11437 | since at the lowest level Ada tasks and C threads map onto the same | |
11438 | underlying kernel concept. | |
11439 | ||
11440 | @item | |
11441 | When an Ada task is blocked during I/O the remaining Ada tasks are | |
11442 | able to proceed. | |
11443 | ||
11444 | @item | |
11445 | On multi-processor systems Ada Tasks can execute in parallel. | |
11446 | @end enumerate | |
11447 | ||
11448 | @node Ensuring Compliance with the Real-Time Annex | |
11449 | @section Ensuring Compliance with the Real-Time Annex | |
11450 | ||
11451 | The reader will be quick to notice that while mapping Ada tasks onto | |
11452 | the underlying threads has significant advantages, it does create some | |
11453 | complications when it comes to respecting the scheduling semantics | |
11454 | specified in the real-time annex (Annex D). | |
11455 | ||
11456 | For instance Annex D requires that for the FIFO_Within_Priorities | |
11457 | scheduling policy we have: | |
11458 | ||
11459 | @smallexample | |
11460 | When the active priority of a ready task that is not running | |
11461 | changes, or the setting of its base priority takes effect, the | |
11462 | task is removed from the ready queue for its old active priority | |
11463 | and is added at the tail of the ready queue for its new active | |
11464 | priority, except in the case where the active priority is lowered | |
11465 | due to the loss of inherited priority, in which case the task is | |
11466 | added at the head of the ready queue for its new active priority. | |
11467 | @end smallexample | |
11468 | ||
11469 | While most kernels do put tasks at the end of the priority queue when | |
11470 | a task changes its priority, (which respects the main | |
11471 | FIFO_Within_Priorities requirement), almost none keep a thread at the | |
11472 | beginning of its priority queue when its priority drops from the loss | |
11473 | of inherited priority. | |
11474 | ||
11475 | As a result most vendors have provided incomplete Annex D implementations. | |
11476 | ||
11477 | The GNAT run-time, has a nice cooperative solution to this problem | |
11478 | which ensures that accurate FIFO_Within_Priorities semantics are | |
11479 | respected. | |
11480 | ||
ad42149c | 11481 | The principle is as follows. When an Ada task T is about to start |
41af791f GB |
11482 | running, it checks whether some other Ada task R with the same |
11483 | priority as T has been suspended due to the loss of priority | |
ad42149c FW |
11484 | inheritance. If this is the case, T yields and is placed at the end of |
11485 | its priority queue. When R arrives at the front of the queue it | |
41af791f GB |
11486 | executes. |
11487 | ||
11488 | Note that this simple scheme preserves the relative order of the tasks | |
11489 | that were ready to execute in the priority queue where R has been | |
11490 | placed at the end. | |
11491 | ||
11492 | @node Code generation for array aggregates | |
11493 | @chapter Code generation for array aggregates | |
11494 | ||
11495 | @menu | |
11496 | * Static constant aggregates with static bounds:: | |
11497 | * Constant aggregates with an unconstrained nominal types:: | |
11498 | * Aggregates with static bounds:: | |
11499 | * Aggregates with non-static bounds:: | |
11500 | * Aggregates in assignments statements:: | |
11501 | @end menu | |
11502 | ||
11503 | Aggregate have a rich syntax and allow the user to specify the values of | |
ad42149c | 11504 | complex data structures by means of a single construct. As a result, the |
41af791f | 11505 | code generated for aggregates can be quite complex and involve loops, case |
ad42149c | 11506 | statements and multiple assignments. In the simplest cases, however, the |
41af791f GB |
11507 | compiler will recognize aggregates whose components and constraints are |
11508 | fully static, and in those cases the compiler will generate little or no | |
ad42149c FW |
11509 | executable code. The following is an outline of the code that GNAT generates |
11510 | for various aggregate constructs. For further details, the user will find it | |
41af791f GB |
11511 | useful to examine the output produced by the -gnatG flag to see the expanded |
11512 | source that is input to the code generator. The user will also want to examine | |
11513 | the assembly code generated at various levels of optimization. | |
11514 | ||
11515 | The code generated for aggregates depends on the context, the component values, | |
ad42149c FW |
11516 | and the type. In the context of an object declaration the code generated is |
11517 | generally simpler than in the case of an assignment. As a general rule, static | |
41af791f GB |
11518 | component values and static subtypes also lead to simpler code. |
11519 | ||
11520 | @node Static constant aggregates with static bounds | |
11521 | @section Static constant aggregates with static bounds | |
11522 | ||
11523 | For the declarations: | |
11524 | @smallexample | |
11525 | type One_Dim is array (1..10) of integer; | |
11526 | ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0); | |
11527 | @end smallexample | |
11528 | ||
11529 | GNAT generates no executable code: the constant ar0 is placed in static memory. | |
11530 | The same is true for constant aggregates with named associations: | |
11531 | ||
11532 | @smallexample | |
11533 | Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1); | |
11534 | Cr3 : constant One_Dim := (others => 7777); | |
11535 | @end smallexample | |
11536 | ||
11537 | The same is true for multidimensional constant arrays such as: | |
11538 | ||
11539 | @smallexample | |
11540 | type two_dim is array (1..3, 1..3) of integer; | |
11541 | Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); | |
11542 | @end smallexample | |
11543 | ||
11544 | The same is true for arrays of one-dimensional arrays: the following are | |
11545 | static: | |
11546 | ||
11547 | @smallexample | |
11548 | type ar1b is array (1..3) of boolean; | |
11549 | type ar_ar is array (1..3) of ar1b; | |
11550 | None : constant ar1b := (others => false); -- fully static | |
11551 | None2 : constant ar_ar := (1..3 => None); -- fully static | |
11552 | @end smallexample | |
11553 | ||
11554 | However, for multidimensional aggregates with named associations, GNAT will | |
ad42149c | 11555 | generate assignments and loops, even if all associations are static. The |
41af791f GB |
11556 | following two declarations generate a loop for the first dimension, and |
11557 | individual component assignments for the second dimension: | |
11558 | ||
11559 | @smallexample | |
11560 | Zero1: constant two_dim := (1..3 => (1..3 => 0)); | |
11561 | Zero2: constant two_dim := (others => (others => 0)); | |
11562 | @end smallexample | |
11563 | ||
11564 | @node Constant aggregates with an unconstrained nominal types | |
11565 | @section Constant aggregates with an unconstrained nominal types | |
11566 | ||
11567 | In such cases the aggregate itself establishes the subtype, so that associations | |
ad42149c FW |
11568 | with @code{others} cannot be used. GNAT determines the bounds for the actual |
11569 | subtype of the aggregate, and allocates the aggregate statically as well. No | |
41af791f GB |
11570 | code is generated for the following: |
11571 | ||
11572 | @smallexample | |
11573 | type One_Unc is array (natural range <>) of integer; | |
11574 | Cr_Unc : constant One_Unc := (12,24,36); | |
11575 | @end smallexample | |
11576 | ||
11577 | @node Aggregates with static bounds | |
11578 | @section Aggregates with static bounds | |
11579 | ||
11580 | In all previous examples the aggregate was the initial (and immutable) value | |
ad42149c | 11581 | of a constant. If the aggregate initializes a variable, then code is generated |
41af791f | 11582 | for it as a combination of individual assignments and loops over the target |
ad42149c | 11583 | object. The declarations |
41af791f GB |
11584 | |
11585 | @smallexample | |
11586 | Cr_Var1 : One_Dim := (2, 5, 7, 11); | |
11587 | Cr_Var2 : One_Dim := (others > -1); | |
11588 | @end smallexample | |
11589 | ||
11590 | generate the equivalent of | |
11591 | ||
11592 | @smallexample | |
11593 | Cr_Var1 (1) := 2; | |
11594 | Cr_Var1 (2) := 3; | |
11595 | Cr_Var1 (3) := 5; | |
11596 | Cr_Var1 (4) := 11; | |
11597 | ||
11598 | for I in Cr_Var2'range loop | |
11599 | Cr_Var2 (I) := =-1; | |
11600 | end loop; | |
11601 | @end smallexample | |
11602 | ||
11603 | @node Aggregates with non-static bounds | |
11604 | @section Aggregates with non-static bounds | |
11605 | ||
11606 | If the bounds of the aggregate are not statically compatible with the bounds | |
11607 | of the nominal subtype of the target, then constraint checks have to be | |
ad42149c | 11608 | generated on the bounds. For a multidimensional array, constraint checks may |
41af791f GB |
11609 | have to be applied to sub-arrays individually, if they do not have statically |
11610 | compatible subtypes. | |
11611 | ||
11612 | @node Aggregates in assignments statements | |
11613 | @section Aggregates in assignments statements | |
11614 | ||
11615 | In general, aggregate assignment requires the construction of a temporary, | |
ad42149c | 11616 | and a copy from the temporary to the target of the assignment. This is because |
41af791f | 11617 | it is not always possible to convert the assignment into a series of individual |
ad42149c | 11618 | component assignments. For example, consider the simple case: |
41af791f GB |
11619 | |
11620 | @smallexample | |
11621 | @end smallexample | |
11622 | A := (A(2), A(1)); | |
11623 | ||
11624 | This cannot be converted into: | |
11625 | ||
11626 | @smallexample | |
11627 | A(1) := A(2); | |
11628 | A(2) := A(1); | |
11629 | @end smallexample | |
11630 | ||
11631 | So the aggregate has to be built first in a separate location, and then | |
ad42149c | 11632 | copied into the target. GNAT recognizes simple cases where this intermediate |
41af791f | 11633 | step is not required, and the assignments can be performed in place, directly |
ad42149c | 11634 | into the target. The following sufficient criteria are applied: |
41af791f GB |
11635 | |
11636 | @enumerate | |
11637 | @item The bounds of the aggregate are static, and the associations are static. | |
11638 | @item The components of the aggregate are static constants, names of | |
11639 | simple variables that are not renamings, or expressions not involving | |
11640 | indexed components whose operands obey these rules. | |
11641 | @end enumerate | |
11642 | ||
11643 | If any of these conditions are violated, the aggregate will be built in | |
11644 | a temporary (created either by the front-end or the code generator) and then | |
11645 | that temporary will be copied onto the target. | |
11646 | ||
11647 | ||
11648 | @node Specialized Needs Annexes | |
11649 | @chapter Specialized Needs Annexes | |
11650 | ||
11651 | @noindent | |
11652 | Ada 95 defines a number of specialized needs annexes, which are not | |
ad42149c | 11653 | required in all implementations. However, as described in this chapter, |
41af791f GB |
11654 | GNAT implements all of these special needs annexes: |
11655 | ||
11656 | @table @asis | |
11657 | @item Systems Programming (Annex C) | |
ad42149c | 11658 | The Systems Programming Annex is fully implemented. |
41af791f GB |
11659 | |
11660 | @item Real-Time Systems (Annex D) | |
ad42149c | 11661 | The Real-Time Systems Annex is fully implemented. |
41af791f GB |
11662 | |
11663 | @item Distributed Systems (Annex E) | |
ad42149c FW |
11664 | Stub generation is fully implemented in the GNAT compiler. In addition, |
11665 | a complete compatible PCS is available as part of the GLADE system, | |
11666 | a separate product. When the two | |
41af791f GB |
11667 | products are used in conjunction, this annex is fully implemented. |
11668 | ||
11669 | @item Information Systems (Annex F) | |
ad42149c | 11670 | The Information Systems annex is fully implemented. |
41af791f GB |
11671 | |
11672 | @item Numerics (Annex G) | |
ad42149c | 11673 | The Numerics Annex is fully implemented. |
41af791f GB |
11674 | |
11675 | @item Safety and Security (Annex H) | |
ad42149c | 11676 | The Safety and Security annex is fully implemented. |
41af791f GB |
11677 | |
11678 | @end table | |
11679 | ||
11680 | @node Compatibility Guide | |
11681 | @chapter Compatibility Guide | |
11682 | ||
11683 | @noindent | |
11684 | This chapter contains sections that describe compatibility issues between | |
11685 | GNAT and other Ada 83 and Ada 95 compilation systems, to aid in porting | |
11686 | applications developed in other Ada environments. | |
11687 | ||
11688 | @menu | |
11689 | * Compatibility with Ada 83:: | |
11690 | * Compatibility with DEC Ada 83:: | |
11691 | * Compatibility with Other Ada 95 Systems:: | |
11692 | * Representation Clauses:: | |
11693 | @end menu | |
11694 | ||
11695 | @node Compatibility with Ada 83 | |
11696 | @section Compatibility with Ada 83 | |
ad42149c | 11697 | @cindex Compatibility (between Ada 83 and Ada 95) |
41af791f GB |
11698 | |
11699 | @noindent | |
ad42149c | 11700 | Ada 95 is designed to be highly upwards compatible with Ada 83. In |
41af791f GB |
11701 | particular, the design intention is that the difficulties associated |
11702 | with moving from Ada 83 to Ada 95 should be no greater than those | |
11703 | that occur when moving from one Ada 83 system to another. | |
11704 | ||
11705 | However, there are a number of points at which there are minor | |
ad42149c | 11706 | incompatibilities. The Ada 95 Annotated Reference Manual contains |
41af791f GB |
11707 | full details of these issues, |
11708 | and should be consulted for a complete treatment. | |
11709 | In practice the | |
11710 | following are the most likely issues to be encountered. | |
11711 | ||
11712 | @table @asis | |
11713 | @item Character range | |
ad42149c | 11714 | The range of @code{Standard.Character} is now the full 256 characters of Latin-1, |
41af791f | 11715 | whereas in most Ada 83 implementations it was restricted to 128 characters. |
ad42149c | 11716 | This may show up as compile time or runtime errors. The desirable fix is to |
41af791f GB |
11717 | adapt the program to accommodate the full character set, but in some cases |
11718 | it may be convenient to define a subtype or derived type of Character that | |
11719 | covers only the restricted range. | |
ad42149c | 11720 | @cindex Latin-1 |
41af791f GB |
11721 | |
11722 | @item New reserved words | |
11723 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
11724 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
11725 | Existing Ada 83 code using any of these identifiers must be edited to | |
11726 | use some alternative name. | |
11727 | ||
11728 | @item Freezing rules | |
11729 | The rules in Ada 95 are slightly different with regard to the point at | |
11730 | which entities are frozen, and representation pragmas and clauses are | |
ad42149c | 11731 | not permitted past the freeze point. This shows up most typically in |
41af791f GB |
11732 | the form of an error message complaining that a representation item |
11733 | appears too late, and the appropriate corrective action is to move | |
11734 | the item nearer to the declaration of the entity to which it refers. | |
11735 | ||
11736 | A particular case is that representation pragmas (including the | |
ad42149c FW |
11737 | extended DEC Ada 83 compatibility pragmas such as @code{Export_Procedure}), cannot |
11738 | be applied to a subprogram body. If necessary, a separate subprogram | |
41af791f GB |
11739 | declaration must be introduced to which the pragma can be applied. |
11740 | ||
11741 | @item Optional bodies for library packages | |
11742 | In Ada 83, a package that did not require a package body was nevertheless | |
ad42149c FW |
11743 | allowed to have one. This lead to certain surprises in compiling large |
11744 | systems (situations in which the body could be unexpectedly ignored). In | |
41af791f | 11745 | Ada 95, if a package does not require a body then it is not permitted to |
ad42149c | 11746 | have a body. To fix this problem, simply remove a redundant body if it |
41af791f | 11747 | is empty, or, if it is non-empty, introduce a dummy declaration into the |
ad42149c | 11748 | spec that makes the body required. One approach is to add a private part |
41af791f GB |
11749 | to the package declaration (if necessary), and define a parameterless |
11750 | procedure called Requires_Body, which must then be given a dummy | |
11751 | procedure body in the package body, which then becomes required. | |
11752 | ||
ad42149c FW |
11753 | @item @code{Numeric_Error} is now the same as @code{Constraint_Error} |
11754 | In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. | |
41af791f | 11755 | This means that it is illegal to have separate exception handlers for |
ad42149c FW |
11756 | the two exceptions. The fix is simply to remove the handler for the |
11757 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
11758 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
41af791f GB |
11759 | |
11760 | @item Indefinite subtypes in generics | |
ad42149c | 11761 | In Ada 83, it was permissible to pass an indefinite type (e.g.@: @code{String}) as |
41af791f GB |
11762 | the actual for a generic formal private type, but then the instantiation |
11763 | would be illegal if there were any instances of declarations of variables | |
ad42149c | 11764 | of this type in the generic body. In Ada 95, to avoid this clear violation |
41af791f | 11765 | of the contract model, the generic declaration clearly indicates whether |
ad42149c FW |
11766 | or not such instantiations are permitted. If a generic formal parameter |
11767 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
41af791f | 11768 | type name, then it can be instantiated with indefinite types, but no |
ad42149c FW |
11769 | variables can be declared of this type. Any attempt to declare a variable |
11770 | will result in an illegality at the time the generic is declared. If the | |
11771 | @code{(<>)} notation is not used, then it is illegal to instantiate the generic | |
11772 | with an indefinite type. This will show up as a compile time error, and | |
11773 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
41af791f GB |
11774 | @end table |
11775 | ||
11776 | All implementations of GNAT provide a switch that causes GNAT to operate | |
ad42149c FW |
11777 | in Ada 83 mode. In this mode, some but not all compatibility problems |
11778 | of the type described above are handled automatically. For example, the | |
11779 | new Ada 95 protected keywords are not recognized in this mode. However, | |
41af791f GB |
11780 | in practice, it is usually advisable to make the necessary modifications |
11781 | to the program to remove the need for using this switch. | |
11782 | ||
11783 | @node Compatibility with Other Ada 95 Systems | |
11784 | @section Compatibility with Other Ada 95 Systems | |
11785 | ||
11786 | @noindent | |
11787 | Providing that programs avoid the use of implementation dependent and | |
11788 | implementation defined features of Ada 95, as documented in the Ada 95 | |
11789 | reference manual, there should be a high degree of portability between | |
ad42149c | 11790 | GNAT and other Ada 95 systems. The following are specific items which |
41af791f | 11791 | have proved troublesome in moving GNAT programs to other Ada 95 |
46b58b8c | 11792 | compilers, but do not affect porting code to GNAT@. |
41af791f GB |
11793 | |
11794 | @table @asis | |
11795 | @item Ada 83 Pragmas and Attributes | |
11796 | Ada 95 compilers are allowed, but not required, to implement the missing | |
11797 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
11798 | GNAT implements all such pragmas and attributes, eliminating this as | |
11799 | a compatibility concern, but some other Ada 95 compilers reject these | |
11800 | pragmas and attributes. | |
11801 | ||
11802 | @item Special-needs Annexes | |
ad42149c FW |
11803 | GNAT implements the full set of special needs annexes. At the |
11804 | current time, it is the only Ada 95 compiler to do so. This means that | |
41af791f GB |
11805 | programs making use of these features may not be portable to other Ada |
11806 | 95 compilation systems. | |
11807 | ||
11808 | @item Representation Clauses | |
11809 | Some other Ada 95 compilers implement only the minimal set of | |
ad42149c | 11810 | representation clauses required by the Ada 95 reference manual. GNAT goes |
41af791f GB |
11811 | far beyond this minimal set, as described in the next section. |
11812 | @end table | |
11813 | ||
11814 | @node Representation Clauses | |
11815 | @section Representation Clauses | |
11816 | ||
11817 | @noindent | |
11818 | The Ada 83 reference manual was quite vague in describing both the minimal | |
11819 | required implementation of representation clauses, and also their precise | |
ad42149c | 11820 | effects. The Ada 95 reference manual is much more explicit, but the minimal |
41af791f GB |
11821 | set of capabilities required in Ada 95 is quite limited. |
11822 | ||
11823 | GNAT implements the full required set of capabilities described in the | |
11824 | Ada 95 reference manual, but also goes much beyond this, and in particular | |
11825 | an effort has been made to be compatible with existing Ada 83 usage to the | |
11826 | greatest extent possible. | |
11827 | ||
11828 | A few cases exist in which Ada 83 compiler behavior is incompatible with | |
ad42149c | 11829 | requirements in the Ada 95 reference manual. These are instances of |
41af791f | 11830 | intentional or accidental dependence on specific implementation dependent |
ad42149c | 11831 | characteristics of these Ada 83 compilers. The following is a list of |
41af791f GB |
11832 | the cases most likely to arise in existing legacy Ada 83 code. |
11833 | ||
11834 | @table @asis | |
11835 | @item Implicit Packing | |
11836 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
ad42149c | 11837 | packing of an array or record. This could cause expensive implicit |
41af791f GB |
11838 | conversions for change of representation in the presence of derived |
11839 | types, and the Ada design intends to avoid this possibility. | |
11840 | Subsequent AI's were issued to make it clear that such implicit | |
11841 | change of representation in response to a Size clause is inadvisable, | |
11842 | and this recommendation is represented explicitly in the Ada 95 RM | |
46b58b8c | 11843 | as implementation advice that is followed by GNAT@. |
41af791f | 11844 | The problem will show up as an error |
ad42149c FW |
11845 | message rejecting the size clause. The fix is simply to provide |
11846 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
41af791f GB |
11847 | a Component_Size clause. |
11848 | ||
11849 | @item Meaning of Size Attribute | |
11850 | The Size attribute in Ada 95 for discrete types is defined as being the | |
ad42149c | 11851 | minimal number of bits required to hold values of the type. For example, |
41af791f | 11852 | on a 32-bit machine, the size of Natural will typically be 31 and not |
ad42149c FW |
11853 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and |
11854 | some 32 in this situation. This problem will usually show up as a compile | |
11855 | time error, but not always. It is a good idea to check all uses of the | |
11856 | 'Size attribute when porting Ada 83 code. The GNAT specific attribute | |
41af791f GB |
11857 | Object_Size can provide a useful way of duplicating the behavior of |
11858 | some Ada 83 compiler systems. | |
11859 | ||
11860 | @item Size of Access Types | |
11861 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
ad42149c FW |
11862 | and that therefore it will be the same size as a System.Address value. This |
11863 | assumption is true for GNAT in most cases with one exception. For the case of | |
41af791f | 11864 | a pointer to an unconstrained array type (where the bounds may vary from one |
ad42149c | 11865 | value of the access type to another), the default is to use a ``fat pointer'', |
41af791f | 11866 | which is represented as two separate pointers, one to the bounds, and one to |
ad42149c FW |
11867 | the array. This representation has a number of advantages, including improved |
11868 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
41af791f GB |
11869 | code which makes the assumption that, for example, pointers fit in 32 bits on |
11870 | a machine with 32-bit addressing. | |
11871 | ||
ad42149c | 11872 | To get around this problem, GNAT also permits the use of ``thin pointers'' for |
41af791f | 11873 | access types in this case (where the designated type is an unconstrained array |
ad42149c | 11874 | type). These thin pointers are indeed the same size as a System.Address value. |
41af791f GB |
11875 | To specify a thin pointer, use a size clause for the type, for example: |
11876 | ||
11877 | @smallexample | |
11878 | type X is access all String; | |
11879 | for X'Size use Standard'Address_Size; | |
11880 | @end smallexample | |
11881 | ||
11882 | @noindent | |
ad42149c FW |
11883 | which will cause the type X to be represented using a single pointer. When using |
11884 | this representation, the bounds are right behind the array. This representation | |
41af791f GB |
11885 | is slightly less efficient, and does not allow quite such flexibility in the |
11886 | use of foreign pointers or in using the Unrestricted_Access attribute to create | |
ad42149c | 11887 | pointers to non-aliased objects. But for any standard portable use of the access |
41af791f | 11888 | type it will work in a functionally correct manner and allow porting of existing |
ad42149c | 11889 | code. Note that another way of forcing a thin pointer representation is to use |
41af791f GB |
11890 | a component size clause for the element size in an array, or a record |
11891 | representation clause for an access field in a record. | |
11892 | @end table | |
11893 | ||
11894 | @node Compatibility with DEC Ada 83 | |
11895 | @section Compatibility with DEC Ada 83 | |
11896 | ||
11897 | @noindent | |
11898 | The VMS version of GNAT fully implements all the pragmas and attributes | |
11899 | provided by DEC Ada 83, as well as providing the standard DEC Ada 83 | |
ad42149c FW |
11900 | libraries, including Starlet. In addition, data layouts and parameter |
11901 | passing conventions are highly compatible. This means that porting | |
41af791f | 11902 | existing DEC Ada 83 code to GNAT in VMS systems should be easier than |
ad42149c | 11903 | most other porting efforts. The following are some of the most |
41af791f GB |
11904 | significant differences between GNAT and DEC Ada 83. |
11905 | ||
11906 | @table @asis | |
11907 | @item Default floating-point representation | |
11908 | In GNAT, the default floating-point format is IEEE, whereas in DEC Ada 83, | |
ad42149c | 11909 | it is VMS format. GNAT does implement the necessary pragmas |
41af791f GB |
11910 | (Long_Float, Float_Representation) for changing this default. |
11911 | ||
11912 | @item System | |
11913 | The package System in GNAT exactly corresponds to the definition in the | |
11914 | Ada 95 reference manual, which means that it excludes many of the | |
ad42149c | 11915 | DEC Ada 83 extensions. However, a separate package Aux_DEC is provided |
41af791f GB |
11916 | that contains the additional definitions, and a special pragma, |
11917 | Extend_System allows this package to be treated transparently as an | |
11918 | extension of package System. | |
11919 | ||
11920 | @item To_Address | |
11921 | The definitions provided by Aux_DEC are exactly compatible with those | |
ad42149c | 11922 | in the DEC Ada 83 version of System, with one exception. DEC Ada provides |
41af791f GB |
11923 | the following declarations: |
11924 | ||
11925 | @smallexample | |
11926 | TO_ADDRESS(INTEGER) | |
11927 | TO_ADDRESS(UNSIGNED_LONGWORD) | |
11928 | TO_ADDRESS(universal_integer) | |
11929 | @end smallexample | |
11930 | ||
11931 | @noindent | |
11932 | The version of TO_ADDRESS taking a universal integer argument is in fact | |
11933 | an extension to Ada 83 not strictly compatible with the reference manual. | |
11934 | In GNAT, we are constrained to be exactly compatible with the standard, | |
ad42149c | 11935 | and this means we cannot provide this capability. In DEC Ada 83, the |
41af791f GB |
11936 | point of this definition is to deal with a call like: |
11937 | ||
11938 | @smallexample | |
11939 | TO_ADDRESS (16#12777#); | |
11940 | @end smallexample | |
11941 | ||
11942 | @noindent | |
11943 | Normally, according to the Ada 83 standard, one would expect this to be | |
11944 | ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms | |
ad42149c | 11945 | of TO_ADDRESS@. However, in DEC Ada 83, there is no ambiguity, since the |
41af791f GB |
11946 | definition using universal_integer takes precedence. |
11947 | ||
11948 | In GNAT, since the version with universal_integer cannot be supplied, it is | |
ad42149c | 11949 | not possible to be 100% compatible. Since there are many programs using |
41af791f GB |
11950 | numeric constants for the argument to TO_ADDRESS, the decision in GNAT was |
11951 | to change the name of the function in the UNSIGNED_LONGWORD case, so the | |
11952 | declarations provided in the GNAT version of AUX_Dec are: | |
11953 | ||
11954 | @smallexample | |
11955 | function To_Address (X : Integer) return Address; | |
11956 | pragma Pure_Function (To_Address); | |
11957 | ||
11958 | function To_Address_Long (X : Unsigned_Longword) | |
11959 | return Address; | |
11960 | pragma Pure_Function (To_Address_Long); | |
11961 | @end smallexample | |
11962 | ||
11963 | @noindent | |
11964 | This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must | |
46b58b8c | 11965 | change the name to TO_ADDRESS_LONG@. |
41af791f GB |
11966 | |
11967 | @item Task_Id values | |
11968 | The Task_Id values assigned will be different in the two systems, and GNAT | |
11969 | does not provide a specified value for the Task_Id of the environment task, | |
11970 | which in GNAT is treated like any other declared task. | |
11971 | @end table | |
11972 | ||
11973 | For full details on these and other less significant compatibility issues, | |
ad42149c FW |
11974 | see appendix E of the Digital publication entitled @cite{DEC Ada, Technical |
11975 | Overview and Comparison on DIGITAL Platforms}. | |
41af791f GB |
11976 | |
11977 | For GNAT running on other than VMS systems, all the DEC Ada 83 pragmas and | |
11978 | attributes are recognized, although only a subset of them can sensibly | |
ad42149c | 11979 | be implemented. The description of pragmas in this reference manual |
41af791f GB |
11980 | indicates whether or not they are applicable to non-VMS systems. |
11981 | ||
5c558dd9 | 11982 | @include fdl.texi |
41af791f GB |
11983 | @c GNU Free Documentation License |
11984 | ||
11985 | @node Index,,GNU Free Documentation License, Top | |
11986 | @unnumbered Index | |
11987 | ||
11988 | @printindex cp | |
11989 | ||
11990 | @contents | |
11991 | ||
11992 | @bye |