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