OSDN Git Service

* trans.h (gfc_conv_cray_pointee): Remove.
[pf3gnuchains/gcc-fork.git] / gcc / fortran / gfortran.texi
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2005
5
6 @include gcc-common.texi
7
8 @settitle The GNU Fortran 95 Compiler
9
10 @c Create a separate index for command line options
11 @defcodeindex op
12 @c Merge the standard indexes into a single one.
13 @syncodeindex fn cp
14 @syncodeindex vr cp
15 @syncodeindex ky cp
16 @syncodeindex pg cp
17 @syncodeindex tp cp
18
19 @c %**end of header
20
21 @c Use with @@smallbook.
22
23 @c %** start of document
24
25 @c Cause even numbered pages to be printed on the left hand side of
26 @c the page and odd numbered pages to be printed on the right hand
27 @c side of the page.  Using this, you can print on both sides of a
28 @c sheet of paper and have the text on the same part of the sheet.
29
30 @c The text on right hand pages is pushed towards the right hand
31 @c margin and the text on left hand pages is pushed toward the left
32 @c hand margin.
33 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
34
35 @c @tex
36 @c \global\bindingoffset=0.75in
37 @c \global\normaloffset =0.75in
38 @c @end tex
39
40 @copying
41 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
42
43 Permission is granted to copy, distribute and/or modify this document
44 under the terms of the GNU Free Documentation License, Version 1.1 or
45 any later version published by the Free Software Foundation; with the
46 Invariant Sections being ``GNU General Public License'' and ``Funding
47 Free Software'', the Front-Cover
48 texts being (a) (see below), and with the Back-Cover Texts being (b)
49 (see below).  A copy of the license is included in the section entitled
50 ``GNU Free Documentation License''.
51
52 (a) The FSF's Front-Cover Text is:
53
54      A GNU Manual
55
56 (b) The FSF's Back-Cover Text is:
57
58      You have freedom to copy and modify this GNU Manual, like GNU
59      software.  Copies published by the Free Software Foundation raise
60      funds for GNU development.
61 @end copying
62
63 @ifinfo
64 @dircategory Programming
65 @direntry
66 * gfortran: (gfortran).                  The GNU Fortran 95 Compiler.
67 @end direntry
68 This file documents the use and the internals of
69 the GNU Fortran 95 compiler, (@command{gfortran}).
70
71 Published by the Free Software Foundation
72 51 Franklin Street, Fifth Floor
73 Boston, MA 02110-1301 USA
74
75 @insertcopying
76 @end ifinfo
77
78 Contributed by Steven Bosscher (@email{s.bosscher@@gcc.gnu.org}).
79
80 @setchapternewpage odd
81 @titlepage
82 @title Using GNU Fortran 95
83 @sp 2
84 @center Steven Bosscher
85 @page
86 @vskip 0pt plus 1filll
87 For the @value{version-GCC} Version*
88 @sp 1
89 Published by the Free Software Foundation @*
90 51 Franklin Street, Fifth Floor@*
91 Boston, MA 02110-1301, USA@*
92 @c Last printed ??ber, 19??.@*
93 @c Printed copies are available for $? each.@*
94 @c ISBN ???
95 @sp 1
96 @insertcopying
97 @end titlepage
98 @summarycontents
99 @contents
100 @page
101
102 @node Top, Copying,, (DIR)
103 @top Introduction
104 @cindex Introduction
105
106 This manual documents the use of @command{gfortran}, 
107 the GNU Fortran 95 compiler. You can find in this manual how to invoke
108 @command{gfortran}, as well as its features and incompatibilities.
109
110 @ifset DEVELOPMENT
111 @emph{Warning:} This document, and the compiler it describes, are still
112 under development.  While efforts are made to keep it up-to-date, it might
113 not accurately reflect the status of the most recent @command{gfortran}.
114 @end ifset
115
116 @comment
117 @comment  When you add a new menu item, please keep the right hand
118 @comment  aligned to the same column.  Do not use tabs.  This provides
119 @comment  better formatting.
120 @comment
121 @menu
122 * Copying::              GNU General Public License says
123                          how you can copy and share GNU Fortran.
124 * GNU Free Documentation License::
125                          How you can copy and share this manual.
126 * Funding::              How to help assure continued work for free software.
127 * Getting Started::      What you should know about @command{gfortran}.
128 * GFORTRAN and GCC::     You can compile Fortran, C, or other programs.
129 * GFORTRAN and G77::     Why we chose to start from scratch.
130 * Invoking GFORTRAN::    Command options supported by @command{gfortran}.
131 * Project Status::       Status of @command{gfortran}, roadmap, proposed extensions.
132 * Contributing::         How you can help.
133 * Standards::            Standards supported by @command{gfortran}
134 * Extensions::           Language extensions implemented by @command{gfortran}
135 * Intrinsic Procedures:: Intrinsic procedures supported by @command{gfortran}
136 * Index::                Index of this documentation.
137 @end menu
138
139
140
141 @c ---------------------------------------------------------------------
142 @c GNU General Public License
143 @c ---------------------------------------------------------------------
144
145 @include gpl.texi
146
147
148
149 @c ---------------------------------------------------------------------
150 @c GNU Free Documentation License
151 @c ---------------------------------------------------------------------
152
153 @include fdl.texi
154
155
156
157 @c ---------------------------------------------------------------------
158 @c Funding Free Software
159 @c ---------------------------------------------------------------------
160
161 @include funding.texi
162
163
164
165 @c ---------------------------------------------------------------------
166 @c Getting Started
167 @c ---------------------------------------------------------------------
168
169 @node Getting Started
170 @chapter Getting Started
171
172 Gfortran is the GNU Fortran 95 compiler front end,
173 designed initially as a free replacement for,
174 or alternative to, the unix @command{f95} command;
175 @command{gfortran} is the command you'll use to invoke the compiler.
176
177 Gfortran is still in an early state of development.
178 @command{gfortran} can generate code for most constructs and expressions,
179 but much work remains to be done.
180
181 When @command{gfortran} is finished,
182 it will do everything you expect from any decent compiler: 
183
184 @itemize @bullet
185 @item
186 Read a user's program,
187 stored in a file and containing instructions written
188 in Fortran 77, Fortran 90 or Fortran 95.
189 This file contains @dfn{source code}.
190
191 @item
192 Translate the user's program into instructions a computer
193 can carry out more quickly than it takes to translate the
194 instructions in the first
195 place.  The result after compilation of a program is
196 @dfn{machine code},
197 code designed to be efficiently translated and processed
198 by a machine such as your computer.
199 Humans usually aren't as good writing machine code
200 as they are at writing Fortran (or C++, Ada, or Java),
201 because is easy to make tiny mistakes writing machine code.
202
203 @item
204 Provide the user with information about the reasons why
205 the compiler is unable to create a binary from the source code.
206 Usually this will be the case if the source code is flawed.
207 When writing Fortran, it is easy to make big mistakes.
208 The Fortran 90 requires that the compiler can point out
209 mistakes to the user.
210 An incorrect usage of the language causes an @dfn{error message}.
211
212 The compiler will also attempt to diagnose cases where the
213 user's program contains a correct usage of the language,
214 but instructs the computer to do something questionable.
215 This kind of diagnostics message is called a @dfn{warning message}.
216
217 @item
218 Provide optional information about the translation passes
219 from the source code to machine code.
220 This can help a user of the compiler to find the cause of
221 certain bugs which may not be obvious in the source code,
222 but may be more easily found at a lower level compiler output.
223 It also helps developers to find bugs in the compiler itself.
224
225 @item
226 Provide information in the generated machine code that can
227 make it easier to find bugs in the program (using a debugging tool,
228 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}). 
229
230 @item
231 Locate and gather machine code already generated to
232 perform actions requested by statements in the user's program.
233 This machine code is organized into @dfn{modules} and is located
234 and @dfn{linked} to the user program. 
235 @end itemize
236
237 Gfortran consists of several components:
238
239 @itemize @bullet
240 @item
241 A version of the @command{gcc} command
242 (which also might be installed as the system's @command{cc} command)
243 that also understands and accepts Fortran source code.
244 The @command{gcc} command is the @dfn{driver} program for
245 all the languages in the GNU Compiler Collection (GCC);
246 With @command{gcc},
247 you can compile the source code of any language for
248 which a front end is available in GCC.
249
250 @item
251 The @command{gfortran} command itself,
252 which also might be installed as the
253 system's @command{f95} command.
254 @command{gfortran} is just another driver program,
255 but specifically for the Fortran 95 compiler only.
256 The difference with @command{gcc} is that @command{gfortran}
257 will automatically link the correct libraries to your program.
258
259 @item
260 A collection of run-time libraries.
261 These libraries contain the machine code needed to support
262 capabilities of the Fortran language that are not directly
263 provided by the machine code generated by the
264 @command{gfortran} compilation phase,
265 such as intrinsic functions and subroutines,
266 and routines for interaction with files and the operating system.
267 @c and mechanisms to spawn,
268 @c unleash and pause threads in parallelized code.
269
270 @item
271 The Fortran compiler itself, (@command{f951}).
272 This is the gfortran parser and code generator,
273 linked to and interfaced with the GCC backend library.
274 @command{f951} ``translates'' the source code to
275 assembler code.  You would typically not use this
276 program directly;
277 instead, the @command{gcc} or @command{gfortran} driver
278 programs will call it for you.
279 @end itemize
280
281
282
283 @c ---------------------------------------------------------------------
284 @c GFORTRAN and GCC
285 @c ---------------------------------------------------------------------
286
287 @node GFORTRAN and GCC
288 @chapter GFORTRAN and GCC
289 @cindex GNU Compiler Collection
290
291 GCC used to be the GNU ``C'' Compiler,
292 but is now known as the @dfn{GNU Compiler Collection}.
293 GCC provides the GNU system with a very versatile
294 compiler middle end (shared optimization passes),
295 and back ends (code generators) for many different
296 computer architectures and operating systems.
297 The code of the middle end and back end are shared by all
298 compiler front ends that are in the GNU Compiler Collection.
299
300 A GCC front end is essentially a source code parser
301 and an intermediate code generator.  The code generator translates the
302 semantics of the source code into a language independent form called
303 @dfn{GENERIC}.
304
305 The parser takes a source file written in a
306 particular computer language, reads and parses it,
307 and tries to make sure that the source code conforms to
308 the language rules.
309 Once the correctness of a program has been established,
310 the compiler will build a data structure known as the
311 @dfn{Abstract Syntax tree},
312 or just @dfn{AST} or ``tree'' for short.
313 This data structure represents the whole program
314 or a subroutine or a function.
315 The ``tree'' is passed to the GCC middle end,
316 which will perform optimization passes on it.  The optimized AST is then 
317 handed off too the back end which assembles the program unit.
318
319 Different phases in this translation process can be,
320 and in fact @emph{are} merged in many compiler front ends.
321 GNU Fortran 95 has a strict separation between the
322 parser and code generator.
323
324 The goal of the gfortran project is to build a new front end for GCC.
325 Specifically, a Fortran 95 front end.
326 In a non-gfortran installation,
327 @command{gcc} will not be able to compile Fortran 95 source code
328 (only the ``C'' front end has to be compiled if you want to build GCC,
329 all other languages are optional).
330 If you build GCC with gfortran, @command{gcc} will recognize
331 @file{.f/.f90/.f95} source files and accepts Fortran 95 specific
332 command line options.
333
334
335
336 @c ---------------------------------------------------------------------
337 @c GFORTRAN and G77
338 @c ---------------------------------------------------------------------
339
340 @node GFORTRAN and G77
341 @chapter GFORTRAN and G77
342 @cindex Fortran 77
343 @cindex G77
344
345 Why do we write a compiler front end from scratch? 
346 There's a fine Fortran 77 compiler in the
347 GNU Compiler Collection that accepts some features
348 of the Fortran 90 standard as extensions.
349 Why not start from there and revamp it?
350
351 One of the reasons is that Craig Burley, the author of G77,
352 has decided to stop working on the G77 front end.
353 On @uref{http://world.std.com/~burley/g77-why.html,
354 Craig explains the reasons for his decision to stop working on G77}
355 in one of the pages in his homepage.
356 Among the reasons is a lack of interest in improvements to
357 @command{g77}.
358 Users appear to be quite satisfied with @command{g77} as it is.
359 While @command{g77} is still being maintained (by Toon Moene),
360 it is unlikely that sufficient people will be willing
361 to completely rewrite the existing code. 
362
363 But there are other reasons to start from scratch.
364 Many people, including Craig Burley,
365 no longer agreed with certain design decisions in the G77 front end.
366 Also, the interface of @command{g77} to the back end is written in
367 a style which is confusing and not up to date on recommended practice.
368 In fact, a full rewrite had already been planned for GCC 3.0.
369
370 When Craig decided to stop,
371 it just seemed to be a better idea to start a new project from scratch,
372 because it was expected to be easier to maintain code we
373 develop ourselves than to do a major overhaul of @command{g77} first,
374 and then build a Fortran 95 compiler out of it.
375
376 @include invoke.texi
377
378 @c ---------------------------------------------------------------------
379 @c Project Status
380 @c ---------------------------------------------------------------------
381
382 @node Project Status
383 @chapter Project Status
384
385 @quotation
386 As soon as gfortran can parse all of the statements correctly,
387 it will be in the ``larva'' state.
388 When we generate code, the ``puppa'' state.
389 When gfortran is done,
390 we'll see if it will be a beautiful butterfly,
391 or just a big bug....
392
393 --Andy Vaught, April 2000
394 @end quotation
395
396 The start of the GNU Fortran 95 project was announced on
397 the GCC homepage in March 18, 2000
398 (even though Andy had already been working on it for a while,
399 of course).
400
401 Gfortran is currently reaching the stage where is is able to compile real
402 world programs.  However it is still under development and has many rough
403 edges.
404
405 @menu
406 * Compiler Status::
407 * Library Status::
408 * Proposed Extensions::
409 @end menu
410
411 @node Compiler Status
412 @section Compiler Status
413
414 @table @emph
415 @item Front end
416 This is the part of gfortran which parses a source file, verifies that it
417 is valid Fortran 95, performs compile time replacement of constants
418 (PARAMETER variables) and reads and generate module files. This is
419 almost complete. Every Fortran 95 source should be accepted, and most
420 none-Fortran 95 source should be rejected. If you find a source file where
421 this is not true, please tell us. You can use the -fsyntax-only switch to
422 make gfortran quit after running the front end, effectively reducing it to
423 a syntax checker.
424
425 @item Middle end interface
426 These are the parts of gfortran that take the parse tree generated by the
427 front end and translate it to the GENERIC form required by the GCC back
428 end. Work is ongoing in these parts of gfortran, but a large part has
429 already been completed.
430 @end table
431
432 @node Library Status
433 @section Library Status
434
435 Some intrinsic functions map directly to library functions, and in most
436 cases the name of the library function used depends on the type of the
437 arguments.  For some intrinsics we generate inline code, and for others,
438 such as sin, cos and sqrt, we rely on the backend to use special
439 instructions in the floating point unit of the CPU if available, or to
440 fall back to a call to libm if these are not available.
441
442 Implementation of some non-elemental intrinsic functions (eg. DOT_PRODUCT,
443 AVERAGE) is not yet optimal. This is hard because we have to make decisions
444 whether to use inline code (good for small arrays as no function call
445 overhead occurs) or generate function calls (good for large arrays as it
446 allows use of hand-optimized assembly routines, SIMD instructions, etc.)
447
448 The IO library is still under development.  The following features should be
449 usable for real programs:
450
451 @itemize @minus
452 @item List directed
453 @item Unformatted sequential
454 @end itemize
455
456 Usable with bugs:
457
458 @itemize @minus
459 @item Formatted sequential ('T' edit descriptor, and others)
460 @end itemize
461
462 Not recommended:
463
464 @itemize @minus
465 @item Unformatted direct access
466 @item Formatted direct access
467 @end itemize
468
469 Many Fortran programs only use a small subset of the available IO
470 capabilities, so your mileage may vary.
471
472 @node Proposed Extensions
473 @section Proposed Extensions
474
475 Here's a list of proposed extensions for @command{gfortran}, in no particular
476 order.  Most of these are necessary to be fully compatible with
477 existing Fortran compilers, but they are not part of the official
478 J3 Fortran 95 standard.
479
480 @subsection Compiler extensions: 
481 @itemize @bullet
482 @item
483 Flag for defining the kind number for default logicals.
484
485 @item
486 User-specified alignment rules for structures.
487 @item
488 Flag to generate @code{Makefile} info.
489
490 @item
491 Automatically extend single precision constants to double.
492
493 @item
494 Compile code that conserves memory by dynamically allocating common and
495 module storage either on stack or heap.
496
497 @item
498 Flag to cause the compiler to distinguish between upper and lower case
499 names.  The Fortran 95 standard does not distinguish them.
500
501 @item
502 Compile flag to generate code for array conformance checking (suggest -CC).
503
504 @item
505 User control of symbol names (underscores, etc).
506
507 @item
508 Compile setting for maximum size of stack frame size before spilling
509 parts to static or heap.
510
511 @item
512 Flag to force local variables into static space.
513
514 @item
515 Flag to force local variables onto stack.
516
517 @item
518 Flag to compile lines beginning with ``D''.
519
520 @item
521 Flag to ignore lines beginning with ``D''.
522
523 @item
524 Flag for maximum errors before ending compile.
525
526 @item
527 Generate code to check for null pointer dereferences -- prints locus of
528 dereference instead of segfaulting.  There was some discussion about this
529 option in the g95 development mailing list.
530
531 @item
532 Allow setting the default unit number.
533
534 @item
535 Option to initialize otherwise uninitialized integer and floating
536 point variables.
537
538 @item
539 Support for OpenMP directives.  This also requires support from the runtime
540 library and the rest of the compiler.
541
542 @item
543 Support for Fortran 200x. This includes several new features including
544 floating point exceptions, extended use of allocatable arrays, C
545 interoperability, Parameterizer data types and function pointers.
546 @end itemize
547
548
549 @subsection Environment Options
550 @itemize @bullet
551 @item
552 Pluggable library modules for random numbers, linear algebra.
553 LA should use BLAS calling conventions.
554
555 @item
556 Environment variables controlling actions on arithmetic exceptions like
557 overflow, underflow, precision loss -- Generate NaN, abort, default.
558 action.
559
560 @item
561 Set precision for fp units that support it (i387).
562
563 @item
564 Variable for setting fp rounding mode.
565
566 @item
567 Variable to fill uninitialized variables with a user-defined bit
568 pattern.
569
570 @item
571 Environment variable controlling filename that is opened for that unit
572 number.
573
574 @item
575 Environment variable to clear/trash memory being freed.
576
577 @item
578 Environment variable to control tracing of allocations and frees.
579
580 @item
581 Environment variable to display allocated memory at normal program end.
582
583 @item
584 Environment variable for filename for * IO-unit.
585
586 @item
587 Environment variable for temporary file directory.
588
589 @item
590 Environment variable forcing standard output to be line buffered (unix).
591
592 @item
593 Variable for swapping endianness during unformatted read.
594
595 @item
596 Variable for swapping Endianness during unformatted write.
597 @end itemize
598
599 @c ---------------------------------------------------------------------
600 @c Extensions
601 @c ---------------------------------------------------------------------
602
603 @c Maybe this chapter should be merged with the 'Standards' section,
604 @c whenever that is written :-)
605
606 @node Extensions
607 @chapter Extensions
608 @cindex Extension
609
610 @command{gfortran} implements a number of extensions over standard
611 Fortran. This chapter contains information on their syntax and
612 meaning.  There are currently two categories of @command{gfortran}
613 extensions, those that provide functionality beyond that provided
614 by any standard, and those that are supported by @command{gfortran}
615 purely for backward compatibility with legacy compilers.  By default,
616 @option{-std=gnu} allows the compiler to accept both types of
617 extensions, but to warn about the use of the latter.  Specifying
618 either @option{-std=f95} or @option{-std=f2003} disables both types
619 of extensions, and @option{-std=legacy} allows both without warning.
620
621 @menu
622 * Old-style kind specifications::
623 * Old-style variable initialization::
624 * Extensions to namelist::
625 * X format descriptor::
626 * Commas in FORMAT specifications::
627 * I/O item lists::
628 * Hexadecimal constants::
629 * Real array indices::
630 * Unary operators::
631 * Implicitly interconvert LOGICAL and INTEGER::
632 * Hollerith constants support::
633 * Cray pointers::
634 @end menu
635
636 @node Old-style kind specifications
637 @section Old-style kind specifications
638 @cindex Kind specifications
639
640 @command{gfortran} allows old-style kind specifications in
641 declarations. These look like:
642 @smallexample
643       TYPESPEC*k x,y,z
644 @end smallexample
645 where @code{TYPESPEC} is a basic type, and where @code{k} is a valid kind
646 number for that type. The statement then declares @code{x}, @code{y}
647 and @code{z} to be of type @code{TYPESPEC} with kind @code{k}. In
648 other words, it is equivalent to the standard conforming declaration
649 @smallexample
650       TYPESPEC(k) x,y,z
651 @end smallexample
652
653 @node Old-style variable initialization
654 @section Old-style variable initialization
655 @cindex Initialization
656
657 @command{gfortran} allows old-style initialization of variables of the
658 form:
659 @smallexample
660       INTEGER*4 i/1/,j/2/
661       REAL*8 x(2,2) /3*0.,1./
662 @end smallexample
663 These are only allowed in declarations without double colons
664 (@code{::}), as these were introduced in Fortran 90 which also
665 introduced a new syntax for variable initializations. The syntax for
666 the individual initializers is as for the @code{DATA} statement, but
667 unlike in a @code{DATA} statement, an initializer only applies to the
668 variable immediately preceding. In other words, something like
669 @code{INTEGER I,J/2,3/} is not valid.
670
671 Examples of standard conforming code equivalent to the above example, are:
672 @smallexample
673 ! Fortran 90
674       INTEGER(4) :: i = 1, j = 2
675       REAL(8) :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
676 ! Fortran 77
677       INTEGER  i, j
678       DOUBLE PRECISION x(2,2)
679       DATA i,j,x /1,2,3*0.,1./
680 @end smallexample
681
682 @node Extensions to namelist
683 @section Extensions to namelist
684 @cindex Namelist
685
686 @command{gfortran} fully supports the Fortran 95 standard for namelist I/O
687 including array qualifiers, substrings and fully qualified derived types.
688 The output from a namelist write is compatible with namelist read.  The
689 output has all names in upper case and indentation to column 1 after the
690 namelist name.  Two extensions are permitted:
691
692 Old-style use of $ instead of &
693 @smallexample
694 $MYNML
695  X(:)%Y(2) = 1.0 2.0 3.0
696  CH(1:4) = "abcd"
697 $END
698 @end smallexample
699
700 It should be noticed that the default terminator is / rather than &END.
701
702 Querying of the namelist when inputting from stdin. After at least
703 one space, entering ? sends to stdout the namelist name and the names of
704 the variables in the namelist:
705 @smallexample
706 ?
707
708 &mynml
709  x
710  x%y
711  ch
712 &end
713 @end smallexample
714
715 Entering =? outputs the namelist to stdout, as if WRITE (*,NML = mynml)
716 had been called:
717 @smallexample
718 =?
719
720 &MYNML
721  X(1)%Y=  0.000000    ,  1.000000    ,  0.000000    ,
722  X(2)%Y=  0.000000    ,  2.000000    ,  0.000000    ,
723  X(3)%Y=  0.000000    ,  3.000000    ,  0.000000    ,
724  CH=abcd,  /
725 @end smallexample
726
727 To aid this dialog, when input is from stdin, errors send their
728 messages to stderr and execution continues, even if IOSTAT is set.
729
730 PRINT namelist is permitted.  This causes an error if -std=f95 is used.
731 @smallexample
732 PROGRAM test_print
733   REAL, dimension (4)  ::  x = (/1.0, 2.0, 3.0, 4.0/)
734   NAMELIST /mynml/ x
735   PRINT mynml
736 END PROGRAM test_print
737 @end smallexample
738
739 @node X format descriptor
740 @section X format descriptor
741 @cindex X format descriptor
742
743 To support legacy codes, @command{gfortran} permits the count field
744 of the X edit descriptor in FORMAT statements to be omitted.  When
745 omitted, the count is implicitly assumed to be one.
746
747 @smallexample
748        PRINT 10, 2, 3
749 10     FORMAT (I1, X, I1)
750 @end smallexample
751
752 @node Commas in FORMAT specifications
753 @section Commas in FORMAT specifications
754 @cindex Commas in FORMAT specifications
755
756 To support legacy codes, @command{gfortran} allows the comma separator
757 to be omitted immediately before and after character string edit
758 descriptors in FORMAT statements.
759
760 @smallexample
761        PRINT 10, 2, 3
762 10     FORMAT ('FOO='I1' BAR='I2)
763 @end smallexample
764
765 @node I/O item lists
766 @section I/O item lists
767 @cindex I/O item lists
768
769 To support legacy codes, @command{gfortran} allows the input item list
770 of the READ statement, and the output item lists of the WRITE and PRINT
771 statements to start with a comma.
772
773 @node Hexadecimal constants
774 @section Hexadecimal constants
775 @cindex Hexadecimal constants
776
777 As a GNU extension, @command{gfortran} allows hexadecimal constants to
778 be specified using the X prefix, in addition to the standard Z prefix.
779
780 @node Real array indices
781 @section Real array indices
782 @cindex Real array indices
783
784 As a GNU extension, @command{gfortran} allows arrays to be indexed using
785 real types, whose values are implicitly converted to integers.
786
787 @node Unary operators
788 @section Unary operators
789 @cindex Unary operators
790
791 As a GNU extension, @command{gfortran} allows unary plus and unary
792 minus operators to appear as the second operand of binary arithmetic
793 operators without the need for parenthesis.
794
795 @smallexample
796        X = Y * -Z
797 @end smallexample
798
799 @node Implicitly interconvert LOGICAL and INTEGER
800 @section Implicitly interconvert LOGICAL and INTEGER
801 @cindex Implicitly interconvert LOGICAL and INTEGER
802
803 As a GNU extension for backwards compatibility with other compilers,
804 @command{gfortran} allows the implicit conversion of LOGICALs to INTEGERs
805 and vice versa.  When converting from a LOGICAL to an INTEGER, the numeric
806 value of @code{.FALSE.} is zero, and that of @code{.TRUE.} is one.  When
807 converting from INTEGER to LOGICAL, the value zero is interpreted as
808 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
809
810 @smallexample
811        INTEGER*4 i
812        i = .FALSE.
813 @end smallexample
814
815 @node Hollerith constants support
816 @section Hollerith constants support
817 @cindex Hollerith constants
818
819 A Hollerith constant is a string of characters preceded by the letter @samp{H}
820 or @samp{h}, and there must be an literal, unsigned, nonzero default integer
821 constant indicating the number of characters in the string. Hollerith constants
822 are stored as byte strings, one character per byte.
823
824 @command{gfortran} supports Hollerith constants. They can be used as the right
825 hands in the @code{DATA} statement and @code{ASSIGN} statement, also as the
826 arguments. The left hands can be of Integer, Real, Complex and Logical type.
827 The constant will be padded or trancated to fit the size of left hand.
828
829 Valid Hollerith constants examples:
830 @smallexample
831 complex*16 x(2)
832 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
833 call foo (4H abc)
834 x(1) = 16Habcdefghijklmnop
835 @end smallexample
836
837 Invalid Hollerith constants examples:
838 @smallexample
839 integer*4 a
840 a = 8H12345678 ! The Hollerith constant is too long. It will be truncated.
841 a = 0H         ! At least one character needed.
842 @end smallexample
843
844 @node Cray pointers
845 @section Cray pointers
846 @cindex Cray pointers
847
848 Cray pointers are part of a non-standard extension that provides a
849 C-like pointer in Fortran.  This is accomplished through a pair of
850 variables: an integer "pointer" that holds a memory address, and a
851 "pointee" that is used to dereference the pointer.
852
853 Pointer/pointee pairs are declared in statements of the form:
854 @smallexample
855         pointer ( <pointer> , <pointee> )
856 @end smallexample
857 or,
858 @smallexample
859         pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
860 @end smallexample
861 The pointer is an integer that is intended to hold a memory address.
862 The pointee may be an array or scalar.  A pointee can be an assumed
863 size array -- that is, the last dimension may be left unspecified by
864 using a '*' in place of a value -- but a pointee cannot be an assumed
865 shape array.  No space is allocated for the pointee.
866
867 The pointee may have its type declared before or after the pointer
868 statement, and its array specification (if any) may be declared
869 before, during, or after the pointer statement.  The pointer may be
870 declared as an integer prior to the pointer statement.  However, some
871 machines have default integer sizes that are different than the size
872 of a pointer, and so the following code is not portable:
873 @smallexample
874         integer ipt
875         pointer (ipt, iarr)
876 @end smallexample
877 If a pointer is declared with a kind that is too small, the compiler
878 will issue a warning; the resulting binary will probably not work
879 correctly, because the memory addresses stored in the pointers may be
880 truncated.  It is safer to omit the first line of the above example;
881 if explicit declaration of ipt's type is omitted, then the compiler
882 will ensure that ipt is an integer variable large enough to hold a
883 pointer.
884
885 Pointer arithmetic is valid with Cray pointers, but it is not the same
886 as C pointer arithmetic.  Cray pointers are just ordinary integers, so
887 the user is responsible for determining how many bytes to add to a
888 pointer in order to increment it.  Consider the following example:
889 @smallexample
890         real target(10)
891         real pointee(10)
892         pointer (ipt, pointee)
893         ipt = loc (target)
894         ipt = ipt + 1       
895 @end smallexample
896 The last statement does not set ipt to the address of
897 @code{target(1)}, as one familiar with C pointer arithmetic might
898 expect.  Adding 1 to ipt just adds one byte to the address stored in
899 ipt.
900
901 Any expression involving the pointee will be translated to use the
902 value stored in the pointer as the base address.
903
904 To get the address of elements, this extension provides an intrinsic
905 function loc(), loc() is essentially the C '&' operator, except the
906 address is cast to an integer type:
907 @smallexample
908         real ar(10)
909         pointer(ipt, arpte(10))
910         real arpte
911         ipt = loc(ar)  ! Makes arpte is an alias for ar
912         arpte(1) = 1.0 ! Sets ar(1) to 1.0
913 @end smallexample
914 The pointer can also be set by a call to a malloc-type
915 function.  There is no malloc intrinsic implemented as part of the
916 Cray pointer extension, but it might be a useful future addition to
917 @command{gfortran}.  Even without an intrinsic malloc function,
918 dynamic memory allocation can be combined with Cray pointers by
919 calling a short C function:
920 @smallexample
921 mymalloc.c:
922
923         void mymalloc_(void **ptr, int *nbytes)
924         @{
925             *ptr = malloc(*nbytes);
926             return;
927         @}
928
929 caller.f:
930
931         program caller
932         integer ipinfo;
933         real*4 data
934         pointer (ipdata, data(1024))
935         call mymalloc(ipdata,4*1024)
936         end
937 @end smallexample
938 Cray pointees often are used to alias an existing variable.  For
939 example:
940 @smallexample
941         integer target(10)
942         integer iarr(10)
943         pointer (ipt, iarr)
944         ipt = loc(target)
945 @end smallexample
946 As long as ipt remains unchanged, iarr is now an alias for target.
947 The optimizer, however, will not detect this aliasing, so it is unsafe
948 to use iarr and target simultaneously.  Using a pointee in any way
949 that violates the Fortran aliasing rules or assumptions is illegal.
950 It is the user's responsibility to avoid doing this; the compiler
951 works under the assumption that no such aliasing occurs.
952
953 Cray pointers will work correctly when there is no aliasing (i.e.,
954 when they're used to access a dynamically allocated block of memory),
955 and also in any routine where a pointee is used, but any variable with
956 which it shares storage is not used.  Code that violates these rules
957 may not run as the user intends.  This is not a bug in the optimizer;
958 any code that violates the aliasing rules is illegal.  (Note that this
959 is not unique to gfortran; any Fortran compiler that supports Cray
960 pointers will ``incorrectly'' optimize code with illegal aliasing.)
961
962 There are a number of restrictions on the attributes that can be
963 applied to Cray pointers and pointees.  Pointees may not have the
964 attributes ALLOCATABLE, INTENT, OPTIONAL, DUMMY, TARGET, EXTERNAL,
965 INTRINSIC, or POINTER.  Pointers may not have the attributes
966 DIMENSION, POINTER, TARGET, ALLOCATABLE, EXTERNAL, or INTRINSIC.
967 Pointees may not occur in more than one pointer statement.  A pointee
968 cannot be a pointer.  Pointees cannot occur in equivalence, common, or
969 data statements.
970
971 A pointer may be modified during the course of a program, and this
972 will change the location to which the pointee refers.  However, when
973 pointees are passed as arguments, they are treated as ordinary
974 variables in the invoked function.  Subsequent changes to the pointer
975 will not change the base address of the array that was passed.
976
977 @include intrinsic.texi
978 @c ---------------------------------------------------------------------
979 @c Contributing
980 @c ---------------------------------------------------------------------
981
982 @node Contributing
983 @chapter Contributing
984 @cindex Contributing
985
986 Free software is only possible if people contribute to efforts
987 to create it.
988 We're always in need of more people helping out with ideas
989 and comments, writing documentation and contributing code.
990
991 If you want to contribute to GNU Fortran 95,
992 have a look at the long lists of projects you can take on.
993 Some of these projects are small,
994 some of them are large;
995 some are completely orthogonal to the rest of what is
996 happening on @command{gfortran},
997 but others are ``mainstream'' projects in need of enthusiastic hackers.
998 All of these projects are important!
999 We'll eventually get around to the things here,
1000 but they are also things doable by someone who is willing and able.
1001
1002 @menu
1003 * Contributors::
1004 * Projects::
1005 @end menu
1006
1007
1008 @node Contributors
1009 @section Contributors to GNU Fortran 95
1010 @cindex Contributors
1011 @cindex Credits
1012 @cindex Authors
1013
1014 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
1015 also the initiator of the whole project.  Thanks Andy!
1016 Most of the interface with GCC was written by @emph{Paul Brook}.
1017
1018 The following individuals have contributed code and/or
1019 ideas and significant help to the gfortran project
1020 (in no particular order): 
1021
1022 @itemize @minus
1023 @item Andy Vaught
1024 @item Katherine Holcomb
1025 @item Tobias Schl├╝ter
1026 @item Steven Bosscher
1027 @item Toon Moene
1028 @item Tim Prince
1029 @item Niels Kristian Bech Jensen
1030 @item Steven Johnson
1031 @item Paul Brook
1032 @item Feng Wang
1033 @item Bud Davis
1034 @end itemize
1035
1036 The following people have contributed bug reports,
1037 smaller or larger patches,
1038 and much needed feedback and encouragement for the
1039 @command{gfortran} project: 
1040
1041 @itemize @minus
1042 @item Erik Schnetter
1043 @item Bill Clodius
1044 @item Kate Hedstrom
1045 @end itemize
1046
1047 Many other individuals have helped debug,
1048 test and improve @command{gfortran} over the past two years,
1049 and we welcome you to do the same!
1050 If you already have done so,
1051 and you would like to see your name listed in the
1052 list above, please contact us.
1053
1054
1055 @node Projects
1056 @section Projects
1057
1058 @table @emph
1059
1060 @item Help build the test suite
1061 Solicit more code for donation to the test suite.
1062 We can keep code private on request.
1063
1064 @item Bug hunting/squishing
1065 Find bugs and write more test cases!
1066 Test cases are especially very welcome,
1067 because it allows us to concentrate on fixing bugs
1068 instead of isolating them.
1069
1070 @item Smaller projects (``bug'' fixes):
1071   @itemize @minus
1072   @item Allow init exprs to be numbers raised to integer powers.
1073   @item Implement correct rounding.
1074   @item Implement F restrictions on Fortran 95 syntax.
1075   @item See about making Emacs-parsable error messages.
1076   @end itemize
1077 @end table
1078
1079 If you wish to work on the runtime libraries,
1080 please contact a project maintainer.
1081 @c TODO: email!
1082
1083
1084 @c ---------------------------------------------------------------------
1085 @c Standards
1086 @c ---------------------------------------------------------------------
1087
1088 @node Standards
1089 @chapter Standards
1090 @cindex Standards
1091
1092 The GNU Fortran 95 Compiler aims to be a conforming implementation of
1093 ISO/IEC 1539:1997 (Fortran 95).
1094
1095 In the future it may also support other variants of and extensions to
1096 the Fortran language.  These include ANSI Fortran 77, ISO Fortran 90,
1097 ISO Fortran 2003 and OpenMP.
1098
1099 @menu
1100 * Fortran 2003 status::
1101 @end menu
1102
1103 @node Fortran 2003 status
1104 @section Fortran 2003 status
1105
1106 Although @command{gfortran} focuses on implementing the Fortran 95
1107 standard for the time being, a few Fortran 2003 features are currently
1108 available.
1109
1110 @itemize
1111 @item 
1112 Intrinsics @code{command_argument_count}, @code{get_command},
1113 @code{get_command_argument}, and @code{get_environment_variable}.
1114
1115 @item 
1116 Array constructors using square brackets. That is, @code{[...]} rather
1117 than @code{(/.../)}.
1118
1119 @item 
1120 @code{FLUSH} statement.
1121
1122 @item
1123 @code{IOMSG=} specifier for I/O statements.
1124 @end itemize
1125
1126
1127 @c ---------------------------------------------------------------------
1128 @c Index
1129 @c ---------------------------------------------------------------------
1130
1131 @node Index
1132 @unnumbered Index
1133
1134 @printindex cp
1135
1136 @bye