OSDN Git Service

* MAINTAINERS: Remove chill maintainers.
[pf3gnuchains/gcc-fork.git] / gcc / f / g77.texi
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename g77.info
4
5 @set last-update 2002-02-01
6 @set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002
7
8 @include root.texi
9
10 @c This tells @include'd files that they're part of the overall G77 doc
11 @c set.  (They might be part of a higher-level doc set too.)
12 @set DOC-G77
13
14 @c @setfilename useg77.info
15 @c @setfilename portg77.info
16 @c To produce the full manual, use the "g77.info" setfilename, and
17 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
18 @set INTERNALS
19 @set USING
20 @c To produce a user-only manual, use the "useg77.info" setfilename, and
21 @c make sure the following does NOT begin with '@c':
22 @c @clear INTERNALS
23 @c To produce a porter-only manual, use the "portg77.info" setfilename,
24 @c and make sure the following does NOT begin with '@c':
25 @c @clear USING
26
27 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from gcc.texi)
28 @c @smallbook
29
30 @c i also commented out the finalout command, so if there *are* any
31 @c overfulls, you'll (hopefully) see the rectangle in the right hand
32 @c margin. -- burley 1999-03-13 (from mew's comment in gcc.texi).
33 @c @finalout
34
35 @macro gcctabopt{body}
36 @code{\body\}
37 @end macro
38 @macro gccoptlist{body}
39 @smallexample
40 \body\
41 @end smallexample
42 @end macro
43 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
44 @c they get lost at some point in handling the macro.  But if @macro is
45 @c used here rather than @alias, it produces double line breaks.
46 @iftex
47 @alias gol = *
48 @end iftex
49 @ifnottex
50 @macro gol
51 @end macro
52 @end ifnottex
53
54 @ifset INTERNALS
55 @ifset USING
56 @settitle Using and Porting GNU Fortran
57 @end ifset
58 @end ifset
59 @c seems reasonable to assume at least one of INTERNALS or USING is set...
60 @ifclear INTERNALS
61 @settitle Using GNU Fortran
62 @end ifclear
63 @ifclear USING
64 @settitle Porting GNU Fortran
65 @end ifclear
66 @c then again, have some fun
67 @ifclear INTERNALS
68 @ifclear USING
69 @settitle Doing Squat with GNU Fortran
70 @end ifclear
71 @end ifclear
72
73 @syncodeindex fn cp
74 @syncodeindex vr cp
75 @c %**end of header
76
77 @c Cause even numbered pages to be printed on the left hand side of
78 @c the page and odd numbered pages to be printed on the right hand
79 @c side of the page.  Using this, you can print on both sides of a
80 @c sheet of paper and have the text on the same part of the sheet.
81
82 @c The text on right hand pages is pushed towards the right hand
83 @c margin and the text on left hand pages is pushed toward the left
84 @c hand margin.
85 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
86
87 @c @tex
88 @c \global\bindingoffset=0.75in
89 @c \global\normaloffset =0.75in
90 @c @end tex
91
92 @ifinfo
93 @dircategory Programming
94 @direntry
95 * g77: (g77).                  The GNU Fortran compiler.
96 @end direntry
97 @ifset INTERNALS
98 @ifset USING
99 This file documents the use and the internals of the GNU Fortran (@command{g77})
100 compiler.
101 It corresponds to the @value{which-g77} version of @command{g77}.
102 @end ifset
103 @end ifset
104 @ifclear USING
105 This file documents the internals of the GNU Fortran (@command{g77}) compiler.
106 It corresponds to the @value{which-g77} version of @command{g77}.
107 @end ifclear
108 @ifclear INTERNALS
109 This file documents the use of the GNU Fortran (@command{g77}) compiler.
110 It corresponds to the @value{which-g77} version of @command{g77}.
111 @end ifclear
112
113 Published by the Free Software Foundation
114 59 Temple Place - Suite 330
115 Boston, MA 02111-1307 USA
116
117 Copyright (C) @value{copyrights-g77} Free Software Foundation, Inc.
118
119
120 Permission is granted to copy, distribute and/or modify this document
121 under the terms of the GNU Free Documentation License, Version 1.1 or
122 any later version published by the Free Software Foundation; with the
123 Invariant Sections being ``GNU General Public License'' and ``Funding
124 Free Software'', the Front-Cover
125 texts being (a) (see below), and with the Back-Cover Texts being (b)
126 (see below).  A copy of the license is included in the section entitled
127 ``GNU Free Documentation License''.
128
129 (a) The FSF's Front-Cover Text is:
130
131      A GNU Manual
132
133 (b) The FSF's Back-Cover Text is:
134
135      You have freedom to copy and modify this GNU Manual, like GNU
136      software.  Copies published by the Free Software Foundation raise
137      funds for GNU development.
138 @end ifinfo
139
140 Contributed by James Craig Burley (@email{@value{email-burley}}).
141 Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that
142 was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}).
143
144 @setchapternewpage odd
145 @c @finalout
146 @titlepage
147 @ifset INTERNALS
148 @ifset USING
149 @center @titlefont{Using and Porting GNU Fortran}
150
151 @end ifset
152 @end ifset
153 @ifclear INTERNALS
154 @title Using GNU Fortran
155 @end ifclear
156 @ifclear USING
157 @title Porting GNU Fortran
158 @end ifclear
159 @sp 2
160 @center James Craig Burley
161 @sp 3
162 @center Last updated @value{last-update}
163 @sp 1
164 @center for version @value{version-g77}
165 @page
166 @vskip 0pt plus 1filll
167 Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc.
168 @sp 2
169 For the @value{which-g77} Version*
170 @sp 1
171 Published by the Free Software Foundation @*
172 59 Temple Place - Suite 330@*
173 Boston, MA 02111-1307, USA@*
174 @c Last printed ??ber, 19??.@*
175 @c Printed copies are available for $? each.@*
176 @c ISBN ???
177 @sp 1
178 Permission is granted to copy, distribute and/or modify this document
179 under the terms of the GNU Free Documentation License, Version 1.1 or
180 any later version published by the Free Software Foundation; with the
181 Invariant Sections being ``GNU General Public License'' and ``Funding
182 Free Software'', the Front-Cover
183 texts being (a) (see below), and with the Back-Cover Texts being (b)
184 (see below).  A copy of the license is included in the section entitled
185 ``GNU Free Documentation License''.
186
187 (a) The FSF's Front-Cover Text is:
188
189      A GNU Manual
190
191 (b) The FSF's Back-Cover Text is:
192
193      You have freedom to copy and modify this GNU Manual, like GNU
194      software.  Copies published by the Free Software Foundation raise
195      funds for GNU development.
196 @end titlepage
197 @summarycontents
198 @contents
199 @page
200
201 @node Top, Copying,, (DIR)
202 @top Introduction
203 @cindex Introduction
204
205 @ifset INTERNALS
206 @ifset USING
207 This manual documents how to run, install and port @command{g77},
208 as well as its new features and incompatibilities,
209 and how to report bugs.
210 It corresponds to the @value{which-g77} version of @command{g77}.
211 @end ifset
212 @end ifset
213
214 @ifclear INTERNALS
215 This manual documents how to run and install @command{g77},
216 as well as its new features and incompatibilities, and how to report
217 bugs.
218 It corresponds to the @value{which-g77} version of @command{g77}.
219 @end ifclear
220 @ifclear USING
221 This manual documents how to port @command{g77},
222 as well as its new features and incompatibilities,
223 and how to report bugs.
224 It corresponds to the @value{which-g77} version of @command{g77}.
225 @end ifclear
226
227 @ifset DEVELOPMENT
228 @emph{Warning:} This document is still under development,
229 and might not accurately reflect the @command{g77} code base
230 of which it is a part.
231 Efforts are made to keep it somewhat up-to-date,
232 but they are particularly concentrated
233 on any version of this information
234 that is distributed as part of a @emph{released} @command{g77}.
235
236 In particular, while this document is intended to apply to
237 the @value{which-g77} version of @command{g77},
238 only an official @emph{release} of that version
239 is expected to contain documentation that is
240 most consistent with the @command{g77} product in that version.
241 @end ifset
242
243 @menu
244 * Copying::         GNU General Public License says
245                     how you can copy and share GNU Fortran.
246 * GNU Free Documentation License::
247                     How you can copy and share this manual.
248 * Contributors::    People who have contributed to GNU Fortran.
249 * Funding::         How to help assure continued work for free software.
250 * Funding GNU Fortran::  How to help assure continued work on GNU Fortran.
251 @ifset USING
252 * Getting Started:: Finding your way around this manual.
253 * What is GNU Fortran?::  How @command{g77} fits into the universe.
254 * G77 and GCC::     You can compile Fortran, C, or other programs.
255 * Invoking G77::    Command options supported by @command{g77}.
256 * News::            News about recent releases of @command{g77}.
257 * Changes::         User-visible changes to recent releases of @command{g77}.
258 * Language::        The GNU Fortran language.
259 * Compiler::        The GNU Fortran compiler.
260 * Other Dialects::  Dialects of Fortran supported by @command{g77}.
261 * Other Compilers:: Fortran compilers other than @command{g77}.
262 * Other Languages:: Languages other than Fortran.
263 * Debugging and Interfacing::  How @command{g77} generates code.
264 * Collected Fortran Wisdom::  How to avoid Trouble.
265 * Trouble::         If you have trouble with GNU Fortran.
266 * Open Questions::  Things we'd like to know.
267 * Bugs::            How, why, and where to report bugs.
268 * Service::         How to find suppliers of support for GNU Fortran.
269 @end ifset
270 @ifset INTERNALS
271 * Adding Options::  Guidance on teaching @command{g77} about new options.
272 * Projects::        Projects for @command{g77} internals hackers.
273 * Front End::       Design and implementation of the @command{g77} front end.
274 @end ifset
275
276 * M: Diagnostics.   Diagnostics produced by @command{g77}.
277
278 * Index::           Index of concepts and symbol names.
279 @end menu
280 @c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)!
281
282 @include gpl.texi
283
284 @include fdl.texi
285
286 @node Contributors
287 @unnumbered Contributors to GNU Fortran
288 @cindex contributors
289 @cindex credits
290
291 In addition to James Craig Burley, who wrote the front end,
292 many people have helped create and improve GNU Fortran.
293
294 @itemize @bullet
295 @item
296 The packaging and compiler portions of GNU Fortran are based largely
297 on the GNU CC compiler.
298 @xref{Contributors,,Contributors to GCC,gcc,Using the GNU Compiler
299 Collection (GCC)},
300 for more information.
301
302 @item
303 The run-time library used by GNU Fortran is a repackaged version
304 of the @code{libf2c} library (combined from the @code{libF77} and
305 @code{libI77} libraries) provided as part of @command{f2c}, available for
306 free from @code{netlib} sites on the Internet.
307
308 @item
309 Cygnus Support and The Free Software Foundation contributed
310 significant money and/or equipment to Craig's efforts.
311
312 @item
313 The following individuals served as alpha testers prior to @command{g77}'s
314 public release.  This work consisted of testing, researching, sometimes
315 debugging, and occasionally providing small amounts of code and fixes
316 for @command{g77}, plus offering plenty of helpful advice to Craig:
317
318 @itemize @w{}
319 @item
320 Jonathan Corbet
321 @item
322 Dr.@: Mark Fernyhough
323 @item
324 Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp}
325 @item
326 Kate Hedstrom
327 @item
328 Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr}
329 @item
330 Dr.@: A. O. V. Le Blanc
331 @item
332 Dave Love
333 @item
334 Rick Lutowski
335 @item
336 Toon Moene
337 @item
338 Rick Niles
339 @item
340 Derk Reefman
341 @item
342 Wayne K. Schroll
343 @item
344 Bill Thorson
345 @item
346 Pedro A. M. Vazquez
347 @item
348 Ian Watson
349 @end itemize
350
351 @item
352 Dave Love (@email{d.love@@dl.ac.uk})
353 wrote the libU77 part of the run-time library.
354
355 @item
356 Scott Snyder (@email{snyder@@d0sgif.fnal.gov})
357 provided the patch to add rudimentary support
358 for @code{INTEGER*1}, @code{INTEGER*2}, and
359 @code{LOGICAL*1}.
360 This inspired Craig to add further support,
361 even though the resulting support
362 would still be incomplete.
363
364 @item
365 David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired
366 and encouraged Craig to rewrite the documentation in texinfo
367 format by contributing a first pass at a translation of the
368 old @file{g77-0.5.16/f/DOC} file.
369
370 @item
371 Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed
372 some analysis of generated code as part of an overall project
373 to improve @command{g77} code generation to at least be as good
374 as @command{f2c} used in conjunction with @command{gcc}.
375 So far, this has resulted in the three, somewhat
376 experimental, options added by @command{g77} to the @command{gcc}
377 compiler and its back end.
378
379 (These, in turn, had made their way into the @code{egcs}
380 version of the compiler, and do not exist in @command{gcc}
381 version 2.8 or versions of @command{g77} based on that version
382 of @command{gcc}.)
383
384 @item
385 John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements.
386
387 @item
388 Thanks to Mary Cortani and the staff at Craftwork Solutions
389 (@email{support@@craftwork.com}) for all of their support.
390
391 @item
392 Many other individuals have helped debug, test, and improve @command{g77}
393 over the past several years, and undoubtedly more people
394 will be doing so in the future.
395 If you have done so, and would like
396 to see your name listed in the above list, please ask!
397 The default is that people wish to remain anonymous.
398 @end itemize
399
400 @include funding.texi
401
402 @node Funding GNU Fortran
403 @chapter Funding GNU Fortran
404 @cindex funding improvements
405 @cindex improvements, funding
406
407 James Craig Burley (@email{@value{email-burley}}), the original author
408 of @command{g77}, stopped working on it in September 1999
409 (He has a web page at @uref{@value{www-burley}}.)
410
411 GNU Fortran is currently maintained by Toon Moene
412 (@email{toon@@moene.indiv.nluug.nl}), with the help of countless other
413 volunteers.
414
415 As with other GNU software, funding is important because it can pay for
416 needed equipment, personnel, and so on.
417
418 @cindex FSF, funding the
419 @cindex funding the FSF
420 The FSF provides information on the best way to fund ongoing
421 development of GNU software (such as GNU Fortran) in documents
422 such as the ``GNUS Bulletin''.
423 Email @email{gnu@@gnu.org} for information on funding the FSF.
424
425 Another important way to support work on GNU Fortran is to volunteer
426 to help out.
427
428 Email @email{@value{email-general}} to volunteer for this work.
429
430 However, we strongly expect that there will never be a version 0.6
431 of @command{g77}.  Work on this compiler has stopped as of the release
432 of GCC 3.1, except for bug fixing.  @command{g77} will be succeeded by
433 @command{g95} - see @uref{http://g95.sourceforge.net}.
434
435 @xref{Funding,,Funding Free Software}, for more information.
436
437 @node Getting Started
438 @chapter Getting Started
439 @cindex getting started
440 @cindex new users
441 @cindex newbies
442 @cindex beginners
443
444 If you don't need help getting started reading the portions
445 of this manual that are most important to you, you should skip
446 this portion of the manual.
447
448 If you are new to compilers, especially Fortran compilers, or
449 new to how compilers are structured under UNIX and UNIX-like
450 systems, you'll want to see @ref{What is GNU Fortran?}.
451
452 If you are new to GNU compilers, or have used only one GNU
453 compiler in the past and not had to delve into how it lets
454 you manage various versions and configurations of @command{gcc},
455 you should see @ref{G77 and GCC}.
456
457 Everyone except experienced @command{g77} users should
458 see @ref{Invoking G77}.
459
460 If you're acquainted with previous versions of @command{g77},
461 you should see @ref{News,,News About GNU Fortran}.
462 Further, if you've actually used previous versions of @command{g77},
463 especially if you've written or modified Fortran code to
464 be compiled by previous versions of @command{g77}, you
465 should see @ref{Changes}.
466
467 If you intend to write or otherwise compile code that is
468 not already strictly conforming ANSI FORTRAN 77---and this
469 is probably everyone---you should see @ref{Language}.
470
471 If you run into trouble getting Fortran code to compile,
472 link, run, or work properly, you might find answers
473 if you see @ref{Debugging and Interfacing},
474 see @ref{Collected Fortran Wisdom},
475 and see @ref{Trouble}.
476 You might also find that the problems you are encountering
477 are bugs in @command{g77}---see @ref{Bugs}, for information on
478 reporting them, after reading the other material.
479
480 If you need further help with @command{g77}, or with
481 freely redistributable software in general,
482 see @ref{Service}.
483
484 If you would like to help the @command{g77} project,
485 see @ref{Funding GNU Fortran}, for information on
486 helping financially, and see @ref{Projects}, for information
487 on helping in other ways.
488
489 If you're generally curious about the future of
490 @command{g77}, see @ref{Projects}.
491 If you're curious about its past,
492 see @ref{Contributors},
493 and see @ref{Funding GNU Fortran}.
494
495 To see a few of the questions maintainers of @command{g77} have,
496 and that you might be able to answer,
497 see @ref{Open Questions}.
498
499 @ifset USING
500 @node What is GNU Fortran?
501 @chapter What is GNU Fortran?
502 @cindex concepts, basic
503 @cindex basic concepts
504
505 GNU Fortran, or @command{g77}, is designed initially as a free replacement
506 for, or alternative to, the UNIX @command{f77} command.
507 (Similarly, @command{gcc} is designed as a replacement
508 for the UNIX @command{cc} command.)
509
510 @command{g77} also is designed to fit in well with the other
511 fine GNU compilers and tools.
512
513 Sometimes these design goals conflict---in such cases, resolution
514 often is made in favor of fitting in well with Project GNU.
515 These cases are usually identified in the appropriate
516 sections of this manual.
517
518 @cindex compilers
519 As compilers, @command{g77}, @command{gcc}, and @command{f77}
520 share the following characteristics:
521
522 @itemize @bullet
523 @cindex source code
524 @cindex file, source
525 @cindex code, source
526 @cindex source file
527 @item
528 They read a user's program, stored in a file and
529 containing instructions written in the appropriate
530 language (Fortran, C, and so on).
531 This file contains @dfn{source code}.
532
533 @cindex translation of user programs
534 @cindex machine code
535 @cindex code, machine
536 @cindex mistakes
537 @item
538 They translate the user's program into instructions
539 a computer can carry out more quickly than it takes
540 to translate the instructions in the first place.
541 These instructions are called @dfn{machine code}---code
542 designed to be efficiently translated and processed
543 by a machine such as a computer.
544 Humans usually aren't as good writing machine code
545 as they are at writing Fortran or C, because
546 it is easy to make tiny mistakes writing machine code.
547 When writing Fortran or C, it is easy
548 to make big mistakes.
549
550 @cindex debugger
551 @cindex bugs, finding
552 @cindex @command{gdb}, command
553 @cindex commands, @command{gdb}
554 @item
555 They provide information in the generated machine code
556 that can make it easier to find bugs in the program
557 (using a debugging tool, called a @dfn{debugger},
558 such as @command{gdb}).
559
560 @cindex libraries
561 @cindex linking
562 @cindex @command{ld} command
563 @cindex commands, @command{ld}
564 @item
565 They locate and gather machine code already generated
566 to perform actions requested by statements in
567 the user's program.
568 This machine code is organized
569 into @dfn{libraries} and is located and gathered
570 during the @dfn{link} phase of the compilation
571 process.
572 (Linking often is thought of as a separate
573 step, because it can be directly invoked via the
574 @command{ld} command.
575 However, the @command{g77} and @command{gcc}
576 commands, as with most compiler commands, automatically
577 perform the linking step by calling on @command{ld}
578 directly, unless asked to not do so by the user.)
579
580 @cindex language, incorrect use of
581 @cindex incorrect use of language
582 @item
583 They attempt to diagnose cases where the user's
584 program contains incorrect usages of the language.
585 The @dfn{diagnostics} produced by the compiler
586 indicate the problem and the location in the user's
587 source file where the problem was first noticed.
588 The user can use this information to locate and
589 fix the problem.
590 @cindex diagnostics, incorrect
591 @cindex incorrect diagnostics
592 @cindex error messages, incorrect
593 @cindex incorrect error messages
594 (Sometimes an incorrect usage
595 of the language leads to a situation where the
596 compiler can no longer make any sense of what
597 follows---while a human might be able to---and
598 thus ends up complaining about many ``problems''
599 it encounters that, in fact, stem from just one
600 problem, usually the first one reported.)
601
602 @cindex warnings
603 @cindex questionable instructions
604 @item
605 They attempt to diagnose cases where the user's
606 program contains a correct usage of the language,
607 but instructs the computer to do something questionable.
608 These diagnostics often are in the form of @dfn{warnings},
609 instead of the @dfn{errors} that indicate incorrect
610 usage of the language.
611 @end itemize
612
613 How these actions are performed is generally under the
614 control of the user.
615 Using command-line options, the user can specify
616 how persnickety the compiler is to be regarding
617 the program (whether to diagnose questionable usage
618 of the language), how much time to spend making
619 the generated machine code run faster, and so on.
620
621 @cindex components of @command{g77}
622 @cindex @command{g77}, components of
623 @command{g77} consists of several components:
624
625 @cindex @command{gcc}, command
626 @cindex commands, @command{gcc}
627 @itemize @bullet
628 @item
629 A modified version of the @command{gcc} command, which also might be
630 installed as the system's @command{cc} command.
631 (In many cases, @command{cc} refers to the
632 system's ``native'' C compiler, which
633 might be a non-GNU compiler, or an older version
634 of @command{gcc} considered more stable or that is
635 used to build the operating system kernel.)
636
637 @cindex @command{g77}, command
638 @cindex commands, @command{g77}
639 @item
640 The @command{g77} command itself, which also might be installed as the
641 system's @command{f77} command.
642
643 @cindex libg2c library
644 @cindex libf2c library
645 @cindex libraries, libf2c
646 @cindex libraries, libg2c
647 @cindex run-time, library
648 @item
649 The @code{libg2c} run-time library.
650 This library contains the machine code needed to support
651 capabilities of the Fortran language that are not directly
652 provided by the machine code generated by the @command{g77}
653 compilation phase.
654
655 @code{libg2c} is just the unique name @command{g77} gives
656 to its version of @code{libf2c} to distinguish it from
657 any copy of @code{libf2c} installed from @command{f2c}
658 (or versions of @command{g77} that built @code{libf2c} under
659 that same name)
660 on the system.
661
662 The maintainer of @code{libf2c} currently is
663 @email{dmg@@bell-labs.com}.
664
665 @cindex @code{f771}, program
666 @cindex programs, @code{f771}
667 @cindex assembler
668 @cindex @command{as} command
669 @cindex commands, @command{as}
670 @cindex assembly code
671 @cindex code, assembly
672 @item
673 The compiler itself, internally named @code{f771}.
674
675 Note that @code{f771} does not generate machine code directly---it
676 generates @dfn{assembly code} that is a more readable form
677 of machine code, leaving the conversion to actual machine code
678 to an @dfn{assembler}, usually named @command{as}.
679 @end itemize
680
681 @command{gcc} is often thought of as ``the C compiler'' only,
682 but it does more than that.
683 Based on command-line options and the names given for files
684 on the command line, @command{gcc} determines which actions to perform, including
685 preprocessing, compiling (in a variety of possible languages), assembling,
686 and linking.
687
688 @cindex driver, gcc command as
689 @cindex @command{gcc}, command as driver
690 @cindex executable file
691 @cindex files, executable
692 @cindex cc1 program
693 @cindex programs, cc1
694 @cindex preprocessor
695 @cindex cpp program
696 @cindex programs, cpp
697 For example, the command @samp{gcc foo.c} @dfn{drives} the file
698 @file{foo.c} through the preprocessor @command{cpp}, then
699 the C compiler (internally named
700 @code{cc1}), then the assembler (usually @command{as}), then the linker
701 (@command{ld}), producing an executable program named @file{a.out} (on
702 UNIX systems).
703
704 @cindex cc1plus program
705 @cindex programs, cc1plus
706 As another example, the command @samp{gcc foo.cc} would do much the same as
707 @samp{gcc foo.c}, but instead of using the C compiler named @code{cc1},
708 @command{gcc} would use the C++ compiler (named @code{cc1plus}).
709
710 @cindex @code{f771}, program
711 @cindex programs, @code{f771}
712 In a GNU Fortran installation, @command{gcc} recognizes Fortran source
713 files by name just like it does C and C++ source files.
714 It knows to use the Fortran compiler named @code{f771}, instead of
715 @code{cc1} or @code{cc1plus}, to compile Fortran files.
716
717 @cindex @command{gcc}, not recognizing Fortran source
718 @cindex unrecognized file format
719 @cindex file format not recognized
720 Non-Fortran-related operation of @command{gcc} is generally
721 unaffected by installing the GNU Fortran version of @command{gcc}.
722 However, without the installed version of @command{gcc} being the
723 GNU Fortran version, @command{gcc} will not be able to compile
724 and link Fortran programs---and since @command{g77} uses @command{gcc}
725 to do most of the actual work, neither will @command{g77}!
726
727 @cindex @command{g77}, command
728 @cindex commands, @command{g77}
729 The @command{g77} command is essentially just a front-end for
730 the @command{gcc} command.
731 Fortran users will normally use @command{g77} instead of @command{gcc},
732 because @command{g77}
733 knows how to specify the libraries needed to link with Fortran programs
734 (@code{libg2c} and @code{lm}).
735 @command{g77} can still compile and link programs and
736 source files written in other languages, just like @command{gcc}.
737
738 @cindex printing version information
739 @cindex version information, printing
740 The command @samp{g77 -v} is a quick
741 way to display lots of version information for the various programs
742 used to compile a typical preprocessed Fortran source file---this
743 produces much more output than @samp{gcc -v} currently does.
744 (If it produces an error message near the end of the output---diagnostics
745 from the linker, usually @command{ld}---you might
746 have an out-of-date @code{libf2c} that improperly handles
747 complex arithmetic.)
748 In the output of this command, the line beginning @samp{GNU Fortran Front
749 End} identifies the version number of GNU Fortran; immediately
750 preceding that line is a line identifying the version of @command{gcc}
751 with which that version of @command{g77} was built.
752
753 @cindex libf2c library
754 @cindex libraries, libf2c
755 The @code{libf2c} library is distributed with GNU Fortran for
756 the convenience of its users, but is not part of GNU Fortran.
757 It contains the procedures
758 needed by Fortran programs while they are running.
759
760 @cindex in-line code
761 @cindex code, in-line
762 For example, while code generated by @command{g77} is likely
763 to do additions, subtractions, and multiplications @dfn{in line}---in
764 the actual compiled code---it is not likely to do trigonometric
765 functions this way.
766
767 Instead, operations like trigonometric
768 functions are compiled by the @code{f771} compiler
769 (invoked by @command{g77} when compiling Fortran code) into machine
770 code that, when run, calls on functions in @code{libg2c}, so
771 @code{libg2c} must be linked with almost every useful program
772 having any component compiled by GNU Fortran.
773 (As mentioned above, the @command{g77} command takes
774 care of all this for you.)
775
776 The @code{f771} program represents most of what is unique to GNU Fortran.
777 While much of the @code{libg2c} component comes from
778 the @code{libf2c} component of @command{f2c},
779 a free Fortran-to-C converter distributed by Bellcore (AT&T),
780 plus @code{libU77}, provided by Dave Love,
781 and the @command{g77} command is just a small front-end to @command{gcc},
782 @code{f771} is a combination of two rather
783 large chunks of code.
784
785 @cindex GNU Back End (GBE)
786 @cindex GBE
787 @cindex @command{gcc}, back end
788 @cindex back end, gcc
789 @cindex code generator
790 One chunk is the so-called @dfn{GNU Back End}, or GBE,
791 which knows how to generate fast code for a wide variety of processors.
792 The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1},
793 @code{cc1plus}, and @code{f771}, plus others.
794 Often the GBE is referred to as the ``gcc back end'' or
795 even just ``gcc''---in this manual, the term GBE is used
796 whenever the distinction is important.
797
798 @cindex GNU Fortran Front End (FFE)
799 @cindex FFE
800 @cindex @command{g77}, front end
801 @cindex front end, @command{g77}
802 The other chunk of @code{f771} is the
803 majority of what is unique about GNU Fortran---the code that knows how
804 to interpret Fortran programs to determine what they are intending to
805 do, and then communicate that knowledge to the GBE for actual compilation
806 of those programs.
807 This chunk is called the @dfn{Fortran Front End} (FFE).
808 The @code{cc1} and @code{cc1plus} programs have their own front ends,
809 for the C and C++ languages, respectively.
810 These fronts ends are responsible for diagnosing
811 incorrect usage of their respective languages by the
812 programs the process, and are responsible for most of
813 the warnings about questionable constructs as well.
814 (The GBE handles producing some warnings, like those
815 concerning possible references to undefined variables.)
816
817 Because so much is shared among the compilers for various languages,
818 much of the behavior and many of the user-selectable options for these
819 compilers are similar.
820 For example, diagnostics (error messages and
821 warnings) are similar in appearance; command-line
822 options like @option{-Wall} have generally similar effects; and the quality
823 of generated code (in terms of speed and size) is roughly similar
824 (since that work is done by the shared GBE).
825
826 @node G77 and GCC
827 @chapter Compile Fortran, C, or Other Programs
828 @cindex compiling programs
829 @cindex programs, compiling
830
831 @cindex @command{gcc}, command
832 @cindex commands, @command{gcc}
833 A GNU Fortran installation includes a modified version of the @command{gcc}
834 command.
835
836 In a non-Fortran installation, @command{gcc} recognizes C, C++,
837 and Objective-C source files.
838
839 In a GNU Fortran installation, @command{gcc} also recognizes Fortran source
840 files and accepts Fortran-specific command-line options, plus some
841 command-line options that are designed to cater to Fortran users
842 but apply to other languages as well.
843
844 @xref{G++ and GCC,,Compile C; C++; Objective-C; Ada; Fortran;
845 or Java,gcc,Using the GNU Compiler Collection (GCC)},
846 for information on the way different languages are handled
847 by the GNU CC compiler (@command{gcc}).
848
849 @cindex @command{g77}, command
850 @cindex commands, @command{g77}
851 Also provided as part of GNU Fortran is the @command{g77} command.
852 The @command{g77} command is designed to make compiling and linking Fortran
853 programs somewhat easier than when using the @command{gcc} command for
854 these tasks.
855 It does this by analyzing the command line somewhat and changing it
856 appropriately before submitting it to the @command{gcc} command.
857
858 @cindex -v option
859 @cindex @command{g77} options, -v
860 @cindex options, -v
861 Use the @option{-v} option with @command{g77}
862 to see what is going on---the first line of output is the invocation
863 of the @command{gcc} command.
864
865 @include invoke.texi
866
867 @include news.texi
868
869 @set USERVISONLY
870 @include news.texi
871 @clear USERVISONLY
872
873 @node Language
874 @chapter The GNU Fortran Language
875
876 @cindex standard, ANSI FORTRAN 77
877 @cindex ANSI FORTRAN 77 standard
878 @cindex reference works
879 GNU Fortran supports a variety of extensions to, and dialects
880 of, the Fortran language.
881 Its primary base is the ANSI FORTRAN 77 standard, currently available on
882 the network at
883 @uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html}
884 or as monolithic text at
885 @uref{http://www.fortran.com/fortran/F77_std/f77_std.html}.
886 It offers some extensions that are popular among users
887 of UNIX @command{f77} and @command{f2c} compilers, some that
888 are popular among users of other compilers (such as Digital
889 products), some that are popular among users of the
890 newer Fortran 90 standard, and some that are introduced
891 by GNU Fortran.
892
893 @cindex textbooks
894 (If you need a text on Fortran,
895 a few freely available electronic references have pointers from
896 @uref{http://www.fortran.com/fortran/Books/}.  There is a `cooperative
897 net project', @cite{User Notes on Fortran Programming} at
898 @uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this
899 material might not apply specifically to @command{g77}.)
900
901 Part of what defines a particular implementation of a Fortran
902 system, such as @command{g77}, is the particular characteristics
903 of how it supports types, constants, and so on.
904 Much of this is left up to the implementation by the various
905 Fortran standards and accepted practice in the industry.
906
907 The GNU Fortran @emph{language} is described below.
908 Much of the material is organized along the same lines
909 as the ANSI FORTRAN 77 standard itself.
910
911 @xref{Other Dialects}, for information on features @command{g77} supports
912 that are not part of the GNU Fortran language.
913
914 @emph{Note}: This portion of the documentation definitely needs a lot
915 of work!
916
917 @menu
918 Relationship to the ANSI FORTRAN 77 standard:
919 * Direction of Language Development::  Where GNU Fortran is headed.
920 * Standard Support::  Degree of support for the standard.
921
922 Extensions to the ANSI FORTRAN 77 standard:
923 * Conformance::
924 * Notation Used::
925 * Terms and Concepts::
926 * Characters Lines Sequence::
927 * Data Types and Constants::
928 * Expressions::
929 * Specification Statements::
930 * Control Statements::
931 * Functions and Subroutines::
932 * Scope and Classes of Names::
933 * I/O::
934 * Fortran 90 Features::
935 @end menu
936
937 @node Direction of Language Development
938 @section Direction of Language Development
939 @cindex direction of language development
940 @cindex features, language
941 @cindex language, features
942
943 The purpose of the following description of the GNU Fortran
944 language is to promote wide portability of GNU Fortran programs.
945
946 GNU Fortran is an evolving language, due to the
947 fact that @command{g77} itself is in beta test.
948 Some current features of the language might later
949 be redefined as dialects of Fortran supported by @command{g77}
950 when better ways to express these features are added to @command{g77},
951 for example.
952 Such features would still be supported by
953 @command{g77}, but would be available only when
954 one or more command-line options were used.
955
956 The GNU Fortran @emph{language} is distinct from the
957 GNU Fortran @emph{compilation system} (@command{g77}).
958
959 For example, @command{g77} supports various dialects of
960 Fortran---in a sense, these are languages other than
961 GNU Fortran---though its primary
962 purpose is to support the GNU Fortran language, which also is
963 described in its documentation and by its implementation.
964
965 On the other hand, non-GNU compilers might offer
966 support for the GNU Fortran language, and are encouraged
967 to do so.
968
969 Currently, the GNU Fortran language is a fairly fuzzy object.
970 It represents something of a cross between what @command{g77} accepts
971 when compiling using the prevailing defaults and what this
972 document describes as being part of the language.
973
974 Future versions of @command{g77} are expected to clarify the
975 definition of the language in the documentation.
976 Often, this will mean adding new features to the language, in the form
977 of both new documentation and new support in @command{g77}.
978 However, it might occasionally mean removing a feature
979 from the language itself to ``dialect'' status.
980 In such a case, the documentation would be adjusted
981 to reflect the change, and @command{g77} itself would likely be changed
982 to require one or more command-line options to continue supporting
983 the feature.
984
985 The development of the GNU Fortran language is intended to strike
986 a balance between:
987
988 @itemize @bullet
989 @item
990 Serving as a mostly-upwards-compatible language from the
991 de facto UNIX Fortran dialect as supported by @command{f77}.
992
993 @item
994 Offering new, well-designed language features.
995 Attributes of such features include
996 not making existing code any harder to read
997 (for those who might be unaware that the new
998 features are not in use) and
999 not making state-of-the-art
1000 compilers take longer to issue diagnostics,
1001 among others.
1002
1003 @item
1004 Supporting existing, well-written code without gratuitously
1005 rejecting non-standard constructs, regardless of the origin
1006 of the code (its dialect).
1007
1008 @item
1009 Offering default behavior and command-line options to reduce
1010 and, where reasonable, eliminate the need for programmers to make
1011 any modifications to code that already works in existing
1012 production environments.
1013
1014 @item
1015 Diagnosing constructs that have different meanings in different
1016 systems, languages, and dialects, while offering clear,
1017 less ambiguous ways to express each of the different meanings
1018 so programmers can change their code appropriately.
1019 @end itemize
1020
1021 One of the biggest practical challenges for the developers of the
1022 GNU Fortran language is meeting the sometimes contradictory demands
1023 of the above items.
1024
1025 For example, a feature might be widely used in one popular environment,
1026 but the exact same code that utilizes that feature might not work
1027 as expected---perhaps it might mean something entirely different---in
1028 another popular environment.
1029
1030 Traditionally, Fortran compilers---even portable ones---have solved this
1031 problem by simply offering the appropriate feature to users of
1032 the respective systems.
1033 This approach treats users of various Fortran systems and dialects
1034 as remote ``islands'', or camps, of programmers, and assume that these
1035 camps rarely come into contact with each other (or,
1036 especially, with each other's code).
1037
1038 Project GNU takes a radically different approach to software and language
1039 design, in that it assumes that users of GNU software do not necessarily
1040 care what kind of underlying system they are using, regardless
1041 of whether they are using software (at the user-interface
1042 level) or writing it (for example, writing Fortran or C code).
1043
1044 As such, GNU users rarely need consider just what kind of underlying
1045 hardware (or, in many cases, operating system) they are using at any
1046 particular time.
1047 They can use and write software designed for a general-purpose,
1048 widely portable, heterogenous environment---the GNU environment.
1049
1050 In line with this philosophy, GNU Fortran must evolve into a product
1051 that is widely ported and portable not only in the sense that it can
1052 be successfully built, installed, and run by users, but in the larger
1053 sense that its users can use it in the same way, and expect largely the
1054 same behaviors from it, regardless of the kind of system they are using
1055 at any particular time.
1056
1057 This approach constrains the solutions @command{g77} can use to resolve
1058 conflicts between various camps of Fortran users.
1059 If these two camps disagree about what a particular construct should
1060 mean, @command{g77} cannot simply be changed to treat that particular construct as
1061 having one meaning without comment (such as a warning), lest the users
1062 expecting it to have the other meaning are unpleasantly surprised that
1063 their code misbehaves when executed.
1064
1065 The use of the ASCII backslash character in character constants is
1066 an excellent (and still somewhat unresolved) example of this kind of
1067 controversy.
1068 @xref{Backslash in Constants}.
1069 Other examples are likely to arise in the future, as @command{g77} developers
1070 strive to improve its ability to accept an ever-wider variety of existing
1071 Fortran code without requiring significant modifications to said code.
1072
1073 Development of GNU Fortran is further constrained by the desire
1074 to avoid requiring programmers to change their code.
1075 This is important because it allows programmers, administrators,
1076 and others to more faithfully evaluate and validate @command{g77}
1077 (as an overall product and as new versions are distributed)
1078 without having to support multiple versions of their programs
1079 so that they continue to work the same way on their existing
1080 systems (non-GNU perhaps, but possibly also earlier versions
1081 of @command{g77}).
1082
1083 @node Standard Support
1084 @section ANSI FORTRAN 77 Standard Support
1085 @cindex ANSI FORTRAN 77 support
1086 @cindex standard, support for
1087 @cindex support, FORTRAN 77
1088 @cindex compatibility, FORTRAN 77
1089 @cindex FORTRAN 77 compatibility
1090
1091 GNU Fortran supports ANSI FORTRAN 77 with the following caveats.
1092 In summary, the only ANSI FORTRAN 77 features @command{g77} doesn't
1093 support are those that are probably rarely used in actual code,
1094 some of which are explicitly disallowed by the Fortran 90 standard.
1095
1096 @menu
1097 * No Passing External Assumed-length::  CHAR*(*) CFUNC restriction.
1098 * No Passing Dummy Assumed-length::     CHAR*(*) CFUNC restriction.
1099 * No Pathological Implied-DO::          No @samp{((@dots{}, I=@dots{}), I=@dots{})}.
1100 * No Useless Implied-DO::               No @samp{(A, I=1, 1)}.
1101 @end menu
1102
1103 @node No Passing External Assumed-length
1104 @subsection No Passing External Assumed-length
1105
1106 @command{g77} disallows passing of an external procedure
1107 as an actual argument if the procedure's
1108 type is declared @code{CHARACTER*(*)}.  For example:
1109
1110 @example
1111 CHARACTER*(*) CFUNC
1112 EXTERNAL CFUNC
1113 CALL FOO(CFUNC)
1114 END
1115 @end example
1116
1117 @noindent
1118 It isn't clear whether the standard considers this conforming.
1119
1120 @node No Passing Dummy Assumed-length
1121 @subsection No Passing Dummy Assumed-length
1122
1123 @command{g77} disallows passing of a dummy procedure
1124 as an actual argument if the procedure's
1125 type is declared @code{CHARACTER*(*)}.
1126
1127 @example
1128 SUBROUTINE BAR(CFUNC)
1129 CHARACTER*(*) CFUNC
1130 EXTERNAL CFUNC
1131 CALL FOO(CFUNC)
1132 END
1133 @end example
1134
1135 @noindent
1136 It isn't clear whether the standard considers this conforming.
1137
1138 @node No Pathological Implied-DO
1139 @subsection No Pathological Implied-DO
1140
1141 The @code{DO} variable for an implied-@code{DO} construct in a
1142 @code{DATA} statement may not be used as the @code{DO} variable
1143 for an outer implied-@code{DO} construct.  For example, this
1144 fragment is disallowed by @command{g77}:
1145
1146 @smallexample
1147 DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/
1148 @end smallexample
1149
1150 @noindent
1151 This also is disallowed by Fortran 90, as it offers no additional
1152 capabilities and would have a variety of possible meanings.
1153
1154 Note that it is @emph{very} unlikely that any production Fortran code
1155 tries to use this unsupported construct.
1156
1157 @node No Useless Implied-DO
1158 @subsection No Useless Implied-DO
1159
1160 An array element initializer in an implied-@code{DO} construct in a
1161 @code{DATA} statement must contain at least one reference to the @code{DO}
1162 variables of each outer implied-@code{DO} construct.  For example,
1163 this fragment is disallowed by @command{g77}:
1164
1165 @smallexample
1166 DATA (A, I= 1, 1) /1./
1167 @end smallexample
1168
1169 @noindent
1170 This also is disallowed by Fortran 90, as FORTRAN 77's more permissive
1171 requirements offer no additional capabilities.
1172 However, @command{g77} doesn't necessarily diagnose all cases
1173 where this requirement is not met.
1174
1175 Note that it is @emph{very} unlikely that any production Fortran code
1176 tries to use this unsupported construct.
1177
1178 @node Conformance
1179 @section Conformance
1180
1181 (The following information augments or overrides the information in
1182 Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1183 language.
1184 Chapter 1 of that document otherwise serves as the basis
1185 for the relevant aspects of GNU Fortran.)
1186
1187 The definition of the GNU Fortran language is akin to that of
1188 the ANSI FORTRAN 77 language in that it does not generally require
1189 conforming implementations to diagnose cases where programs do
1190 not conform to the language.
1191
1192 However, @command{g77} as a compiler is being developed in a way that
1193 is intended to enable it to diagnose such cases in an easy-to-understand
1194 manner.
1195
1196 A program that conforms to the GNU Fortran language should, when
1197 compiled, linked, and executed using a properly installed @command{g77}
1198 system, perform as described by the GNU Fortran language definition.
1199 Reasons for different behavior include, among others:
1200
1201 @itemize @bullet
1202 @item
1203 Use of resources (memory---heap, stack, and so on; disk space; CPU
1204 time; etc.) exceeds those of the system.
1205
1206 @item
1207 Range and/or precision of calculations required by the program
1208 exceeds that of the system.
1209
1210 @item
1211 Excessive reliance on behaviors that are system-dependent
1212 (non-portable Fortran code).
1213
1214 @item
1215 Bugs in the program.
1216
1217 @item
1218 Bug in @command{g77}.
1219
1220 @item
1221 Bugs in the system.
1222 @end itemize
1223
1224 Despite these ``loopholes'', the availability of a clear specification
1225 of the language of programs submitted to @command{g77}, as this document
1226 is intended to provide, is considered an important aspect of providing
1227 a robust, clean, predictable Fortran implementation.
1228
1229 The definition of the GNU Fortran language, while having no special
1230 legal status, can therefore be viewed as a sort of contract, or agreement.
1231 This agreement says, in essence, ``if you write a program in this language,
1232 and run it in an environment (such as a @command{g77} system) that supports
1233 this language, the program should behave in a largely predictable way''.
1234
1235 @node Notation Used
1236 @section Notation Used in This Chapter
1237
1238 (The following information augments or overrides the information in
1239 Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1240 language.
1241 Chapter 1 of that document otherwise serves as the basis
1242 for the relevant aspects of GNU Fortran.)
1243
1244 In this chapter, ``must'' denotes a requirement, ``may'' denotes permission,
1245 and ``must not'' and ``may not'' denote prohibition.
1246 Terms such as ``might'', ``should'', and ``can'' generally add little or
1247 nothing in the way of weight to the GNU Fortran language itself,
1248 but are used to explain or illustrate the language.
1249
1250 For example:
1251
1252 @display
1253 ``The @code{FROBNITZ} statement must precede all executable
1254 statements in a program unit, and may not specify any dummy
1255 arguments.  It may specify local or common variables and arrays.
1256 Its use should be limited to portions of the program designed to
1257 be non-portable and system-specific, because it might cause the
1258 containing program unit to behave quite differently on different
1259 systems.''
1260 @end display
1261
1262 Insofar as the GNU Fortran language is specified,
1263 the requirements and permissions denoted by the above sample statement
1264 are limited to the placement of the statement and the kinds of
1265 things it may specify.
1266 The rest of the statement---the content regarding non-portable portions
1267 of the program and the differing behavior of program units containing
1268 the @code{FROBNITZ} statement---does not pertain the GNU Fortran
1269 language itself.
1270 That content offers advice and warnings about the @code{FROBNITZ}
1271 statement.
1272
1273 @emph{Remember:} The GNU Fortran language definition specifies
1274 both what constitutes a valid GNU Fortran program and how,
1275 given such a program, a valid GNU Fortran implementation is
1276 to interpret that program.
1277
1278 It is @emph{not} incumbent upon a valid GNU Fortran implementation
1279 to behave in any particular way, any consistent way, or any
1280 predictable way when it is asked to interpret input that is
1281 @emph{not} a valid GNU Fortran program.
1282
1283 Such input is said to have @dfn{undefined} behavior when
1284 interpreted by a valid GNU Fortran implementation, though
1285 an implementation may choose to specify behaviors for some
1286 cases of inputs that are not valid GNU Fortran programs.
1287
1288 Other notation used herein is that of the GNU texinfo format,
1289 which is used to generate printed hardcopy, on-line hypertext
1290 (Info), and on-line HTML versions, all from a single source
1291 document.
1292 This notation is used as follows:
1293
1294 @itemize @bullet
1295 @item
1296 Keywords defined by the GNU Fortran language are shown
1297 in uppercase, as in: @code{COMMON}, @code{INTEGER}, and
1298 @code{BLOCK DATA}.
1299
1300 Note that, in practice, many Fortran programs are written
1301 in lowercase---uppercase is used in this manual as a
1302 means to readily distinguish keywords and sample Fortran-related
1303 text from the prose in this document.
1304
1305 @item
1306 Portions of actual sample program, input, or output text
1307 look like this: @samp{Actual program text}.
1308
1309 Generally, uppercase is used for all Fortran-specific and
1310 Fortran-related text, though this does not always include
1311 literal text within Fortran code.
1312
1313 For example: @samp{PRINT *, 'My name is Bob'}.
1314
1315 @item
1316 A metasyntactic variable---that is, a name used in this document
1317 to serve as a placeholder for whatever text is used by the
1318 user or programmer---appears as shown in the following example:
1319
1320 ``The @code{INTEGER @var{ivar}} statement specifies that
1321 @var{ivar} is a variable or array of type @code{INTEGER}.''
1322
1323 In the above example, any valid text may be substituted for
1324 the metasyntactic variable @var{ivar} to make the statement
1325 apply to a specific instance, as long as the same text is
1326 substituted for @emph{both} occurrences of @var{ivar}.
1327
1328 @item
1329 Ellipses (``@dots{}'') are used to indicate further text that
1330 is either unimportant or expanded upon further, elsewhere.
1331
1332 @item
1333 Names of data types are in the style of Fortran 90, in most
1334 cases.
1335
1336 @xref{Kind Notation}, for information on the relationship
1337 between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)})
1338 and the more traditional, less portably concise nomenclature
1339 (such as @code{INTEGER*4}).
1340 @end itemize
1341
1342 @node Terms and Concepts
1343 @section Fortran Terms and Concepts
1344
1345 (The following information augments or overrides the information in
1346 Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1347 language.
1348 Chapter 2 of that document otherwise serves as the basis
1349 for the relevant aspects of GNU Fortran.)
1350
1351 @menu
1352 * Syntactic Items::
1353 * Statements Comments Lines::
1354 * Scope of Names and Labels::
1355 @end menu
1356
1357 @node Syntactic Items
1358 @subsection Syntactic Items
1359
1360 (Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.)
1361
1362 @cindex limits, lengths of names
1363 In GNU Fortran, a symbolic name is at least one character long,
1364 and has no arbitrary upper limit on length.
1365 However, names of entities requiring external linkage (such as
1366 external functions, external subroutines, and @code{COMMON} areas)
1367 might be restricted to some arbitrary length by the system.
1368 Such a restriction is no more constrained than that of one
1369 through six characters.
1370
1371 Underscores (@samp{_}) are accepted in symbol names after the first
1372 character (which must be a letter).
1373
1374 @node Statements Comments Lines
1375 @subsection Statements, Comments, and Lines
1376
1377 (Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.)
1378
1379 @cindex trailing comment
1380 @cindex comment
1381 @cindex characters, comment
1382 @cindex !
1383 @cindex exclamation point
1384 @cindex continuation character
1385 @cindex characters, continuation
1386 Use of an exclamation point (@samp{!}) to begin a
1387 trailing comment (a comment that extends to the end of the same
1388 source line) is permitted under the following conditions:
1389
1390 @itemize @bullet
1391 @item
1392 The exclamation point does not appear in column 6.
1393 Otherwise, it is treated as an indicator of a continuation
1394 line.
1395
1396 @item
1397 The exclamation point appears outside a character or Hollerith
1398 constant.
1399 Otherwise, the exclamation point is considered part of the
1400 constant.
1401
1402 @item
1403 The exclamation point appears to the left of any other possible
1404 trailing comment.
1405 That is, a trailing comment may contain exclamation points
1406 in their commentary text.
1407 @end itemize
1408
1409 @cindex ;
1410 @cindex semicolon
1411 @cindex statements, separated by semicolon
1412 Use of a semicolon (@samp{;}) as a statement separator
1413 is permitted under the following conditions:
1414
1415 @itemize @bullet
1416 @item
1417 The semicolon appears outside a character or Hollerith
1418 constant.
1419 Otherwise, the semicolon is considered part of the
1420 constant.
1421
1422 @item
1423 The semicolon appears to the left of a trailing comment.
1424 Otherwise, the semicolon is considered part of that
1425 comment.
1426
1427 @item
1428 Neither a logical @code{IF} statement nor a non-construct
1429 @code{WHERE} statement (a Fortran 90 feature) may be
1430 followed (in the same, possibly continued, line) by
1431 a semicolon used as a statement separator.
1432
1433 This restriction avoids the confusion
1434 that can result when reading a line such as:
1435
1436 @smallexample
1437 IF (VALIDP) CALL FOO; CALL BAR
1438 @end smallexample
1439
1440 @noindent
1441 Some readers might think the @samp{CALL BAR} is executed
1442 only if @samp{VALIDP} is @code{.TRUE.}, while others might
1443 assume its execution is unconditional.
1444
1445 (At present, @command{g77} does not diagnose code that
1446 violates this restriction.)
1447 @end itemize
1448
1449 @node Scope of Names and Labels
1450 @subsection Scope of Symbolic Names and Statement Labels
1451 @cindex scope
1452
1453 (Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.)
1454
1455 Included in the list of entities that have a scope of a
1456 program unit are construct names (a Fortran 90 feature).
1457 @xref{Construct Names}, for more information.
1458
1459 @node Characters Lines Sequence
1460 @section Characters, Lines, and Execution Sequence
1461
1462 (The following information augments or overrides the information in
1463 Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1464 language.
1465 Chapter 3 of that document otherwise serves as the basis
1466 for the relevant aspects of GNU Fortran.)
1467
1468 @menu
1469 * Character Set::
1470 * Lines::
1471 * Continuation Line::
1472 * Statements::
1473 * Statement Labels::
1474 * Order::
1475 * INCLUDE::
1476 * Cpp-style directives::
1477 @end menu
1478
1479 @node Character Set
1480 @subsection GNU Fortran Character Set
1481 @cindex characters
1482
1483 (Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.)
1484
1485 Letters include uppercase letters (the twenty-six characters
1486 of the English alphabet) and lowercase letters (their lowercase
1487 equivalent).
1488 Generally, lowercase letters may be used in place of uppercase
1489 letters, though in character and Hollerith constants, they
1490 are distinct.
1491
1492 Special characters include:
1493
1494 @itemize @bullet
1495 @item
1496 @cindex ;
1497 @cindex semicolon
1498 Semicolon (@samp{;})
1499
1500 @item
1501 @cindex !
1502 @cindex exclamation point
1503 Exclamation point (@samp{!})
1504
1505 @item
1506 @cindex "
1507 @cindex double quote
1508 Double quote (@samp{"})
1509
1510 @item
1511 @cindex \
1512 @cindex backslash
1513 Backslash (@samp{\})
1514
1515 @item
1516 @cindex ?
1517 @cindex question mark
1518 Question mark (@samp{?})
1519
1520 @item
1521 @cindex #
1522 @cindex hash mark
1523 @cindex pound sign
1524 Hash mark (@samp{#})
1525
1526 @item
1527 @cindex &
1528 @cindex ampersand
1529 Ampersand (@samp{&})
1530
1531 @item
1532 @cindex %
1533 @cindex percent sign
1534 Percent sign (@samp{%})
1535
1536 @item
1537 @cindex _
1538 @cindex underscore
1539 Underscore (@samp{_})
1540
1541 @item
1542 @cindex <
1543 @cindex open angle
1544 @cindex left angle
1545 @cindex open bracket
1546 @cindex left bracket
1547 Open angle (@samp{<})
1548
1549 @item
1550 @cindex >
1551 @cindex close angle
1552 @cindex right angle
1553 @cindex close bracket
1554 @cindex right bracket
1555 Close angle (@samp{>})
1556
1557 @item
1558 The FORTRAN 77 special characters (@key{SPC}, @samp{=},
1559 @samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(},
1560 @samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'},
1561 and @samp{:})
1562 @end itemize
1563
1564 @cindex blank
1565 @cindex space
1566 @cindex SPC
1567 Note that this document refers to @key{SPC} as @dfn{space},
1568 while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}.
1569
1570 @node Lines
1571 @subsection Lines
1572 @cindex lines
1573 @cindex source file format
1574 @cindex source format
1575 @cindex file, source
1576 @cindex source code
1577 @cindex code, source
1578 @cindex fixed form
1579 @cindex free form
1580
1581 (Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.)
1582
1583 The way a Fortran compiler views source files depends entirely on the
1584 implementation choices made for the compiler, since those choices
1585 are explicitly left to the implementation by the published Fortran
1586 standards.
1587
1588 The GNU Fortran language mandates a view applicable to UNIX-like
1589 text files---files that are made up of an arbitrary number of lines,
1590 each with an arbitrary number of characters (sometimes called stream-based
1591 files).
1592
1593 This view does not apply to types of files that are specified as
1594 having a particular number of characters on every single line (sometimes
1595 referred to as record-based files).
1596
1597 Because a ``line in a program unit is a sequence of 72 characters'',
1598 to quote X3.9-1978, the GNU Fortran language specifies that a
1599 stream-based text file is translated to GNU Fortran lines as follows:
1600
1601 @itemize @bullet
1602 @item
1603 A newline in the file is the character that represents the end of
1604 a line of text to the underlying system.
1605 For example, on ASCII-based systems, a newline is the @key{NL}
1606 character, which has ASCII value 10 (decimal).
1607
1608 @item
1609 Each newline in the file serves to end the line of text that precedes
1610 it (and that does not contain a newline).
1611
1612 @item
1613 The end-of-file marker (@code{EOF}) also serves to end the line
1614 of text that precedes it (and that does not contain a newline).
1615
1616 @item
1617 @cindex blank
1618 @cindex space
1619 @cindex SPC
1620 Any line of text that is shorter than 72 characters is padded to that length
1621 with spaces (called ``blanks'' in the standard).
1622
1623 @item
1624 Any line of text that is longer than 72 characters is truncated to that
1625 length, but the truncated remainder must consist entirely of spaces.
1626
1627 @item
1628 Characters other than newline and the GNU Fortran character set
1629 are invalid.
1630 @end itemize
1631
1632 For the purposes of the remainder of this description of the GNU
1633 Fortran language, the translation described above has already
1634 taken place, unless otherwise specified.
1635
1636 The result of the above translation is that the source file appears,
1637 in terms of the remainder of this description of the GNU Fortran language,
1638 as if it had an arbitrary
1639 number of 72-character lines, each character being among the GNU Fortran
1640 character set.
1641
1642 For example, if the source file itself has two newlines in a row,
1643 the second newline becomes, after the above translation, a single
1644 line containing 72 spaces.
1645
1646 @node Continuation Line
1647 @subsection Continuation Line
1648 @cindex continuation line, number of
1649 @cindex lines, continuation
1650 @cindex number of continuation lines
1651 @cindex limits, continuation lines
1652
1653 (Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.)
1654
1655 A continuation line is any line that both
1656
1657 @itemize @bullet
1658 @item
1659 Contains a continuation character, and
1660
1661 @item
1662 Contains only spaces in columns 1 through 5
1663 @end itemize
1664
1665 A continuation character is any character of the GNU Fortran character set
1666 other than space (@key{SPC}) or zero (@samp{0})
1667 in column 6, or a digit (@samp{0} through @samp{9}) in column
1668 7 through 72 of a line that has only spaces to the left of that
1669 digit.
1670
1671 The continuation character is ignored as far as the content of
1672 the statement is concerned.
1673
1674 The GNU Fortran language places no limit on the number of
1675 continuation lines in a statement.
1676 In practice, the limit depends on a variety of factors, such as
1677 available memory, statement content, and so on, but no
1678 GNU Fortran system may impose an arbitrary limit.
1679
1680 @node Statements
1681 @subsection Statements
1682
1683 (Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.)
1684
1685 Statements may be written using an arbitrary number of continuation
1686 lines.
1687
1688 Statements may be separated using the semicolon (@samp{;}), except
1689 that the logical @code{IF} and non-construct @code{WHERE} statements
1690 may not be separated from subsequent statements using only a semicolon
1691 as statement separator.
1692
1693 The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION},
1694 and @code{END BLOCK DATA} statements are alternatives to the @code{END}
1695 statement.
1696 These alternatives may be written as normal statements---they are not
1697 subject to the restrictions of the @code{END} statement.
1698
1699 However, no statement other than @code{END} may have an initial line
1700 that appears to be an @code{END} statement---even @code{END PROGRAM},
1701 for example, must not be written as:
1702
1703 @example
1704       END
1705      &PROGRAM
1706 @end example
1707
1708 @node Statement Labels
1709 @subsection Statement Labels
1710
1711 (Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.)
1712
1713 A statement separated from its predecessor via a semicolon may be
1714 labeled as follows:
1715
1716 @itemize @bullet
1717 @item
1718 The semicolon is followed by the label for the statement,
1719 which in turn follows the label.
1720
1721 @item
1722 The label must be no more than five digits in length.
1723
1724 @item
1725 The first digit of the label for the statement is not
1726 the first non-space character on a line.
1727 Otherwise, that character is treated as a continuation
1728 character.
1729 @end itemize
1730
1731 A statement may have only one label defined for it.
1732
1733 @node Order
1734 @subsection Order of Statements and Lines
1735
1736 (Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.)
1737
1738 Generally, @code{DATA} statements may precede executable statements.
1739 However, specification statements pertaining to any entities
1740 initialized by a @code{DATA} statement must precede that @code{DATA}
1741 statement.
1742 For example,
1743 after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but
1744 @samp{INTEGER J} is permitted.
1745
1746 The last line of a program unit may be an @code{END} statement,
1747 or may be:
1748
1749 @itemize @bullet
1750 @item
1751 An @code{END PROGRAM} statement, if the program unit is a main program.
1752
1753 @item
1754 An @code{END SUBROUTINE} statement, if the program unit is a subroutine.
1755
1756 @item
1757 An @code{END FUNCTION} statement, if the program unit is a function.
1758
1759 @item
1760 An @code{END BLOCK DATA} statement, if the program unit is a block data.
1761 @end itemize
1762
1763 @node INCLUDE
1764 @subsection Including Source Text
1765 @cindex INCLUDE directive
1766
1767 Additional source text may be included in the processing of
1768 the source file via the @code{INCLUDE} directive:
1769
1770 @example
1771 INCLUDE @var{filename}
1772 @end example
1773
1774 @noindent
1775 The source text to be included is identified by @var{filename},
1776 which is a literal GNU Fortran character constant.
1777 The meaning and interpretation of @var{filename} depends on the
1778 implementation, but typically is a filename.
1779
1780 (@command{g77} treats it as a filename that it searches for
1781 in the current directory and/or directories specified
1782 via the @option{-I} command-line option.)
1783
1784 The effect of the @code{INCLUDE} directive is as if the
1785 included text directly replaced the directive in the source
1786 file prior to interpretation of the program.
1787 Included text may itself use @code{INCLUDE}.
1788 The depth of nested @code{INCLUDE} references depends on
1789 the implementation, but typically is a positive integer.
1790
1791 This virtual replacement treats the statements and @code{INCLUDE}
1792 directives in the included text as syntactically distinct from
1793 those in the including text.
1794
1795 Therefore, the first non-comment line of the included text
1796 must not be a continuation line.
1797 The included text must therefore have, after the non-comment
1798 lines, either an initial line (statement), an @code{INCLUDE}
1799 directive, or nothing (the end of the included text).
1800
1801 Similarly, the including text may end the @code{INCLUDE}
1802 directive with a semicolon or the end of the line, but it
1803 cannot follow an @code{INCLUDE} directive at the end of its
1804 line with a continuation line.
1805 Thus, the last statement in an included text may not be
1806 continued.
1807
1808 Any statements between two @code{INCLUDE} directives on the
1809 same line are treated as if they appeared in between the
1810 respective included texts.
1811 For example:
1812
1813 @smallexample
1814 INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM
1815 @end smallexample
1816
1817 @noindent
1818 If the text included by @samp{INCLUDE 'A'} constitutes
1819 a @samp{PRINT *, 'A'} statement and the text included by
1820 @samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement,
1821 then the output of the above sample program would be
1822
1823 @example
1824 A
1825 B
1826 C
1827 @end example
1828
1829 @noindent
1830 (with suitable allowances for how an implementation defines
1831 its handling of output).
1832
1833 Included text must not include itself directly or indirectly,
1834 regardless of whether the @var{filename} used to reference
1835 the text is the same.
1836
1837 Note that @code{INCLUDE} is @emph{not} a statement.
1838 As such, it is neither a non-executable or executable
1839 statement.
1840 However, if the text it includes constitutes one or more
1841 executable statements, then the placement of @code{INCLUDE}
1842 is subject to effectively the same restrictions as those
1843 on executable statements.
1844
1845 An @code{INCLUDE} directive may be continued across multiple
1846 lines as if it were a statement.
1847 This permits long names to be used for @var{filename}.
1848
1849 @node Cpp-style directives
1850 @subsection Cpp-style directives
1851 @cindex #
1852 @cindex preprocessor
1853
1854 @code{cpp} output-style @code{#} directives
1855 (@pxref{C Preprocessor Output,,, cpp, The C Preprocessor})
1856 are recognized by the compiler even
1857 when the preprocessor isn't run on the input (as it is when compiling
1858 @samp{.F} files).  (Note the distinction between these @command{cpp}
1859 @code{#} @emph{output} directives and @code{#line} @emph{input}
1860 directives.)
1861
1862 @node Data Types and Constants
1863 @section Data Types and Constants
1864
1865 (The following information augments or overrides the information in
1866 Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1867 language.
1868 Chapter 4 of that document otherwise serves as the basis
1869 for the relevant aspects of GNU Fortran.)
1870
1871 To more concisely express the appropriate types for
1872 entities, this document uses the more concise
1873 Fortran 90 nomenclature such as @code{INTEGER(KIND=1)}
1874 instead of the more traditional, but less portably concise,
1875 byte-size-based nomenclature such as @code{INTEGER*4},
1876 wherever reasonable.
1877
1878 When referring to generic types---in contexts where the
1879 specific precision and range of a type are not important---this
1880 document uses the generic type names @code{INTEGER}, @code{LOGICAL},
1881 @code{REAL}, @code{COMPLEX}, and @code{CHARACTER}.
1882
1883 In some cases, the context requires specification of a
1884 particular type.
1885 This document uses the @samp{KIND=} notation to accomplish
1886 this throughout, sometimes supplying the more traditional
1887 notation for clarification, though the traditional notation
1888 might not work the same way on all GNU Fortran implementations.
1889
1890 Use of @samp{KIND=} makes this document more concise because
1891 @command{g77} is able to define values for @samp{KIND=} that
1892 have the same meanings on all systems, due to the way the
1893 Fortran 90 standard specifies these values are to be used.
1894
1895 (In particular, that standard permits an implementation to
1896 arbitrarily assign nonnegative values.
1897 There are four distinct sets of assignments: one to the @code{CHARACTER}
1898 type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type;
1899 and the fourth to both the @code{REAL} and @code{COMPLEX} types.
1900 Implementations are free to assign these values in any order,
1901 leave gaps in the ordering of assignments, and assign more than
1902 one value to a representation.)
1903
1904 This makes @samp{KIND=} values superior to the values used
1905 in non-standard statements such as @samp{INTEGER*4}, because
1906 the meanings of the values in those statements vary from machine
1907 to machine, compiler to compiler, even operating system to
1908 operating system.
1909
1910 However, use of @samp{KIND=} is @emph{not} generally recommended
1911 when writing portable code (unless, for example, the code is
1912 going to be compiled only via @command{g77}, which is a widely
1913 ported compiler).
1914 GNU Fortran does not yet have adequate language constructs to
1915 permit use of @samp{KIND=} in a fashion that would make the
1916 code portable to Fortran 90 implementations; and, this construct
1917 is known to @emph{not} be accepted by many popular FORTRAN 77
1918 implementations, so it cannot be used in code that is to be ported
1919 to those.
1920
1921 The distinction here is that this document is able to use
1922 specific values for @samp{KIND=} to concisely document the
1923 types of various operations and operands.
1924
1925 A Fortran program should use the FORTRAN 77 designations for the
1926 appropriate GNU Fortran types---such as @code{INTEGER} for
1927 @code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)},
1928 and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and,
1929 where no such designations exist, make use of appropriate
1930 techniques (preprocessor macros, parameters, and so on)
1931 to specify the types in a fashion that may be easily adjusted
1932 to suit each particular implementation to which the program
1933 is ported.
1934 (These types generally won't need to be adjusted for ports of
1935 @command{g77}.)
1936
1937 Further details regarding GNU Fortran data types and constants
1938 are provided below.
1939
1940 @menu
1941 * Types::
1942 * Constants::
1943 * Integer Type::
1944 * Character Type::
1945 @end menu
1946
1947 @node Types
1948 @subsection Data Types
1949
1950 (Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.)
1951
1952 GNU Fortran supports these types:
1953
1954 @enumerate
1955 @item
1956 Integer (generic type @code{INTEGER})
1957
1958 @item
1959 Real (generic type @code{REAL})
1960
1961 @item
1962 Double precision
1963
1964 @item
1965 Complex (generic type @code{COMPLEX})
1966
1967 @item
1968 Logical (generic type @code{LOGICAL})
1969
1970 @item
1971 Character (generic type @code{CHARACTER})
1972
1973 @item
1974 Double Complex
1975 @end enumerate
1976
1977 (The types numbered 1 through 6 above are standard FORTRAN 77 types.)
1978
1979 The generic types shown above are referred to in this document
1980 using only their generic type names.
1981 Such references usually indicate that any specific type (kind)
1982 of that generic type is valid.
1983
1984 For example, a context described in this document as accepting
1985 the @code{COMPLEX} type also is likely to accept the
1986 @code{DOUBLE COMPLEX} type.
1987
1988 The GNU Fortran language supports three ways to specify
1989 a specific kind of a generic type.
1990
1991 @menu
1992 * Double Notation::  As in @code{DOUBLE COMPLEX}.
1993 * Star Notation::    As in @code{INTEGER*4}.
1994 * Kind Notation::    As in @code{INTEGER(KIND=1)}.
1995 @end menu
1996
1997 @node Double Notation
1998 @subsubsection Double Notation
1999
2000 The GNU Fortran language supports two uses of the keyword
2001 @code{DOUBLE} to specify a specific kind of type:
2002
2003 @itemize @bullet
2004 @item
2005 @code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)}
2006
2007 @item
2008 @code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)}
2009 @end itemize
2010
2011 Use one of the above forms where a type name is valid.
2012
2013 While use of this notation is popular, it doesn't scale
2014 well in a language or dialect rich in intrinsic types,
2015 as is the case for the GNU Fortran language (especially
2016 planned future versions of it).
2017
2018 After all, one rarely sees type names such as @samp{DOUBLE INTEGER},
2019 @samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}.
2020 Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1}
2021 often are substituted for these, respectively, even though they
2022 do not always have the same meanings on all systems.
2023 (And, the fact that @samp{DOUBLE REAL} does not exist as such
2024 is an inconsistency.)
2025
2026 Therefore, this document uses ``double notation'' only on occasion
2027 for the benefit of those readers who are accustomed to it.
2028
2029 @node Star Notation
2030 @subsubsection Star Notation
2031 @cindex *@var{n} notation
2032
2033 The following notation specifies the storage size for a type:
2034
2035 @smallexample
2036 @var{generic-type}*@var{n}
2037 @end smallexample
2038
2039 @noindent
2040 @var{generic-type} must be a generic type---one of
2041 @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
2042 or @code{CHARACTER}.
2043 @var{n} must be one or more digits comprising a decimal
2044 integer number greater than zero.
2045
2046 Use the above form where a type name is valid.
2047
2048 The @samp{*@var{n}} notation specifies that the amount of storage
2049 occupied by variables and array elements of that type is @var{n}
2050 times the storage occupied by a @code{CHARACTER*1} variable.
2051
2052 This notation might indicate a different degree of precision and/or
2053 range for such variables and array elements, and the functions that
2054 return values of types using this notation.
2055 It does not limit the precision or range of values of that type
2056 in any particular way---use explicit code to do that.
2057
2058 Further, the GNU Fortran language requires no particular values
2059 for @var{n} to be supported by an implementation via the @samp{*@var{n}}
2060 notation.
2061 @command{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)})
2062 on all systems, for example,
2063 but not all implementations are required to do so, and @command{g77}
2064 is known to not support @code{REAL*1} on most (or all) systems.
2065
2066 As a result, except for @var{generic-type} of @code{CHARACTER},
2067 uses of this notation should be limited to isolated
2068 portions of a program that are intended to handle system-specific
2069 tasks and are expected to be non-portable.
2070
2071 (Standard FORTRAN 77 supports the @samp{*@var{n}} notation for
2072 only @code{CHARACTER}, where it signifies not only the amount
2073 of storage occupied, but the number of characters in entities
2074 of that type.
2075 However, almost all Fortran compilers have supported this
2076 notation for generic types, though with a variety of meanings
2077 for @var{n}.)
2078
2079 Specifications of types using the @samp{*@var{n}} notation
2080 always are interpreted as specifications of the appropriate
2081 types described in this document using the @samp{KIND=@var{n}}
2082 notation, described below.
2083
2084 While use of this notation is popular, it doesn't serve well
2085 in the context of a widely portable dialect of Fortran, such as
2086 the GNU Fortran language.
2087
2088 For example, even on one particular machine, two or more popular
2089 Fortran compilers might well disagree on the size of a type
2090 declared @code{INTEGER*2} or @code{REAL*16}.
2091 Certainly there
2092 is known to be disagreement over such things among Fortran
2093 compilers on @emph{different} systems.
2094
2095 Further, this notation offers no elegant way to specify sizes
2096 that are not even multiples of the ``byte size'' typically
2097 designated by @code{INTEGER*1}.
2098 Use of ``absurd'' values (such as @code{INTEGER*1000}) would
2099 certainly be possible, but would perhaps be stretching the original
2100 intent of this notation beyond the breaking point in terms
2101 of widespread readability of documentation and code making use
2102 of it.
2103
2104 Therefore, this document uses ``star notation'' only on occasion
2105 for the benefit of those readers who are accustomed to it.
2106
2107 @node Kind Notation
2108 @subsubsection Kind Notation
2109 @cindex KIND= notation
2110
2111 The following notation specifies the kind-type selector of a type:
2112
2113 @smallexample
2114 @var{generic-type}(KIND=@var{n})
2115 @end smallexample
2116
2117 @noindent
2118 Use the above form where a type name is valid.
2119
2120 @var{generic-type} must be a generic type---one of
2121 @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
2122 or @code{CHARACTER}.
2123 @var{n} must be an integer initialization expression that
2124 is a positive, nonzero value.
2125
2126 Programmers are discouraged from writing these values directly
2127 into their code.
2128 Future versions of the GNU Fortran language will offer
2129 facilities that will make the writing of code portable
2130 to @command{g77} @emph{and} Fortran 90 implementations simpler.
2131
2132 However, writing code that ports to existing FORTRAN 77
2133 implementations depends on avoiding the @samp{KIND=} construct.
2134
2135 The @samp{KIND=} construct is thus useful in the context
2136 of GNU Fortran for two reasons:
2137
2138 @itemize @bullet
2139 @item
2140 It provides a means to specify a type in a fashion that
2141 is portable across all GNU Fortran implementations (though
2142 not other FORTRAN 77 and Fortran 90 implementations).
2143
2144 @item
2145 It provides a sort of Rosetta stone for this document to use
2146 to concisely describe the types of various operations and
2147 operands.
2148 @end itemize
2149
2150 The values of @var{n} in the GNU Fortran language are
2151 assigned using a scheme that:
2152
2153 @itemize @bullet
2154 @item
2155 Attempts to maximize the ability of readers
2156 of this document to quickly familiarize themselves
2157 with assignments for popular types
2158
2159 @item
2160 Provides a unique value for each specific desired
2161 meaning
2162
2163 @item
2164 Provides a means to automatically assign new values so
2165 they have a ``natural'' relationship to existing values,
2166 if appropriate, or, if no such relationship exists, will
2167 not interfere with future values assigned on the basis
2168 of such relationships
2169
2170 @item
2171 Avoids using values that are similar to values used
2172 in the existing, popular @samp{*@var{n}} notation,
2173 to prevent readers from expecting that these implied
2174 correspondences work on all GNU Fortran implementations
2175 @end itemize
2176
2177 The assignment system accomplishes this by assigning
2178 to each ``fundamental meaning'' of a specific type a
2179 unique prime number.
2180 Combinations of fundamental meanings---for example, a type
2181 that is two times the size of some other type---are assigned
2182 values of @var{n} that are the products of the values for
2183 those fundamental meanings.
2184
2185 A prime value of @var{n} is never given more than one fundamental
2186 meaning, to avoid situations where some code or system
2187 cannot reasonably provide those meanings in the form of a
2188 single type.
2189
2190 The values of @var{n} assigned so far are:
2191
2192 @table @code
2193 @item KIND=0
2194 This value is reserved for future use.
2195
2196 The planned future use is for this value to designate,
2197 explicitly, context-sensitive kind-type selection.
2198 For example, the expression @samp{1D0 * 0.1_0} would
2199 be equivalent to @samp{1D0 * 0.1D0}.
2200
2201 @item KIND=1
2202 This corresponds to the default types for
2203 @code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX},
2204 and @code{CHARACTER}, as appropriate.
2205
2206 These are the ``default'' types described in the Fortran 90 standard,
2207 though that standard does not assign any particular @samp{KIND=}
2208 value to these types.
2209
2210 (Typically, these are @code{REAL*4}, @code{INTEGER*4},
2211 @code{LOGICAL*4}, and @code{COMPLEX*8}.)
2212
2213 @item KIND=2
2214 This corresponds to types that occupy twice as much
2215 storage as the default types.
2216 @code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}),
2217 @code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}),
2218
2219 These are the ``double precision'' types described in the Fortran 90
2220 standard,
2221 though that standard does not assign any particular @samp{KIND=}
2222 value to these types.
2223
2224 @var{n} of 4 thus corresponds to types that occupy four times
2225 as much storage as the default types, @var{n} of 8 to types that
2226 occupy eight times as much storage, and so on.
2227
2228 The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types
2229 are not necessarily supported by every GNU Fortran implementation.
2230
2231 @item KIND=3
2232 This corresponds to types that occupy as much
2233 storage as the default @code{CHARACTER} type,
2234 which is the same effective type as @code{CHARACTER(KIND=1)}
2235 (making that type effectively the same as @code{CHARACTER(KIND=3)}).
2236
2237 (Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.)
2238
2239 @var{n} of 6 thus corresponds to types that occupy twice as
2240 much storage as the @var{n}=3 types, @var{n} of 12 to types
2241 that occupy four times as much storage, and so on.
2242
2243 These are not necessarily supported by every GNU Fortran
2244 implementation.
2245
2246 @item KIND=5
2247 This corresponds to types that occupy half the
2248 storage as the default (@var{n}=1) types.
2249
2250 (Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.)
2251
2252 @var{n} of 25 thus corresponds to types that occupy one-quarter
2253 as much storage as the default types.
2254
2255 These are not necessarily supported by every GNU Fortran
2256 implementation.
2257
2258 @item KIND=7
2259 @cindex pointers
2260 This is valid only as @code{INTEGER(KIND=7)} and
2261 denotes the @code{INTEGER} type that has the smallest
2262 storage size that holds a pointer on the system.
2263
2264 A pointer representable by this type is capable of uniquely
2265 addressing a @code{CHARACTER*1} variable, array, array element,
2266 or substring.
2267
2268 (Typically this is equivalent to @code{INTEGER*4} or,
2269 on 64-bit systems, @code{INTEGER*8}.
2270 In a compatible C implementation, it typically would
2271 be the same size and semantics of the C type @code{void *}.)
2272 @end table
2273
2274 Note that these are @emph{proposed} correspondences and might change
2275 in future versions of @command{g77}---avoid writing code depending
2276 on them while @command{g77}, and therefore the GNU Fortran language
2277 it defines, is in beta testing.
2278
2279 Values not specified in the above list are reserved to
2280 future versions of the GNU Fortran language.
2281
2282 Implementation-dependent meanings will be assigned new,
2283 unique prime numbers so as to not interfere with other
2284 implementation-dependent meanings, and offer the possibility
2285 of increasing the portability of code depending on such
2286 types by offering support for them in other GNU Fortran
2287 implementations.
2288
2289 Other meanings that might be given unique values are:
2290
2291 @itemize @bullet
2292 @item
2293 Types that make use of only half their storage size for
2294 representing precision and range.
2295
2296 For example, some compilers offer options that cause
2297 @code{INTEGER} types to occupy the amount of storage
2298 that would be needed for @code{INTEGER(KIND=2)} types, but the
2299 range remains that of @code{INTEGER(KIND=1)}.
2300
2301 @item
2302 The IEEE single floating-point type.
2303
2304 @item
2305 Types with a specific bit pattern (endianness), such as the
2306 little-endian form of @code{INTEGER(KIND=1)}.
2307 These could permit, conceptually, use of portable code and
2308 implementations on data files written by existing systems.
2309 @end itemize
2310
2311 Future @emph{prime} numbers should be given meanings in as incremental
2312 a fashion as possible, to allow for flexibility and
2313 expressiveness in combining types.
2314
2315 For example, instead of defining a prime number for little-endian
2316 IEEE doubles, one prime number might be assigned the meaning
2317 ``little-endian'', another the meaning ``IEEE double'', and the
2318 value of @var{n} for a little-endian IEEE double would thus
2319 naturally be the product of those two respective assigned values.
2320 (It could even be reasonable to have IEEE values result from the
2321 products of prime values denoting exponent and fraction sizes
2322 and meanings, hidden bit usage, availability and representations
2323 of special values such as subnormals, infinities, and Not-A-Numbers
2324 (NaNs), and so on.)
2325
2326 This assignment mechanism, while not inherently required for
2327 future versions of the GNU Fortran language, is worth using
2328 because it could ease management of the ``space'' of supported
2329 types much easier in the long run.
2330
2331 The above approach suggests a mechanism for specifying inheritance
2332 of intrinsic (built-in) types for an entire, widely portable
2333 product line.
2334 It is certainly reasonable that, unlike programmers of other languages
2335 offering inheritance mechanisms that employ verbose names for classes
2336 and subclasses, along with graphical browsers to elucidate the
2337 relationships, Fortran programmers would employ
2338 a mechanism that works by multiplying prime numbers together
2339 and finding the prime factors of such products.
2340
2341 Most of the advantages for the above scheme have been explained
2342 above.
2343 One disadvantage is that it could lead to the defining,
2344 by the GNU Fortran language, of some fairly large prime numbers.
2345 This could lead to the GNU Fortran language being declared
2346 ``munitions'' by the United States Department of Defense.
2347
2348 @node Constants
2349 @subsection Constants
2350 @cindex constants
2351 @cindex types, constants
2352
2353 (Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.)
2354
2355 A @dfn{typeless constant} has one of the following forms:
2356
2357 @smallexample
2358 '@var{binary-digits}'B
2359 '@var{octal-digits}'O
2360 '@var{hexadecimal-digits}'Z
2361 '@var{hexadecimal-digits}'X
2362 @end smallexample
2363
2364 @noindent
2365 @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
2366 are nonempty strings of characters in the set @samp{01}, @samp{01234567},
2367 and @samp{0123456789ABCDEFabcdef}, respectively.
2368 (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
2369 is 11, and so on.)
2370
2371 A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be
2372 treated as typeless.  @xref{Fortran Dialect Options,, Options
2373 Controlling Fortran Dialect}, for information on the
2374 @option{-ftypeless-boz} option.
2375
2376 Typeless constants have values that depend on the context in which
2377 they are used.
2378
2379 All other constants, called @dfn{typed constants}, are interpreted---converted
2380 to internal form---according to their inherent type.
2381 Thus, context is @emph{never} a determining factor for the type, and hence
2382 the interpretation, of a typed constant.
2383 (All constants in the ANSI FORTRAN 77 language are typed constants.)
2384
2385 For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU
2386 Fortran (called default INTEGER in Fortran 90),
2387 @samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the
2388 additional precision specified is lost, and even when used in a
2389 @code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)},
2390 and @samp{1D0} is always type @code{REAL(KIND=2)}.
2391
2392 @node Integer Type
2393 @subsection Integer Type
2394
2395 (Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.)
2396
2397 An integer constant also may have one of the following forms:
2398
2399 @smallexample
2400 B'@var{binary-digits}'
2401 O'@var{octal-digits}'
2402 Z'@var{hexadecimal-digits}'
2403 X'@var{hexadecimal-digits}'
2404 @end smallexample
2405
2406 @noindent
2407 @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
2408 are nonempty strings of characters in the set @samp{01}, @samp{01234567},
2409 and @samp{0123456789ABCDEFabcdef}, respectively.
2410 (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
2411 is 11, and so on.)
2412
2413 @node Character Type
2414 @subsection Character Type
2415
2416 (Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.)
2417
2418 @cindex double quoted character constants
2419 A character constant may be delimited by a pair of double quotes
2420 (@samp{"}) instead of apostrophes.
2421 In this case, an apostrophe within the constant represents
2422 a single apostrophe, while a double quote is represented in
2423 the source text of the constant by two consecutive double
2424 quotes with no intervening spaces.
2425
2426 @cindex zero-length CHARACTER
2427 @cindex null CHARACTER strings
2428 @cindex empty CHARACTER strings
2429 @cindex strings, empty
2430 @cindex CHARACTER, null
2431 A character constant may be empty (have a length of zero).
2432
2433 A character constant may include a substring specification,
2434 The value of such a constant is the value of the substring---for
2435 example, the value of @samp{'hello'(3:5)} is the same
2436 as the value of @samp{'llo'}.
2437
2438 @node Expressions
2439 @section Expressions
2440
2441 (The following information augments or overrides the information in
2442 Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2443 language.
2444 Chapter 6 of that document otherwise serves as the basis
2445 for the relevant aspects of GNU Fortran.)
2446
2447 @menu
2448 * %LOC()::
2449 @end menu
2450
2451 @node %LOC()
2452 @subsection The @code{%LOC()} Construct
2453 @cindex %LOC() construct
2454
2455 @example
2456 %LOC(@var{arg})
2457 @end example
2458
2459 The @code{%LOC()} construct is an expression
2460 that yields the value of the location of its argument,
2461 @var{arg}, in memory.
2462 The size of the type of the expression depends on the system---typically,
2463 it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)},
2464 though it is actually type @code{INTEGER(KIND=7)}.
2465
2466 The argument to @code{%LOC()} must be suitable as the
2467 left-hand side of an assignment statement.
2468 That is, it may not be a general expression involving
2469 operators such as addition, subtraction, and so on,
2470 nor may it be a constant.
2471
2472 Use of @code{%LOC()} is recommended only for code that
2473 is accessing facilities outside of GNU Fortran, such as
2474 operating system or windowing facilities.
2475 It is best to constrain such uses to isolated portions of
2476 a program---portions that deal specifically and exclusively
2477 with low-level, system-dependent facilities.
2478 Such portions might well provide a portable interface for
2479 use by the program as a whole, but are themselves not
2480 portable, and should be thoroughly tested each time they
2481 are rebuilt using a new compiler or version of a compiler.
2482
2483 Do not depend on @code{%LOC()} returning a pointer that
2484 can be safely used to @emph{define} (change) the argument.
2485 While this might work in some circumstances, it is hard
2486 to predict whether it will continue to work when a program
2487 (that works using this unsafe behavior)
2488 is recompiled using different command-line options or
2489 a different version of @command{g77}.
2490
2491 Generally, @code{%LOC()} is safe when used as an argument
2492 to a procedure that makes use of the value of the corresponding
2493 dummy argument only during its activation, and only when
2494 such use is restricted to referencing (reading) the value
2495 of the argument to @code{%LOC()}.
2496
2497 @emph{Implementation Note:} Currently, @command{g77} passes
2498 arguments (those not passed using a construct such as @code{%VAL()})
2499 by reference or descriptor, depending on the type of
2500 the actual argument.
2501 Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would
2502 seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and
2503 in fact might compile to identical code.
2504
2505 However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means
2506 ``pass, by value, the address of @samp{I} in memory''.
2507 While @samp{CALL FOO(I)} might use that same approach in a
2508 particular version of @command{g77}, another version or compiler
2509 might choose a different implementation, such as copy-in/copy-out,
2510 to effect the desired behavior---and which will therefore not
2511 necessarily compile to the same code as would
2512 @samp{CALL FOO(%VAL(%LOC(I)))}
2513 using the same version or compiler.
2514
2515 @xref{Debugging and Interfacing}, for detailed information on
2516 how this particular version of @command{g77} implements various
2517 constructs.
2518
2519 @node Specification Statements
2520 @section Specification Statements
2521
2522 (The following information augments or overrides the information in
2523 Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2524 language.
2525 Chapter 8 of that document otherwise serves as the basis
2526 for the relevant aspects of GNU Fortran.)
2527
2528 @menu
2529 * NAMELIST::
2530 * DOUBLE COMPLEX::
2531 @end menu
2532
2533 @node NAMELIST
2534 @subsection @code{NAMELIST} Statement
2535 @cindex NAMELIST statement
2536 @cindex statements, NAMELIST
2537
2538 The @code{NAMELIST} statement, and related I/O constructs, are
2539 supported by the GNU Fortran language in essentially the same
2540 way as they are by @command{f2c}.
2541
2542 This follows Fortran 90 with the restriction that on @code{NAMELIST}
2543 input, subscripts must have the form
2544 @smallexample
2545 @var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]]
2546 @end smallexample
2547 i.e.@:
2548 @smallexample
2549 &xx x(1:3,8:10:2)=1,2,3,4,5,6/
2550 @end smallexample
2551 is allowed, but not, say,
2552 @smallexample
2553 &xx x(:3,8::2)=1,2,3,4,5,6/
2554 @end smallexample
2555
2556 As an extension of the Fortran 90 form, @code{$} and @code{$END} may be
2557 used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that
2558 @smallexample
2559 $&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end
2560 @end smallexample
2561 could be used instead of the example above.
2562
2563 @node DOUBLE COMPLEX
2564 @subsection @code{DOUBLE COMPLEX} Statement
2565 @cindex DOUBLE COMPLEX
2566
2567 @code{DOUBLE COMPLEX} is a type-statement (and type) that
2568 specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran.
2569
2570 @node Control Statements
2571 @section Control Statements
2572
2573 (The following information augments or overrides the information in
2574 Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2575 language.
2576 Chapter 11 of that document otherwise serves as the basis
2577 for the relevant aspects of GNU Fortran.)
2578
2579 @menu
2580 * DO WHILE::
2581 * END DO::
2582 * Construct Names::
2583 * CYCLE and EXIT::
2584 @end menu
2585
2586 @node DO WHILE
2587 @subsection DO WHILE
2588 @cindex DO WHILE
2589 @cindex DO
2590 @cindex MIL-STD 1753
2591
2592 The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and
2593 Fortran 90 standards, is provided by the GNU Fortran language.
2594 The Fortran 90 ``do forever'' statement comprising just @code{DO} is
2595 also supported.
2596
2597 @node END DO
2598 @subsection END DO
2599 @cindex END DO
2600 @cindex MIL-STD 1753
2601
2602 The @code{END DO} statement is provided by the GNU Fortran language.
2603
2604 This statement is used in one of two ways:
2605
2606 @itemize @bullet
2607 @item
2608 The Fortran 90 meaning, in which it specifies the termination
2609 point of a single @code{DO} loop started with a @code{DO} statement
2610 that specifies no termination label.
2611
2612 @item
2613 The MIL-STD 1753 meaning, in which it specifies the termination
2614 point of one or more @code{DO} loops, all of which start with a
2615 @code{DO} statement that specify the label defined for the
2616 @code{END DO} statement.
2617
2618 This kind of @code{END DO} statement is merely a synonym for
2619 @code{CONTINUE}, except it is permitted only when the statement
2620 is labeled and a target of one or more labeled @code{DO} loops.
2621
2622 It is expected that this use of @code{END DO} will be removed from
2623 the GNU Fortran language in the future, though it is likely that
2624 it will long be supported by @command{g77} as a dialect form.
2625 @end itemize
2626
2627 @node Construct Names
2628 @subsection Construct Names
2629 @cindex construct names
2630
2631 The GNU Fortran language supports construct names as defined
2632 by the Fortran 90 standard.
2633 These names are local to the program unit and are defined
2634 as follows:
2635
2636 @smallexample
2637 @var{construct-name}: @var{block-statement}
2638 @end smallexample
2639
2640 @noindent
2641 Here, @var{construct-name} is the construct name itself;
2642 its definition is connoted by the single colon (@samp{:}); and
2643 @var{block-statement} is an @code{IF}, @code{DO},
2644 or @code{SELECT CASE} statement that begins a block.
2645
2646 A block that is given a construct name must also specify the
2647 same construct name in its termination statement:
2648
2649 @example
2650 END @var{block} @var{construct-name}
2651 @end example
2652
2653 @noindent
2654 Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT},
2655 as appropriate.
2656
2657 @node CYCLE and EXIT
2658 @subsection The @code{CYCLE} and @code{EXIT} Statements
2659
2660 @cindex CYCLE statement
2661 @cindex EXIT statement
2662 @cindex statements, CYCLE
2663 @cindex statements, EXIT
2664 The @code{CYCLE} and @code{EXIT} statements specify that
2665 the remaining statements in the current iteration of a
2666 particular active (enclosing) @code{DO} loop are to be skipped.
2667
2668 @code{CYCLE} specifies that these statements are skipped,
2669 but the @code{END DO} statement that marks the end of the
2670 @code{DO} loop be executed---that is, the next iteration,
2671 if any, is to be started.
2672 If the statement marking the end of the @code{DO} loop is
2673 not @code{END DO}---in other words, if the loop is not
2674 a block @code{DO}---the @code{CYCLE} statement does not
2675 execute that statement, but does start the next iteration (if any).
2676
2677 @code{EXIT} specifies that the loop specified by the
2678 @code{DO} construct is terminated.
2679
2680 The @code{DO} loop affected by @code{CYCLE} and @code{EXIT}
2681 is the innermost enclosing @code{DO} loop when the following
2682 forms are used:
2683
2684 @example
2685 CYCLE
2686 EXIT
2687 @end example
2688
2689 Otherwise, the following forms specify the construct name
2690 of the pertinent @code{DO} loop:
2691
2692 @example
2693 CYCLE @var{construct-name}
2694 EXIT @var{construct-name}
2695 @end example
2696
2697 @code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO}
2698 statements.
2699 However, they cannot be easily thought of as @code{GO TO} statements
2700 in obscure cases involving FORTRAN 77 loops.
2701 For example:
2702
2703 @smallexample
2704       DO 10 I = 1, 5
2705       DO 10 J = 1, 5
2706          IF (J .EQ. 5) EXIT
2707       DO 10 K = 1, 5
2708          IF (K .EQ. 3) CYCLE
2709 10    PRINT *, 'I=', I, ' J=', J, ' K=', K
2710 20    CONTINUE
2711 @end smallexample
2712
2713 @noindent
2714 In particular, neither the @code{EXIT} nor @code{CYCLE} statements
2715 above are equivalent to a @code{GO TO} statement to either label
2716 @samp{10} or @samp{20}.
2717
2718 To understand the effect of @code{CYCLE} and @code{EXIT} in the
2719 above fragment, it is helpful to first translate it to its equivalent
2720 using only block @code{DO} loops:
2721
2722 @smallexample
2723       DO I = 1, 5
2724          DO J = 1, 5
2725             IF (J .EQ. 5) EXIT
2726             DO K = 1, 5
2727                IF (K .EQ. 3) CYCLE
2728 10             PRINT *, 'I=', I, ' J=', J, ' K=', K
2729             END DO
2730          END DO
2731       END DO
2732 20    CONTINUE
2733 @end smallexample
2734
2735 Adding new labels allows translation of @code{CYCLE} and @code{EXIT}
2736 to @code{GO TO} so they may be more easily understood by programmers
2737 accustomed to FORTRAN coding:
2738
2739 @smallexample
2740       DO I = 1, 5
2741          DO J = 1, 5
2742             IF (J .EQ. 5) GOTO 18
2743             DO K = 1, 5
2744                IF (K .EQ. 3) GO TO 12
2745 10             PRINT *, 'I=', I, ' J=', J, ' K=', K
2746 12          END DO
2747          END DO
2748 18    END DO
2749 20    CONTINUE
2750 @end smallexample
2751
2752 @noindent
2753 Thus, the @code{CYCLE} statement in the innermost loop skips over
2754 the @code{PRINT} statement as it begins the next iteration of the
2755 loop, while the @code{EXIT} statement in the middle loop ends that
2756 loop but @emph{not} the outermost loop.
2757
2758 @node Functions and Subroutines
2759 @section Functions and Subroutines
2760
2761 (The following information augments or overrides the information in
2762 Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2763 language.
2764 Chapter 15 of that document otherwise serves as the basis
2765 for the relevant aspects of GNU Fortran.)
2766
2767 @menu
2768 * %VAL()::
2769 * %REF()::
2770 * %DESCR()::
2771 * Generics and Specifics::
2772 * REAL() and AIMAG() of Complex::
2773 * CMPLX() of DOUBLE PRECISION::
2774 * MIL-STD 1753::
2775 * f77/f2c Intrinsics::
2776 * Table of Intrinsic Functions::
2777 @end menu
2778
2779 @node %VAL()
2780 @subsection The @code{%VAL()} Construct
2781 @cindex %VAL() construct
2782
2783 @example
2784 %VAL(@var{arg})
2785 @end example
2786
2787 The @code{%VAL()} construct specifies that an argument,
2788 @var{arg}, is to be passed by value, instead of by reference
2789 or descriptor.
2790
2791 @code{%VAL()} is restricted to actual arguments in
2792 invocations of external procedures.
2793
2794 Use of @code{%VAL()} is recommended only for code that
2795 is accessing facilities outside of GNU Fortran, such as
2796 operating system or windowing facilities.
2797 It is best to constrain such uses to isolated portions of
2798 a program---portions the deal specifically and exclusively
2799 with low-level, system-dependent facilities.
2800 Such portions might well provide a portable interface for
2801 use by the program as a whole, but are themselves not
2802 portable, and should be thoroughly tested each time they
2803 are rebuilt using a new compiler or version of a compiler.
2804
2805 @emph{Implementation Note:} Currently, @command{g77} passes
2806 all arguments either by reference or by descriptor.
2807
2808 Thus, use of @code{%VAL()} tends to be restricted to cases
2809 where the called procedure is written in a language other
2810 than Fortran that supports call-by-value semantics.
2811 (C is an example of such a language.)
2812
2813 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)},
2814 for detailed information on
2815 how this particular version of @command{g77} passes arguments
2816 to procedures.
2817
2818 @node %REF()
2819 @subsection The @code{%REF()} Construct
2820 @cindex %REF() construct
2821
2822 @example
2823 %REF(@var{arg})
2824 @end example
2825
2826 The @code{%REF()} construct specifies that an argument,
2827 @var{arg}, is to be passed by reference, instead of by
2828 value or descriptor.
2829
2830 @code{%REF()} is restricted to actual arguments in
2831 invocations of external procedures.
2832
2833 Use of @code{%REF()} is recommended only for code that
2834 is accessing facilities outside of GNU Fortran, such as
2835 operating system or windowing facilities.
2836 It is best to constrain such uses to isolated portions of
2837 a program---portions the deal specifically and exclusively
2838 with low-level, system-dependent facilities.
2839 Such portions might well provide a portable interface for
2840 use by the program as a whole, but are themselves not
2841 portable, and should be thoroughly tested each time they
2842 are rebuilt using a new compiler or version of a compiler.
2843
2844 Do not depend on @code{%REF()} supplying a pointer to the
2845 procedure being invoked.
2846 While that is a likely implementation choice, other
2847 implementation choices are available that preserve Fortran
2848 pass-by-reference semantics without passing a pointer to
2849 the argument, @var{arg}.
2850 (For example, a copy-in/copy-out implementation.)
2851
2852 @emph{Implementation Note:} Currently, @command{g77} passes
2853 all arguments
2854 (other than variables and arrays of type @code{CHARACTER})
2855 by reference.
2856 Future versions of, or dialects supported by, @command{g77} might
2857 not pass @code{CHARACTER} functions by reference.
2858
2859 Thus, use of @code{%REF()} tends to be restricted to cases
2860 where @var{arg} is type @code{CHARACTER} but the called
2861 procedure accesses it via a means other than the method
2862 used for Fortran @code{CHARACTER} arguments.
2863
2864 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
2865 how this particular version of @command{g77} passes arguments
2866 to procedures.
2867
2868 @node %DESCR()
2869 @subsection The @code{%DESCR()} Construct
2870 @cindex %DESCR() construct
2871
2872 @example
2873 %DESCR(@var{arg})
2874 @end example
2875
2876 The @code{%DESCR()} construct specifies that an argument,
2877 @var{arg}, is to be passed by descriptor, instead of by
2878 value or reference.
2879
2880 @code{%DESCR()} is restricted to actual arguments in
2881 invocations of external procedures.
2882
2883 Use of @code{%DESCR()} is recommended only for code that
2884 is accessing facilities outside of GNU Fortran, such as
2885 operating system or windowing facilities.
2886 It is best to constrain such uses to isolated portions of
2887 a program---portions the deal specifically and exclusively
2888 with low-level, system-dependent facilities.
2889 Such portions might well provide a portable interface for
2890 use by the program as a whole, but are themselves not
2891 portable, and should be thoroughly tested each time they
2892 are rebuilt using a new compiler or version of a compiler.
2893
2894 Do not depend on @code{%DESCR()} supplying a pointer
2895 and/or a length passed by value
2896 to the procedure being invoked.
2897 While that is a likely implementation choice, other
2898 implementation choices are available that preserve the
2899 pass-by-reference semantics without passing a pointer to
2900 the argument, @var{arg}.
2901 (For example, a copy-in/copy-out implementation.)
2902 And, future versions of @command{g77} might change the
2903 way descriptors are implemented, such as passing a
2904 single argument pointing to a record containing the
2905 pointer/length information instead of passing that same
2906 information via two arguments as it currently does.
2907
2908 @emph{Implementation Note:} Currently, @command{g77} passes
2909 all variables and arrays of type @code{CHARACTER}
2910 by descriptor.
2911 Future versions of, or dialects supported by, @command{g77} might
2912 pass @code{CHARACTER} functions by descriptor as well.
2913
2914 Thus, use of @code{%DESCR()} tends to be restricted to cases
2915 where @var{arg} is not type @code{CHARACTER} but the called
2916 procedure accesses it via a means similar to the method
2917 used for Fortran @code{CHARACTER} arguments.
2918
2919 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
2920 how this particular version of @command{g77} passes arguments
2921 to procedures.
2922
2923 @node Generics and Specifics
2924 @subsection Generics and Specifics
2925 @cindex generic intrinsics
2926 @cindex intrinsics, generic
2927
2928 The ANSI FORTRAN 77 language defines generic and specific
2929 intrinsics.
2930 In short, the distinctions are:
2931
2932 @itemize @bullet
2933 @item
2934 @emph{Specific} intrinsics have
2935 specific types for their arguments and a specific return
2936 type.
2937
2938 @item
2939 @emph{Generic} intrinsics are treated,
2940 on a case-by-case basis in the program's source code,
2941 as one of several possible specific intrinsics.
2942
2943 Typically, a generic intrinsic has a return type that
2944 is determined by the type of one or more of its arguments.
2945 @end itemize
2946
2947 The GNU Fortran language generalizes these concepts somewhat,
2948 especially by providing intrinsic subroutines and generic
2949 intrinsics that are treated as either a specific intrinsic subroutine
2950 or a specific intrinsic function (e.g. @code{SECOND}).
2951
2952 However, GNU Fortran avoids generalizing this concept to
2953 the point where existing code would be accepted as meaning
2954 something possibly different than what was intended.
2955
2956 For example, @code{ABS} is a generic intrinsic, so all working
2957 code written using @code{ABS} of an @code{INTEGER} argument
2958 expects an @code{INTEGER} return value.
2959 Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2}
2960 argument returns an @code{INTEGER*2} return value.
2961
2962 Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only
2963 an @code{INTEGER(KIND=1)} argument.
2964 Code that passes something other than an @code{INTEGER(KIND=1)}
2965 argument to @code{IABS} is not valid GNU Fortran code, because
2966 it is not clear what the author intended.
2967
2968 For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)}
2969 is not defined by the GNU Fortran language, because the programmer
2970 might have used that construct to mean any of the following, subtly
2971 different, things:
2972
2973 @itemize @bullet
2974 @item
2975 Convert @samp{J} to @code{INTEGER(KIND=1)} first
2976 (as if @samp{IABS(INT(J))} had been written).
2977
2978 @item
2979 Convert the result of the intrinsic to @code{INTEGER(KIND=1)}
2980 (as if @samp{INT(ABS(J))} had been written).
2981
2982 @item
2983 No conversion (as if @samp{ABS(J)} had been written).
2984 @end itemize
2985
2986 The distinctions matter especially when types and values wider than
2987 @code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when
2988 operations performing more ``arithmetic'' than absolute-value, are involved.
2989
2990 The following sample program is not a valid GNU Fortran program, but
2991 might be accepted by other compilers.
2992 If so, the output is likely to be revealing in terms of how a given
2993 compiler treats intrinsics (that normally are specific) when they
2994 are given arguments that do not conform to their stated requirements:
2995
2996 @cindex JCB002 program
2997 @smallexample
2998       PROGRAM JCB002
2999 C Version 1:
3000 C Modified 1999-02-15 (Burley) to delete my email address.
3001 C Modified 1997-05-21 (Burley) to accommodate compilers that implement
3002 C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2.
3003 C
3004 C Version 0:
3005 C Written by James Craig Burley 1997-02-20.
3006 C
3007 C Purpose:
3008 C Determine how compilers handle non-standard IDIM
3009 C on INTEGER*2 operands, which presumably can be
3010 C extrapolated into understanding how the compiler
3011 C generally treats specific intrinsics that are passed
3012 C arguments not of the correct types.
3013 C
3014 C If your compiler implements INTEGER*2 and INTEGER
3015 C as the same type, change all INTEGER*2 below to
3016 C INTEGER*1.
3017 C
3018       INTEGER*2 I0, I4
3019       INTEGER I1, I2, I3
3020       INTEGER*2 ISMALL, ILARGE
3021       INTEGER*2 ITOOLG, ITWO
3022       INTEGER*2 ITMP
3023       LOGICAL L2, L3, L4
3024 C
3025 C Find smallest INTEGER*2 number.
3026 C
3027       ISMALL=0
3028  10   I0 = ISMALL-1
3029       IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20
3030       ISMALL = I0
3031       GOTO 10
3032  20   CONTINUE
3033 C
3034 C Find largest INTEGER*2 number.
3035 C
3036       ILARGE=0
3037  30   I0 = ILARGE+1
3038       IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40
3039       ILARGE = I0
3040       GOTO 30
3041  40   CONTINUE
3042 C
3043 C Multiplying by two adds stress to the situation.
3044 C
3045       ITWO = 2
3046 C
3047 C Need a number that, added to -2, is too wide to fit in I*2.
3048 C
3049       ITOOLG = ISMALL
3050 C
3051 C Use IDIM the straightforward way.
3052 C
3053       I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG
3054 C
3055 C Calculate result for first interpretation.
3056 C
3057       I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG
3058 C
3059 C Calculate result for second interpretation.
3060 C
3061       ITMP = ILARGE - ISMALL
3062       I3 = (INT (ITMP)) * ITWO + ITOOLG
3063 C
3064 C Calculate result for third interpretation.
3065 C
3066       I4 = (ILARGE - ISMALL) * ITWO + ITOOLG
3067 C
3068 C Print results.
3069 C
3070       PRINT *, 'ILARGE=', ILARGE
3071       PRINT *, 'ITWO=', ITWO
3072       PRINT *, 'ITOOLG=', ITOOLG
3073       PRINT *, 'ISMALL=', ISMALL
3074       PRINT *, 'I1=', I1
3075       PRINT *, 'I2=', I2
3076       PRINT *, 'I3=', I3
3077       PRINT *, 'I4=', I4
3078       PRINT *
3079       L2 = (I1 .EQ. I2)
3080       L3 = (I1 .EQ. I3)
3081       L4 = (I1 .EQ. I4)
3082       IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN
3083          PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))'
3084          STOP
3085       END IF
3086       IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN
3087          PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))'
3088          STOP
3089       END IF
3090       IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN
3091          PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)'
3092          STOP
3093       END IF
3094       PRINT *, 'Results need careful analysis.'
3095       END
3096 @end smallexample
3097
3098 No future version of the GNU Fortran language
3099 will likely permit specific intrinsic invocations with wrong-typed
3100 arguments (such as @code{IDIM} in the above example), since
3101 it has been determined that disagreements exist among
3102 many production compilers on the interpretation of
3103 such invocations.
3104 These disagreements strongly suggest that Fortran programmers,
3105 and certainly existing Fortran programs, disagree about the
3106 meaning of such invocations.
3107
3108 The first version of @code{JCB002} didn't accommodate some compilers'
3109 treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are
3110 @code{INTEGER*2}.
3111 In such a case, these compilers apparently convert both
3112 operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction,
3113 instead of doing an @code{INTEGER*2} subtraction on the
3114 original values in @samp{I1} and @samp{I2}.
3115
3116 However, the results of the careful analyses done on the outputs
3117 of programs compiled by these various compilers show that they
3118 all implement either @samp{Interp 1} or @samp{Interp 2} above.
3119
3120 Specifically, it is believed that the new version of @code{JCB002}
3121 above will confirm that:
3122
3123 @itemize @bullet
3124 @item
3125 Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5
3126 @command{f77} compilers all implement @samp{Interp 1}.
3127
3128 @item
3129 IRIX 5.3 @command{f77} compiler implements @samp{Interp 2}.
3130
3131 @item
3132 Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3,
3133 and IRIX 6.1 @command{f77} compilers all implement @samp{Interp 3}.
3134 @end itemize
3135
3136 If you get different results than the above for the stated
3137 compilers, or have results for other compilers that might be
3138 worth adding to the above list, please let us know the details
3139 (compiler product, version, machine, results, and so on).
3140
3141 @node REAL() and AIMAG() of Complex
3142 @subsection @code{REAL()} and @code{AIMAG()} of Complex
3143 @cindex @code{Real} intrinsic
3144 @cindex intrinsics, @code{Real}
3145 @cindex @code{AImag} intrinsic
3146 @cindex intrinsics, @code{AImag}
3147
3148 The GNU Fortran language disallows @code{REAL(@var{expr})}
3149 and @code{AIMAG(@var{expr})},
3150 where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)},
3151 except when they are used in the following way:
3152
3153 @example
3154 REAL(REAL(@var{expr}))
3155 REAL(AIMAG(@var{expr}))
3156 @end example
3157
3158 @noindent
3159 The above forms explicitly specify that the desired effect
3160 is to convert the real or imaginary part of @var{expr}, which might
3161 be some @code{REAL} type other than @code{REAL(KIND=1)},
3162 to type @code{REAL(KIND=1)},
3163 and have that serve as the value of the expression.
3164
3165 The GNU Fortran language offers clearly named intrinsics to extract the
3166 real and imaginary parts of a complex entity without any
3167 conversion:
3168
3169 @example
3170 REALPART(@var{expr})
3171 IMAGPART(@var{expr})
3172 @end example
3173
3174 To express the above using typical extended FORTRAN 77,
3175 use the following constructs
3176 (when @var{expr} is @code{COMPLEX(KIND=2)}):
3177
3178 @example
3179 DBLE(@var{expr})
3180 DIMAG(@var{expr})
3181 @end example
3182
3183 The FORTRAN 77 language offers no way
3184 to explicitly specify the real and imaginary parts of a complex expression of
3185 arbitrary type, apparently as a result of requiring support for
3186 only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}).
3187 The concepts of converting an expression to type @code{REAL(KIND=1)} and
3188 of extracting the real part of a complex expression were
3189 thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since
3190 they happened to have the exact same effect in that language
3191 (due to having only one @code{COMPLEX} type).
3192
3193 @emph{Note:} When @option{-ff90} is in effect,
3194 @command{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of
3195 type @code{COMPLEX}, as @samp{REALPART(@var{expr})},
3196 whereas with @samp{-fugly-complex -fno-f90} in effect, it is
3197 treated as @samp{REAL(REALPART(@var{expr}))}.
3198
3199 @xref{Ugly Complex Part Extraction}, for more information.
3200
3201 @node CMPLX() of DOUBLE PRECISION
3202 @subsection @code{CMPLX()} of @code{DOUBLE PRECISION}
3203 @cindex @code{Cmplx} intrinsic
3204 @cindex intrinsics, @code{Cmplx}
3205
3206 In accordance with Fortran 90 and at least some (perhaps all)
3207 other compilers, the GNU Fortran language defines @code{CMPLX()}
3208 as always returning a result that is type @code{COMPLEX(KIND=1)}.
3209
3210 This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2}
3211 are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as:
3212
3213 @example
3214 CMPLX(SNGL(D1), SNGL(D2))
3215 @end example
3216
3217 (It was necessary for Fortran 90 to specify this behavior
3218 for @code{DOUBLE PRECISION} arguments, since that is
3219 the behavior mandated by FORTRAN 77.)
3220
3221 The GNU Fortran language also provides the @code{DCMPLX()} intrinsic,
3222 which is provided by some FORTRAN 77 compilers to construct
3223 a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION}
3224 operands.
3225 However, this solution does not scale well when more @code{COMPLEX} types
3226 (having various precisions and ranges) are offered by Fortran implementations.
3227
3228 Fortran 90 extends the @code{CMPLX()} intrinsic by adding
3229 an extra argument used to specify the desired kind of complex
3230 result.
3231 However, this solution is somewhat awkward to use, and
3232 @command{g77} currently does not support it.
3233
3234 The GNU Fortran language provides a simple way to build a complex
3235 value out of two numbers, with the precise type of the value
3236 determined by the types of the two numbers (via the usual
3237 type-promotion mechanism):
3238
3239 @example
3240 COMPLEX(@var{real}, @var{imag})
3241 @end example
3242
3243 When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()}
3244 performs no conversion other than to put them together to form a
3245 complex result of the same (complex version of real) type.
3246
3247 @xref{Complex Intrinsic}, for more information.
3248
3249 @node MIL-STD 1753
3250 @subsection MIL-STD 1753 Support
3251 @cindex MIL-STD 1753
3252
3253 The GNU Fortran language includes the MIL-STD 1753 intrinsics
3254 @code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS},
3255 @code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT},
3256 @code{ISHFTC}, @code{MVBITS}, and @code{NOT}.
3257
3258 @node f77/f2c Intrinsics
3259 @subsection @command{f77}/@command{f2c} Intrinsics
3260
3261 The bit-manipulation intrinsics supported by traditional
3262 @command{f77} and by @command{f2c} are available in the GNU Fortran language.
3263 These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT},
3264 and @code{XOR}.
3265
3266 Also supported are the intrinsics @code{CDABS},
3267 @code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN},
3268 @code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT},
3269 @code{DIMAG}, @code{DREAL}, and @code{IMAG},
3270 @code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN},
3271 and @code{ZSQRT}.
3272
3273 @node Table of Intrinsic Functions
3274 @subsection Table of Intrinsic Functions
3275 @cindex intrinsics, table of
3276 @cindex table of intrinsics
3277
3278 (Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.)
3279
3280 The GNU Fortran language adds various functions, subroutines, types,
3281 and arguments to the set of intrinsic functions in ANSI FORTRAN 77.
3282 The complete set of intrinsics supported by the GNU Fortran language
3283 is described below.
3284
3285 Note that a name is not treated as that of an intrinsic if it is
3286 specified in an @code{EXTERNAL} statement in the same program unit;
3287 if a command-line option is used to disable the groups to which
3288 the intrinsic belongs; or if the intrinsic is not named in an
3289 @code{INTRINSIC} statement and a command-line option is used to
3290 hide the groups to which the intrinsic belongs.
3291
3292 So, it is recommended that any reference in a program unit to
3293 an intrinsic procedure that is not a standard FORTRAN 77
3294 intrinsic be accompanied by an appropriate @code{INTRINSIC}
3295 statement in that program unit.
3296 This sort of defensive programming makes it more
3297 likely that an implementation will issue a diagnostic rather
3298 than generate incorrect code for such a reference.
3299
3300 The terminology used below is based on that of the Fortran 90
3301 standard, so that the text may be more concise and accurate:
3302
3303 @itemize @bullet
3304 @item
3305 @code{OPTIONAL} means the argument may be omitted.
3306
3307 @item
3308 @samp{A-1, A-2, @dots{}, A-n} means more than one argument
3309 (generally named @samp{A}) may be specified.
3310
3311 @item
3312 @samp{scalar} means the argument must not be an array (must
3313 be a variable or array element, or perhaps a constant if expressions
3314 are permitted).
3315
3316 @item
3317 @samp{DIMENSION(4)} means the argument must be an array having 4 elements.
3318
3319 @item
3320 @code{INTENT(IN)} means the argument must be an expression
3321 (such as a constant or a variable that is defined upon invocation
3322 of the intrinsic).
3323
3324 @item
3325 @code{INTENT(OUT)} means the argument must be definable by the
3326 invocation of the intrinsic (that is, must not be a constant nor
3327 an expression involving operators other than array reference and
3328 substring reference).
3329
3330 @item
3331 @code{INTENT(INOUT)} means the argument must be defined prior to,
3332 and definable by, invocation of the intrinsic (a combination of
3333 the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}.
3334
3335 @item
3336 @xref{Kind Notation}, for an explanation of @code{KIND}.
3337 @end itemize
3338
3339 @ifinfo
3340 (Note that the empty lines appearing in the menu below
3341 are not intentional---they result from a bug in the
3342 GNU @command{makeinfo} program@dots{}a program that, if it
3343 did not exist, would leave this document in far worse shape!)
3344 @end ifinfo
3345
3346 @c The actual documentation for intrinsics comes from
3347 @c intdoc.texi, which in turn is automatically generated
3348 @c from the internal g77 tables in intrin.def _and_ the
3349 @c largely hand-written text in intdoc.h.  So, if you want
3350 @c to change or add to existing documentation on intrinsics,
3351 @c you probably want to edit intdoc.h.
3352 @c
3353 @set familyF77
3354 @set familyGNU
3355 @set familyASC
3356 @set familyMIL
3357 @set familyF90
3358 @clear familyVXT
3359 @clear familyFVZ
3360 @set familyF2C
3361 @set familyF2U
3362 @clear familyBADU77
3363 @include intdoc.texi
3364
3365 @node Scope and Classes of Names
3366 @section Scope and Classes of Symbolic Names
3367 @cindex symbol names, scope and classes
3368 @cindex scope
3369
3370 (The following information augments or overrides the information in
3371 Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
3372 language.
3373 Chapter 18 of that document otherwise serves as the basis
3374 for the relevant aspects of GNU Fortran.)
3375
3376 @menu
3377 * Underscores in Symbol Names::
3378 @end menu
3379
3380 @node Underscores in Symbol Names
3381 @subsection Underscores in Symbol Names
3382 @cindex underscore
3383
3384 Underscores (@samp{_}) are accepted in symbol names after the first
3385 character (which must be a letter).
3386
3387 @node I/O
3388 @section I/O
3389
3390 @cindex dollar sign
3391 A dollar sign at the end of an output format specification suppresses
3392 the newline at the end of the output.
3393
3394 @cindex <> edit descriptor
3395 @cindex edit descriptor, <>
3396 Edit descriptors in @code{FORMAT} statements may contain compile-time
3397 @code{INTEGER} constant expressions in angle brackets, such as
3398 @smallexample
3399 10    FORMAT (I<WIDTH>)
3400 @end smallexample
3401
3402 The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}.
3403
3404 These Fortran 90 features are supported:
3405 @itemize @bullet
3406 @item
3407 @cindex FORMAT descriptors
3408 @cindex Z edit descriptor
3409 @cindex edit descriptor, Z
3410 @cindex O edit descriptor
3411 @cindex edit descriptor, O
3412 The @code{O} and @code{Z} edit descriptors are supported for I/O of
3413 integers in octal and hexadecimal formats, respectively.
3414 @item
3415 The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
3416 @code{STATUS='SCRATCH'} is supplied.  The @code{STATUS='REPLACE'}
3417 specifier is supported.
3418 @end itemize
3419
3420 @node Fortran 90 Features
3421 @section Fortran 90 Features
3422 @cindex Fortran 90
3423 @cindex extensions, from Fortran 90
3424
3425 For convenience this section collects a list (probably incomplete) of
3426 the Fortran 90 features supported by the GNU Fortran language, even if
3427 they are documented elsewhere.
3428 @xref{Characters Lines Sequence,,@asis{Characters, Lines, and Execution Sequence}},
3429 for information on additional fixed source form lexical issues.
3430 @cindex @option{-ffree-form}
3431 Further, the free source form is supported through the
3432 @option{-ffree-form} option.
3433 @cindex @option{-ff90}
3434 Other Fortran 90 features can be turned on by the @option{-ff90} option;
3435 see @ref{Fortran 90}.
3436 For information on the Fortran 90 intrinsics available,
3437 see @ref{Table of Intrinsic Functions}.
3438
3439 @table @asis
3440 @item Automatic arrays in procedures
3441 @item Character assignments
3442 @cindex character assignments
3443 In character assignments, the variable being assigned may occur on the
3444 right hand side of the assignment.
3445 @item Character strings
3446 @cindex double quoted character constants
3447 Strings may have zero length and substrings of character constants are
3448 permitted.  Character constants may be enclosed in double quotes
3449 (@code{"}) as well as single quotes.  @xref{Character Type}.
3450 @item Construct names
3451 (Symbolic tags on blocks.)  @xref{Construct Names}.
3452 @item @code{CYCLE} and @code{EXIT}
3453 @xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}.
3454 @item @code{DOUBLE COMPLEX}
3455 @xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement}.
3456 @item @code{DO WHILE}
3457 @xref{DO WHILE}.
3458 @item @code{END} decoration
3459 @xref{Statements}.
3460 @item @code{END DO}
3461 @xref{END DO}.
3462 @item @code{KIND}
3463 @item @code{IMPLICIT NONE}
3464 @item @code{INCLUDE} statements
3465 @xref{INCLUDE}.
3466 @item List-directed and namelist I/O on internal files
3467 @item Binary, octal and hexadecimal constants
3468 These are supported more generally than required by Fortran 90.
3469 @xref{Integer Type}.
3470 @item @samp{O} and @samp{Z} edit descriptors
3471 @item @code{NAMELIST}
3472 @xref{NAMELIST}.
3473 @item @code{OPEN} specifiers
3474 @code{STATUS='REPLACE'} is supported.
3475 The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
3476 @code{STATUS='SCRATCH'} is supplied.
3477 @item @code{FORMAT} edit descriptors
3478 @cindex FORMAT descriptors
3479 @cindex Z edit descriptor
3480 @cindex edit descriptor, Z
3481 The @code{Z} edit descriptor is supported.
3482 @item Relational operators
3483 The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and
3484 @code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.},
3485 @code{.NE.}, @code{.GT.} and @code{.GE.} respectively.
3486 @item @code{SELECT CASE}
3487 Not fully implemented.
3488 @xref{SELECT CASE on CHARACTER Type,, @code{SELECT CASE} on @code{CHARACTER} Type}.
3489 @item Specification statements
3490 A limited subset of the Fortran 90 syntax and semantics for variable
3491 declarations is supported, including @code{KIND}.  @xref{Kind Notation}.
3492 (@code{KIND} is of limited usefulness in the absence of the
3493 @code{KIND}-related intrinsics, since these intrinsics permit writing
3494 more widely portable code.)  An example of supported @code{KIND} usage
3495 is:
3496 @smallexample
3497 INTEGER (KIND=1) :: FOO=1, BAR=2
3498 CHARACTER (LEN=3) FOO
3499 @end smallexample
3500 @code{PARAMETER} and @code{DIMENSION} attributes aren't supported.
3501 @end table
3502
3503 @node Other Dialects
3504 @chapter Other Dialects
3505
3506 GNU Fortran supports a variety of features that are not
3507 considered part of the GNU Fortran language itself, but
3508 are representative of various dialects of Fortran that
3509 @command{g77} supports in whole or in part.
3510
3511 Any of the features listed below might be disallowed by
3512 @command{g77} unless some command-line option is specified.
3513 Currently, some of the features are accepted using the
3514 default invocation of @command{g77}, but that might change
3515 in the future.
3516
3517 @emph{Note: This portion of the documentation definitely needs a lot
3518 of work!}
3519
3520 @menu
3521 * Source Form::       Details of fixed-form and free-form source.
3522 * Trailing Comment::  Use of @samp{/*} to start a comment.
3523 * Debug Line::        Use of @samp{D} in column 1.
3524 * Dollar Signs::      Use of @samp{$} in symbolic names.
3525 * Case Sensitivity::  Uppercase and lowercase in source files.
3526 * VXT Fortran::       @dots{}versus the GNU Fortran language.
3527 * Fortran 90::        @dots{}versus the GNU Fortran language.
3528 * Pedantic Compilation::  Enforcing the standard.
3529 * Distensions::       Misfeatures supported by GNU Fortran.
3530 @end menu
3531
3532 @node Source Form
3533 @section Source Form
3534 @cindex source file format
3535 @cindex source format
3536 @cindex file, source
3537 @cindex source code
3538 @cindex code, source
3539 @cindex fixed form
3540 @cindex free form
3541
3542 GNU Fortran accepts programs written in either fixed form or
3543 free form.
3544
3545 Fixed form
3546 corresponds to ANSI FORTRAN 77 (plus popular extensions, such as
3547 allowing tabs) and Fortran 90's fixed form.
3548
3549 Free form corresponds to
3550 Fortran 90's free form (though possibly not entirely up-to-date, and
3551 without complaining about some things that for which Fortran 90 requires
3552 diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}).
3553
3554 The way a Fortran compiler views source files depends entirely on the
3555 implementation choices made for the compiler, since those choices
3556 are explicitly left to the implementation by the published Fortran
3557 standards.
3558 GNU Fortran currently tries to be somewhat like a few popular compilers
3559 (@command{f2c}, Digital (``DEC'') Fortran, and so on).
3560
3561 This section describes how @command{g77} interprets source lines.
3562
3563 @menu
3564 * Carriage Returns::  Carriage returns ignored.
3565 * Tabs::              Tabs converted to spaces.
3566 * Short Lines::       Short lines padded with spaces (fixed-form only).
3567 * Long Lines::        Long lines truncated.
3568 * Ampersands::        Special Continuation Lines.
3569 @end menu
3570
3571 @node Carriage Returns
3572 @subsection Carriage Returns
3573 @cindex carriage returns
3574
3575 Carriage returns (@samp{\r}) in source lines are ignored.
3576 This is somewhat different from @command{f2c}, which seems to treat them as
3577 spaces outside character/Hollerith constants, and encodes them as @samp{\r}
3578 inside such constants.
3579
3580 @node Tabs
3581 @subsection Tabs
3582 @cindex tab character
3583 @cindex horizontal tab
3584
3585 A source line with a @key{TAB} character anywhere in it is treated as
3586 entirely significant---however long it is---instead of ending in
3587 column 72 (for fixed-form source) or 132 (for free-form source).
3588 This also is different from @command{f2c}, which encodes tabs as
3589 @samp{\t} (the ASCII @key{TAB} character) inside character
3590 and Hollerith constants, but nevertheless seems to treat the column
3591 position as if it had been affected by the canonical tab positioning.
3592
3593 @command{g77} effectively
3594 translates tabs to the appropriate number of spaces (a la the default
3595 for the UNIX @command{expand} command) before doing any other processing, other
3596 than (currently) noting whether a tab was found on a line and using this
3597 information to decide how to interpret the length of the line and continued
3598 constants.
3599
3600 @node Short Lines
3601 @subsection Short Lines
3602 @cindex short source lines
3603 @cindex space, padding with
3604 @cindex source lines, short
3605 @cindex lines, short
3606
3607 Source lines shorter than the applicable fixed-form length are treated as
3608 if they were padded with spaces to that length.
3609 (None of this is relevant to source files written in free form.)
3610
3611 This affects only
3612 continued character and Hollerith constants, and is a different
3613 interpretation than provided by some other popular compilers
3614 (although a bit more consistent with the traditional punched-card
3615 basis of Fortran and the way the Fortran standard expressed fixed
3616 source form).
3617
3618 @command{g77} might someday offer an option to warn about cases where differences
3619 might be seen as a result of this treatment, and perhaps an option to
3620 specify the alternate behavior as well.
3621
3622 Note that this padding cannot apply to lines that are effectively of
3623 infinite length---such lines are specified using command-line options
3624 like @option{-ffixed-line-length-none}, for example.
3625
3626 @node Long Lines
3627 @subsection Long Lines
3628 @cindex long source lines
3629 @cindex truncation, of long lines
3630 @cindex lines, long
3631 @cindex source lines, long
3632
3633 Source lines longer than the applicable length are truncated to that
3634 length.
3635 Currently, @command{g77} does not warn if the truncated characters are
3636 not spaces, to accommodate existing code written for systems that
3637 treated truncated text as commentary (especially in columns 73 through 80).
3638
3639 @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect},
3640 for information on the @option{-ffixed-line-length-@var{n}} option,
3641 which can be used to set the line length applicable to fixed-form
3642 source files.
3643
3644 @node Ampersands
3645 @subsection Ampersand Continuation Line
3646 @cindex ampersand continuation line
3647 @cindex continuation line, ampersand
3648
3649 A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length
3650 continuation line, imitating the behavior of @command{f2c}.
3651
3652 @node Trailing Comment
3653 @section Trailing Comment
3654
3655 @cindex trailing comment
3656 @cindex comment
3657 @cindex characters, comment
3658 @cindex /*
3659 @cindex !
3660 @cindex exclamation point
3661 @command{g77} supports use of @samp{/*} to start a trailing
3662 comment.
3663 In the GNU Fortran language, @samp{!} is used for this purpose.
3664
3665 @samp{/*} is not in the GNU Fortran language
3666 because the use of @samp{/*} in a program might
3667 suggest to some readers that a block, not trailing, comment is
3668 started (and thus ended by @samp{*/}, not end of line),
3669 since that is the meaning of @samp{/*} in C.
3670
3671 Also, such readers might think they can use @samp{//} to start
3672 a trailing comment as an alternative to @samp{/*}, but
3673 @samp{//} already denotes concatenation, and such a ``comment''
3674 might actually result in a program that compiles without
3675 error (though it would likely behave incorrectly).
3676
3677 @node Debug Line
3678 @section Debug Line
3679 @cindex debug line
3680 @cindex comment line, debug
3681
3682 Use of @samp{D} or @samp{d} as the first character (column 1) of
3683 a source line denotes a debug line.
3684
3685 In turn, a debug line is treated as either a comment line
3686 or a normal line, depending on whether debug lines are enabled.
3687
3688 When treated as a comment line, a line beginning with @samp{D} or
3689 @samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively.
3690 When treated as a normal line, such a line is treated as if
3691 the first character was @key{SPC} (space).
3692
3693 (Currently, @command{g77} provides no means for treating debug
3694 lines as normal lines.)
3695
3696 @node Dollar Signs
3697 @section Dollar Signs in Symbol Names
3698 @cindex dollar sign
3699 @cindex $
3700
3701 Dollar signs (@samp{$}) are allowed in symbol names (after the first character)
3702 when the @option{-fdollar-ok} option is specified.
3703
3704 @node Case Sensitivity
3705 @section Case Sensitivity
3706 @cindex case sensitivity
3707 @cindex source file format
3708 @cindex code, source
3709 @cindex source code
3710 @cindex uppercase letters
3711 @cindex lowercase letters
3712 @cindex letters, uppercase
3713 @cindex letters, lowercase
3714
3715 GNU Fortran offers the programmer way too much flexibility in deciding
3716 how source files are to be treated vis-a-vis uppercase and lowercase
3717 characters.
3718 There are 66 useful settings that affect case sensitivity, plus 10
3719 settings that are nearly useless, with the remaining 116 settings
3720 being either redundant or useless.
3721
3722 None of these settings have any effect on the contents of comments
3723 (the text after a @samp{c} or @samp{C} in Column 1, for example)
3724 or of character or Hollerith constants.
3725 Note that things like the @samp{E} in the statement
3726 @samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB}
3727 are considered built-in keywords, and so are affected by
3728 these settings.
3729
3730 Low-level switches are identified in this section as follows:
3731
3732 @itemize @w{}
3733 @item A
3734 Source Case Conversion:
3735
3736 @itemize @w{}
3737 @item 0
3738 Preserve (see Note 1)
3739 @item 1
3740 Convert to Upper Case
3741 @item 2
3742 Convert to Lower Case
3743 @end itemize
3744
3745 @item B
3746 Built-in Keyword Matching:
3747
3748 @itemize @w{}
3749 @item 0
3750 Match Any Case (per-character basis)
3751 @item 1
3752 Match Upper Case Only
3753 @item 2
3754 Match Lower Case Only
3755 @item 3
3756 Match InitialCaps Only (see tables for spellings)
3757 @end itemize
3758
3759 @item C
3760 Built-in Intrinsic Matching:
3761
3762 @itemize @w{}
3763 @item 0
3764 Match Any Case (per-character basis)
3765 @item 1
3766 Match Upper Case Only
3767 @item 2
3768 Match Lower Case Only
3769 @item 3
3770 Match InitialCaps Only (see tables for spellings)
3771 @end itemize
3772
3773 @item D
3774 User-defined Symbol Possibilities (warnings only):
3775
3776 @itemize @w{}
3777 @item 0
3778 Allow Any Case (per-character basis)
3779 @item 1
3780 Allow Upper Case Only
3781 @item 2
3782 Allow Lower Case Only
3783 @item 3
3784 Allow InitialCaps Only (see Note 2)
3785 @end itemize
3786 @end itemize
3787
3788 Note 1: @command{g77} eventually will support @code{NAMELIST} in a manner that is
3789 consistent with these source switches---in the sense that input will be
3790 expected to meet the same requirements as source code in terms
3791 of matching symbol names and keywords (for the exponent letters).
3792
3793 Currently, however, @code{NAMELIST} is supported by @code{libg2c},
3794 which uppercases @code{NAMELIST} input and symbol names for matching.
3795 This means not only that @code{NAMELIST} output currently shows symbol
3796 (and keyword) names in uppercase even if lower-case source
3797 conversion (option A2) is selected, but that @code{NAMELIST} cannot be
3798 adequately supported when source case preservation (option A0)
3799 is selected.
3800
3801 If A0 is selected, a warning message will be
3802 output for each @code{NAMELIST} statement to this effect.
3803 The behavior
3804 of the program is undefined at run time if two or more symbol names
3805 appear in a given @code{NAMELIST} such that the names are identical
3806 when converted to upper case (e.g.&n