OSDN Git Service

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