diff options
Diffstat (limited to 'contrib/gcc/f/g77.texi')
| -rw-r--r-- | contrib/gcc/f/g77.texi | 15091 |
1 files changed, 0 insertions, 15091 deletions
diff --git a/contrib/gcc/f/g77.texi b/contrib/gcc/f/g77.texi deleted file mode 100644 index eaab2543e6b4..000000000000 --- a/contrib/gcc/f/g77.texi +++ /dev/null @@ -1,15091 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename g77.info - -@set last-update 1999-06-06 -@set copyrights-g77 1995-1999 - -@include root.texi - -@c This tells @include'd files that they're part of the overall G77 doc -@c set. (They might be part of a higher-level doc set too.) -@set DOC-G77 - -@c @setfilename useg77.info -@c @setfilename portg77.info -@c To produce the full manual, use the "g77.info" setfilename, and -@c make sure the following do NOT begin with '@c' (and the @clear lines DO) -@set INTERNALS -@set USING -@c To produce a user-only manual, use the "useg77.info" setfilename, and -@c make sure the following does NOT begin with '@c': -@c @clear INTERNALS -@c To produce a porter-only manual, use the "portg77.info" setfilename, -@c and make sure the following does NOT begin with '@c': -@c @clear USING - -@c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from gcc.texi) -@c @smallbook - -@c i also commented out the finalout command, so if there *are* any -@c overfulls, you'll (hopefully) see the rectangle in the right hand -@c margin. -- burley 1999-03-13 (from mew's comment in gcc.texi). -@c @finalout - -@ifset INTERNALS -@ifset USING -@settitle Using and Porting GNU Fortran -@end ifset -@end ifset -@c seems reasonable to assume at least one of INTERNALS or USING is set... -@ifclear INTERNALS -@settitle Using GNU Fortran -@end ifclear -@ifclear USING -@settitle Porting GNU Fortran -@end ifclear -@c then again, have some fun -@ifclear INTERNALS -@ifclear USING -@settitle Doing Squat with GNU Fortran -@end ifclear -@end ifclear - -@syncodeindex fn cp -@syncodeindex vr cp -@c %**end of header - -@c Cause even numbered pages to be printed on the left hand side of -@c the page and odd numbered pages to be printed on the right hand -@c side of the page. Using this, you can print on both sides of a -@c sheet of paper and have the text on the same part of the sheet. - -@c The text on right hand pages is pushed towards the right hand -@c margin and the text on left hand pages is pushed toward the left -@c hand margin. -@c (To provide the reverse effect, set bindingoffset to -0.75in.) - -@c @tex -@c \global\bindingoffset=0.75in -@c \global\normaloffset =0.75in -@c @end tex - -@ifinfo -@dircategory Programming -@direntry -* g77: (g77). The GNU Fortran compiler. -@end direntry -@ifset INTERNALS -@ifset USING -This file documents the use and the internals of the GNU Fortran (@code{g77}) -compiler. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifset -@end ifset -@ifclear USING -This file documents the internals of the GNU Fortran (@code{g77}) compiler. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifclear -@ifclear INTERNALS -This file documents the use of the GNU Fortran (@code{g77}) compiler. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifclear - -Published by the Free Software Foundation -59 Temple Place - Suite 330 -Boston, MA 02111-1307 USA - -Copyright (C) @value{copyrights-g77} Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -sections entitled ``GNU General Public License,'' ``Funding for Free -Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are -included exactly as in the original, and provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the sections entitled ``GNU General Public License,'' -``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look -And Feel'@w{}'', and this permission notice, may be included in -translations approved by the Free Software Foundation instead of in the -original English. -@end ifinfo - -Contributed by James Craig Burley (@email{@value{email-burley}}). -Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that -was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}). - -@setchapternewpage odd -@c @finalout -@titlepage -@ifset INTERNALS -@ifset USING -@center @titlefont{Using and Porting GNU Fortran} - -@end ifset -@end ifset -@ifclear INTERNALS -@title Using GNU Fortran -@end ifclear -@ifclear USING -@title Porting GNU Fortran -@end ifclear -@sp 2 -@center James Craig Burley -@sp 3 -@center Last updated @value{last-update} -@sp 1 -@center for version @value{version-g77} -@page -@vskip 0pt plus 1filll -Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc. -@sp 2 -For the @value{which-g77} Version* -@sp 1 -Published by the Free Software Foundation @* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307, USA@* -@c Last printed ??ber, 19??.@* -@c Printed copies are available for $? each.@* -@c ISBN ??? -@sp 1 -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -sections entitled ``GNU General Public License,'' ``Funding for Free -Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are -included exactly as in the original, and provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the sections entitled ``GNU General Public License,'' -``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look -And Feel'@w{}'', and this permission notice, may be included in -translations approved by the Free Software Foundation instead of in the -original English. -@end titlepage -@page - -@ifinfo - -@node Top, Copying,, (DIR) -@top Introduction -@cindex Introduction - -@ifset INTERNALS -@ifset USING -This manual documents how to run, install and port @code{g77}, -as well as its new features and incompatibilities, -and how to report bugs. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifset -@end ifset - -@ifclear INTERNALS -This manual documents how to run and install @code{g77}, -as well as its new features and incompatibilities, and how to report -bugs. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifclear -@ifclear USING -This manual documents how to port @code{g77}, -as well as its new features and incompatibilities, -and how to report bugs. -It corresponds to the @value{which-g77} version of @code{g77}. -@end ifclear - -@end ifinfo - -@ifset DEVELOPMENT -@emph{Warning:} This document is still under development, -and might not accurately reflect the @code{g77} code base -of which it is a part. -Efforts are made to keep it somewhat up-to-date, -but they are particularly concentrated -on any version of this information -that is distributed as part of a @emph{released} @code{g77}. - -In particular, while this document is intended to apply to -the @value{which-g77} version of @code{g77}, -only an official @emph{release} of that version -is expected to contain documentation that is -most consistent with the @code{g77} product in that version. -@end ifset - -@menu -* Copying:: GNU General Public License says - how you can copy and share GNU Fortran. -* Contributors:: People who have contributed to GNU Fortran. -* Funding:: How to help assure continued work for free software. -* Funding GNU Fortran:: How to help assure continued work on GNU Fortran. -* Look and Feel:: Protect your freedom---fight ``look and feel''. -@ifset USING -* Getting Started:: Finding your way around this manual. -* What is GNU Fortran?:: How @code{g77} fits into the universe. -* G77 and GCC:: You can compile Fortran, C, or other programs. -* Invoking G77:: Command options supported by @code{g77}. -* News:: News about recent releases of @code{g77}. -* Changes:: User-visible changes to recent releases of @code{g77}. -* Language:: The GNU Fortran language. -* Compiler:: The GNU Fortran compiler. -* Other Dialects:: Dialects of Fortran supported by @code{g77}. -* Other Compilers:: Fortran compilers other than @code{g77}. -* Other Languages:: Languages other than Fortran. -* Installation:: How to configure, compile and install GNU Fortran. -* Debugging and Interfacing:: How @code{g77} generates code. -* Collected Fortran Wisdom:: How to avoid Trouble. -* Trouble:: If you have trouble with GNU Fortran. -* Open Questions:: Things we'd like to know. -* Bugs:: How, why, and where to report bugs. -* Service:: How to find suppliers of support for GNU Fortran. -@end ifset -@ifset INTERNALS -* Adding Options:: Guidance on teaching @code{g77} about new options. -* Projects:: Projects for @code{g77} internals hackers. -* Front End:: Design and implementation of the @code{g77} front end. -@end ifset - -* M: Diagnostics. Diagnostics produced by @code{g77}. - -* Index:: Index of concepts and symbol names. -@end menu -@c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)! - -@node Copying -@unnumbered GNU GENERAL PUBLIC LICENSE -@center Version 2, June 1991 - -@display -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software---to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end iftex -@ifinfo -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifinfo - -@enumerate 0 -@item -This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The ``Program'', below, -refers to any such program or work, and a ``work based on the Program'' -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term ``modification''.) Each licensee is addressed as ``you''. - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -@item -You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -@item -You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@enumerate a -@item -You must cause the modified files to carry prominent notices -stating that you changed the files and the date of any change. - -@item -You must cause any work that you distribute or publish, that in -whole or in part contains or is derived from the Program or any -part thereof, to be licensed as a whole at no charge to all third -parties under the terms of this License. - -@item -If the modified program normally reads commands interactively -when run, you must cause it, when started running for such -interactive use in the most ordinary way, to print or display an -announcement including an appropriate copyright notice and a -notice that there is no warranty (or else, saying that you provide -a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this -License. (Exception: if the Program itself is interactive but -does not normally print such an announcement, your work based on -the Program is not required to print an announcement.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - -@enumerate a -@item -Accompany it with the complete corresponding machine-readable -source code, which must be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, - -@item -Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your -cost of physically performing source distribution, a complete -machine-readable copy of the corresponding source code, to be -distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -@item -Accompany it with the information you received as to the offer -to distribute corresponding source code. (This alternative is -allowed only for noncommercial distribution and only if you -received the program in object code or executable form with such -an offer, in accord with Subsection b above.) -@end enumerate - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -@item -Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and ``any -later version'', you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - -@item -If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@item -BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifinfo -@center END OF TERMS AND CONDITIONS -@end ifinfo - -@page -@unnumberedsec How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) 19@var{yy} @var{name of author} - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - -@smallexample -Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} -Gnomovision comes with ABSOLUTELY NO WARRANTY; for details -type `show w'. -This is free software, and you are welcome to redistribute it -under certain conditions; type `show c' for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, the -commands you use may be called something other than @samp{show w} and -@samp{show c}; they could even be mouse-clicks or menu items---whatever -suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the program, if -necessary. Here is a sample; alter the names: - -@smallexample -Yoyodyne, Inc., hereby disclaims all copyright interest in the program -`Gnomovision' (which makes passes at compilers) written by James Hacker. - -@var{signature of Ty Coon}, 1 April 1989 -Ty Coon, President of Vice -@end smallexample - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. - -@node Contributors -@unnumbered Contributors to GNU Fortran -@cindex contributors -@cindex credits - -In addition to James Craig Burley, who wrote the front end, -many people have helped create and improve GNU Fortran. - -@itemize @bullet -@item -The packaging and compiler portions of GNU Fortran are based largely -on the GNU CC compiler. -@xref{Contributors,,Contributors to GNU CC,gcc,Using and Porting GNU CC}, -for more information. - -@item -The run-time library used by GNU Fortran is a repackaged version -of the @code{libf2c} library (combined from the @code{libF77} and -@code{libI77} libraries) provided as part of @code{f2c}, available for -free from @code{netlib} sites on the Internet. - -@item -Cygnus Support and The Free Software Foundation contributed -significant money and/or equipment to Craig's efforts. - -@item -The following individuals served as alpha testers prior to @code{g77}'s -public release. This work consisted of testing, researching, sometimes -debugging, and occasionally providing small amounts of code and fixes -for @code{g77}, plus offering plenty of helpful advice to Craig: - -@itemize @w{} -@item -Jonathan Corbet -@item -Dr.@: Mark Fernyhough -@item -Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp} -@item -Kate Hedstrom -@item -Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr} -@item -Dr.@: A. O. V. Le Blanc -@item -Dave Love -@item -Rick Lutowski -@item -Toon Moene -@item -Rick Niles -@item -Derk Reefman -@item -Wayne K. Schroll -@item -Bill Thorson -@item -Pedro A. M. Vazquez -@item -Ian Watson -@end itemize - -@item -Scott Snyder (@email{snyder@@d0sgif.fnal.gov}) -provided the patch to add rudimentary support -for @code{INTEGER*1}, @code{INTEGER*2}, and -@code{LOGICAL*1}. -This inspired Craig to add further support, -even though the resulting support -would still be incomplete, because version 0.6 is still -a ways off. - -@item -David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired -and encouraged Craig to rewrite the documentation in texinfo -format by contributing a first pass at a translation of the -old @file{g77-0.5.16/f/DOC} file. - -@item -Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed -some analysis of generated code as part of an overall project -to improve @code{g77} code generation to at least be as good -as @code{f2c} used in conjunction with @code{gcc}. -So far, this has resulted in the three, somewhat -experimental, options added by @code{g77} to the @code{gcc} -compiler and its back end. - -(These, in turn, have made their way into the @code{egcs} -version of the compiler, and do not exist in @code{gcc} -version 2.8 or versions of @code{g77} based on that version -of @code{gcc}.) - -@item -John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements. - -@item -Thanks to Mary Cortani and the staff at Craftwork Solutions -(@email{support@@craftwork.com}) for all of their support. - -@item -Many other individuals have helped debug, test, and improve @code{g77} -over the past several years, and undoubtedly more people -will be doing so in the future. -If you have done so, and would like -to see your name listed in the above list, please ask! -The default is that people wish to remain anonymous. -@end itemize - -@node Funding -@chapter Funding Free Software - -If you want to have more free software a few years from now, it makes -sense for you to help encourage people to contribute funds for its -development. The most effective approach known is to encourage -commercial redistributors to donate. - -Users of free software systems can boost the pace of development by -encouraging for-a-fee distributors to donate part of their selling price -to free software developers---the Free Software Foundation, and others. - -The way to convince distributors to do this is to demand it and expect -it from them. So when you compare distributors, judge them partly by -how much they give to free software development. Show distributors -they must compete to be the one who gives the most. - -To make this approach work, you must insist on numbers that you can -compare, such as, ``We will donate ten dollars to the Frobnitz project -for each disk sold.'' Don't be satisfied with a vague promise, such as -``A portion of the profits are donated,'' since it doesn't give a basis -for comparison. - -Even a precise fraction ``of the profits from this disk'' is not very -meaningful, since creative accounting and unrelated business decisions -can greatly alter what fraction of the sales price counts as profit. -If the price you pay is $50, ten percent of the profit is probably -less than a dollar; it might be a few cents, or nothing at all. - -Some redistributors do development work themselves. This is useful too; -but to keep everyone honest, you need to inquire how much they do, and -what kind. Some kinds of development make much more long-term -difference than others. For example, maintaining a separate version of -a program contributes very little; maintaining the standard version of a -program for the whole community contributes much. Easy new ports -contribute little, since someone else would surely do them; difficult -ports such as adding a new CPU to the GNU C compiler contribute more; -major new features or packages contribute the most. - -By establishing the idea that supporting further development is ``the -proper thing to do'' when distributing free software for a fee, we can -assure a steady flow of resources into making more free software. - -@display -Copyright (C) 1994 Free Software Foundation, Inc. -Verbatim copying and redistribution of this section is permitted -without royalty; alteration is not permitted. -@end display - -@node Funding GNU Fortran -@chapter Funding GNU Fortran -@cindex funding improvements -@cindex improvements, funding - -Work on GNU Fortran is still being done mostly by its author, -James Craig Burley (@email{@value{email-burley}}), who is a volunteer -for, not an employee of, the Free Software Foundation (FSF). -(He has a web page at @uref{@value{www-burley}}.) - -As with other GNU software, funding is important because it can pay for -needed equipment, personnel, and so on. - -@cindex FSF, funding the -@cindex funding the FSF -The FSF provides information on the best way to fund ongoing -development of GNU software (such as GNU Fortran) in documents -such as the ``GNUS Bulletin''. -Email @email{gnu@@gnu.org} for information on funding the FSF. - -To fund specific GNU Fortran work in particular, the FSF might -provide a means for that, but the FSF does not provide direct funding -to the author of GNU Fortran to continue his work. The FSF has -employee salary restrictions that can be incompatible with the -financial needs of some volunteers, who therefore choose to -remain volunteers and thus be able to be free to do contract work -and otherwise make their own schedules for doing GNU work. - -Still, funding the FSF at least indirectly benefits work -on specific projects like GNU Fortran because it ensures the -continuing operation of the FSF offices, their workstations, their -network connections, and so on, which are invaluable to volunteers. -(Similarly, hiring Cygnus Support can help a project like GNU -Fortran---Cygnus has been a long-time donor of equipment usage to the author -of GNU Fortran, and this too has been invaluable---see @ref{Contributors}.) - -Currently, the only way to directly fund the author of GNU Fortran -in his work on that project is to hire him for the work you want -him to do, or donate money to him. -Several people have done this -already, with the result that he has not needed to immediately find -contract work on a few occasions. -If more people did this, he -would be able to plan on not doing contract work for many months and -could thus devote that time to work on projects (such as the planned -changes for 0.6) that require longer timeframes to complete. -For the latest information on the status of the author, do -@kbd{finger -l burley@@gnu.org} on a UNIX system -(or any system with a command like UNIX @code{finger}). - -Another important way to support work on GNU Fortran is to volunteer -to help out. -Work is needed on documentation, testing, porting -to various machines, and in some cases, coding (although major -changes planned for version 0.6 make it difficult to add manpower to this -area). -Email @email{@value{email-general}} to volunteer for this work. - -@xref{Funding,,Funding Free Software}, for more information. - -@node Look and Feel -@chapter Protect Your Freedom---Fight ``Look And Feel'' -@c the above chapter heading overflows onto the next line. --mew 1/26/93 - -To preserve the ability to write free software, including replacements -for proprietary software, authors must be free to replicate the -user interface to which users of existing software have become -accustomed. - -@xref{Look and Feel,,Protect Your Freedom---Fight ``Look And Feel'', -gcc,Using and Porting GNU CC}, for more information. - -@node Getting Started -@chapter Getting Started -@cindex getting started -@cindex new users -@cindex newbies -@cindex beginners - -If you don't need help getting started reading the portions -of this manual that are most important to you, you should skip -this portion of the manual. - -If you are new to compilers, especially Fortran compilers, or -new to how compilers are structured under UNIX and UNIX-like -systems, you'll want to see @ref{What is GNU Fortran?}. - -If you are new to GNU compilers, or have used only one GNU -compiler in the past and not had to delve into how it lets -you manage various versions and configurations of @code{gcc}, -you should see @ref{G77 and GCC}. - -Everyone except experienced @code{g77} users should -see @ref{Invoking G77}. - -If you're acquainted with previous versions of @code{g77}, -you should see @ref{News,,News About GNU Fortran}. -Further, if you've actually used previous versions of @code{g77}, -especially if you've written or modified Fortran code to -be compiled by previous versions of @code{g77}, you -should see @ref{Changes}. - -If you intend to write or otherwise compile code that is -not already strictly conforming ANSI FORTRAN 77---and this -is probably everyone---you should see @ref{Language}. - -If you don't already have @code{g77} installed on your -system, you must see @ref{Installation}. - -If you run into trouble getting Fortran code to compile, -link, run, or work properly, you might find answers -if you see @ref{Debugging and Interfacing}, -see @ref{Collected Fortran Wisdom}, -and see @ref{Trouble}. -You might also find that the problems you are encountering -are bugs in @code{g77}---see @ref{Bugs}, for information on -reporting them, after reading the other material. - -If you need further help with @code{g77}, or with -freely redistributable software in general, -see @ref{Service}. - -If you would like to help the @code{g77} project, -see @ref{Funding GNU Fortran}, for information on -helping financially, and see @ref{Projects}, for information -on helping in other ways. - -If you're generally curious about the future of -@code{g77}, see @ref{Projects}. -If you're curious about its past, -see @ref{Contributors}, -and see @ref{Funding GNU Fortran}. - -To see a few of the questions maintainers of @code{g77} have, -and that you might be able to answer, -see @ref{Open Questions}. - -@ifset USING -@node What is GNU Fortran? -@chapter What is GNU Fortran? -@cindex concepts, basic -@cindex basic concepts - -GNU Fortran, or @code{g77}, is designed initially as a free replacement -for, or alternative to, the UNIX @code{f77} command. -(Similarly, @code{gcc} is designed as a replacement -for the UNIX @code{cc} command.) - -@code{g77} also is designed to fit in well with the other -fine GNU compilers and tools. - -Sometimes these design goals conflict---in such cases, resolution -often is made in favor of fitting in well with Project GNU. -These cases are usually identified in the appropriate -sections of this manual. - -@cindex compilers -As compilers, @code{g77}, @code{gcc}, and @code{f77} -share the following characteristics: - -@itemize @bullet -@cindex source code -@cindex file, source -@cindex code, source -@cindex source file -@item -They read a user's program, stored in a file and -containing instructions written in the appropriate -language (Fortran, C, and so on). -This file contains @dfn{source code}. - -@cindex translation of user programs -@cindex machine code -@cindex code, machine -@cindex mistakes -@item -They translate the user's program into instructions -a computer can carry out more quickly than it takes -to translate the instructions in the first place. -These instructions are called @dfn{machine code}---code -designed to be efficiently translated and processed -by a machine such as a computer. -Humans usually aren't as good writing machine code -as they are at writing Fortran or C, because -it is easy to make tiny mistakes writing machine code. -When writing Fortran or C, it is easy -to make big mistakes. - -@cindex debugger -@cindex bugs, finding -@cindex @code{gdb}, command -@cindex commands, @code{gdb} -@item -They provide information in the generated machine code -that can make it easier to find bugs in the program -(using a debugging tool, called a @dfn{debugger}, -such as @code{gdb}). - -@cindex libraries -@cindex linking -@cindex @code{ld} command -@cindex commands, @code{ld} -@item -They locate and gather machine code already generated -to perform actions requested by statements in -the user's program. -This machine code is organized -into @dfn{libraries} and is located and gathered -during the @dfn{link} phase of the compilation -process. -(Linking often is thought of as a separate -step, because it can be directly invoked via the -@code{ld} command. -However, the @code{g77} and @code{gcc} -commands, as with most compiler commands, automatically -perform the linking step by calling on @code{ld} -directly, unless asked to not do so by the user.) - -@cindex language, incorrect use of -@cindex incorrect use of language -@item -They attempt to diagnose cases where the user's -program contains incorrect usages of the language. -The @dfn{diagnostics} produced by the compiler -indicate the problem and the location in the user's -source file where the problem was first noticed. -The user can use this information to locate and -fix the problem. -@cindex diagnostics, incorrect -@cindex incorrect diagnostics -@cindex error messages, incorrect -@cindex incorrect error messages -(Sometimes an incorrect usage -of the language leads to a situation where the -compiler can no longer make any sense of what -follows---while a human might be able to---and -thus ends up complaining about many ``problems'' -it encounters that, in fact, stem from just one -problem, usually the first one reported.) - -@cindex warnings -@cindex questionable instructions -@item -They attempt to diagnose cases where the user's -program contains a correct usage of the language, -but instructs the computer to do something questionable. -These diagnostics often are in the form of @dfn{warnings}, -instead of the @dfn{errors} that indicate incorrect -usage of the language. -@end itemize - -How these actions are performed is generally under the -control of the user. -Using command-line options, the user can specify -how persnickety the compiler is to be regarding -the program (whether to diagnose questionable usage -of the language), how much time to spend making -the generated machine code run faster, and so on. - -@cindex components of g77 -@cindex @code{g77}, components of -@code{g77} consists of several components: - -@cindex @code{gcc}, command -@cindex commands, @code{gcc} -@itemize @bullet -@item -A modified version of the @code{gcc} command, which also might be -installed as the system's @code{cc} command. -(In many cases, @code{cc} refers to the -system's ``native'' C compiler, which -might be a non-GNU compiler, or an older version -of @code{gcc} considered more stable or that is -used to build the operating system kernel.) - -@cindex @code{g77}, command -@cindex commands, @code{g77} -@item -The @code{g77} command itself, which also might be installed as the -system's @code{f77} command. - -@cindex libg2c library -@cindex libf2c library -@cindex libraries, libf2c -@cindex libraries, libg2c -@cindex run-time, library -@item -The @code{libg2c} run-time library. -This library contains the machine code needed to support -capabilities of the Fortran language that are not directly -provided by the machine code generated by the @code{g77} -compilation phase. - -@code{libg2c} is just the unique name @code{g77} gives -to its version of @code{libf2c} to distinguish it from -any copy of @code{libf2c} installed from @code{f2c} -(or versions of @code{g77} that built @code{libf2c} under -that same name) -on the system. - -The maintainer of @code{libf2c} currently is -@email{dmg@@bell-labs.com}. - -@cindex @code{f771}, program -@cindex programs, @code{f771} -@cindex assembler -@cindex @code{as} command -@cindex commands, @code{as} -@cindex assembly code -@cindex code, assembly -@item -The compiler itself, internally named @code{f771}. - -Note that @code{f771} does not generate machine code directly---it -generates @dfn{assembly code} that is a more readable form -of machine code, leaving the conversion to actual machine code -to an @dfn{assembler}, usually named @code{as}. -@end itemize - -@code{gcc} is often thought of as ``the C compiler'' only, -but it does more than that. -Based on command-line options and the names given for files -on the command line, @code{gcc} determines which actions to perform, including -preprocessing, compiling (in a variety of possible languages), assembling, -and linking. - -@cindex driver, gcc command as -@cindex @code{gcc}, command as driver -@cindex executable file -@cindex files, executable -@cindex cc1 program -@cindex programs, cc1 -@cindex preprocessor -@cindex cpp program -@cindex programs, cpp -For example, the command @samp{gcc foo.c} @dfn{drives} the file -@file{foo.c} through the preprocessor @code{cpp}, then -the C compiler (internally named -@code{cc1}), then the assembler (usually @code{as}), then the linker -(@code{ld}), producing an executable program named @file{a.out} (on -UNIX systems). - -@cindex cc1plus program -@cindex programs, cc1plus -As another example, the command @samp{gcc foo.cc} would do much the same as -@samp{gcc foo.c}, but instead of using the C compiler named @code{cc1}, -@code{gcc} would use the C++ compiler (named @code{cc1plus}). - -@cindex @code{f771}, program -@cindex programs, @code{f771} -In a GNU Fortran installation, @code{gcc} recognizes Fortran source -files by name just like it does C and C++ source files. -It knows to use the Fortran compiler named @code{f771}, instead of -@code{cc1} or @code{cc1plus}, to compile Fortran files. - -@cindex @code{gcc}, not recognizing Fortran source -@cindex unrecognized file format -@cindex file format not recognized -Non-Fortran-related operation of @code{gcc} is generally -unaffected by installing the GNU Fortran version of @code{gcc}. -However, without the installed version of @code{gcc} being the -GNU Fortran version, @code{gcc} will not be able to compile -and link Fortran programs---and since @code{g77} uses @code{gcc} -to do most of the actual work, neither will @code{g77}! - -@cindex @code{g77}, command -@cindex commands, @code{g77} -The @code{g77} command is essentially just a front-end for -the @code{gcc} command. -Fortran users will normally use @code{g77} instead of @code{gcc}, -because @code{g77} -knows how to specify the libraries needed to link with Fortran programs -(@code{libg2c} and @code{lm}). -@code{g77} can still compile and link programs and -source files written in other languages, just like @code{gcc}. - -@cindex printing version information -@cindex version information, printing -The command @samp{g77 -v} is a quick -way to display lots of version information for the various programs -used to compile a typical preprocessed Fortran source file---this -produces much more output than @samp{gcc -v} currently does. -(If it produces an error message near the end of the output---diagnostics -from the linker, usually @code{ld}---you might -have an out-of-date @code{libf2c} that improperly handles -complex arithmetic.) -In the output of this command, the line beginning @samp{GNU Fortran Front -End} identifies the version number of GNU Fortran; immediately -preceding that line is a line identifying the version of @code{gcc} -with which that version of @code{g77} was built. - -@cindex libf2c library -@cindex libraries, libf2c -The @code{libf2c} library is distributed with GNU Fortran for -the convenience of its users, but is not part of GNU Fortran. -It contains the procedures -needed by Fortran programs while they are running. - -@cindex in-line code -@cindex code, in-line -For example, while code generated by @code{g77} is likely -to do additions, subtractions, and multiplications @dfn{in line}---in -the actual compiled code---it is not likely to do trigonometric -functions this way. - -Instead, operations like trigonometric -functions are compiled by the @code{f771} compiler -(invoked by @code{g77} when compiling Fortran code) into machine -code that, when run, calls on functions in @code{libg2c}, so -@code{libg2c} must be linked with almost every useful program -having any component compiled by GNU Fortran. -(As mentioned above, the @code{g77} command takes -care of all this for you.) - -The @code{f771} program represents most of what is unique to GNU Fortran. -While much of the @code{libg2c} component comes from -the @code{libf2c} component of @code{f2c}, -a free Fortran-to-C converter distributed by Bellcore (AT&T), -plus @code{libU77}, provided by Dave Love, -and the @code{g77} command is just a small front-end to @code{gcc}, -@code{f771} is a combination of two rather -large chunks of code. - -@cindex GNU Back End (GBE) -@cindex GBE -@cindex @code{gcc}, back end -@cindex back end, gcc -@cindex code generator -One chunk is the so-called @dfn{GNU Back End}, or GBE, -which knows how to generate fast code for a wide variety of processors. -The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1}, -@code{cc1plus}, and @code{f771}, plus others. -Often the GBE is referred to as the ``gcc back end'' or -even just ``gcc''---in this manual, the term GBE is used -whenever the distinction is important. - -@cindex GNU Fortran Front End (FFE) -@cindex FFE -@cindex @code{g77}, front end -@cindex front end, @code{g77} -The other chunk of @code{f771} is the -majority of what is unique about GNU Fortran---the code that knows how -to interpret Fortran programs to determine what they are intending to -do, and then communicate that knowledge to the GBE for actual compilation -of those programs. -This chunk is called the @dfn{Fortran Front End} (FFE). -The @code{cc1} and @code{cc1plus} programs have their own front ends, -for the C and C++ languages, respectively. -These fronts ends are responsible for diagnosing -incorrect usage of their respective languages by the -programs the process, and are responsible for most of -the warnings about questionable constructs as well. -(The GBE handles producing some warnings, like those -concerning possible references to undefined variables.) - -Because so much is shared among the compilers for various languages, -much of the behavior and many of the user-selectable options for these -compilers are similar. -For example, diagnostics (error messages and -warnings) are similar in appearance; command-line -options like @samp{-Wall} have generally similar effects; and the quality -of generated code (in terms of speed and size) is roughly similar -(since that work is done by the shared GBE). - -@node G77 and GCC -@chapter Compile Fortran, C, or Other Programs -@cindex compiling programs -@cindex programs, compiling - -@cindex @code{gcc}, command -@cindex commands, @code{gcc} -A GNU Fortran installation includes a modified version of the @code{gcc} -command. - -In a non-Fortran installation, @code{gcc} recognizes C, C++, -and Objective-C source files. - -In a GNU Fortran installation, @code{gcc} also recognizes Fortran source -files and accepts Fortran-specific command-line options, plus some -command-line options that are designed to cater to Fortran users -but apply to other languages as well. - -@xref{G++ and GCC,,Compile C; C++; or Objective-C,gcc,Using and Porting GNU CC}, -for information on the way different languages are handled -by the GNU CC compiler (@code{gcc}). - -@cindex @code{g77}, command -@cindex commands, @code{g77} -Also provided as part of GNU Fortran is the @code{g77} command. -The @code{g77} command is designed to make compiling and linking Fortran -programs somewhat easier than when using the @code{gcc} command for -these tasks. -It does this by analyzing the command line somewhat and changing it -appropriately before submitting it to the @code{gcc} command. - -@cindex -v option -@cindex @code{g77} options, -v -@cindex options, -v -Use the @samp{-v} option with @code{g77} -to see what is going on---the first line of output is the invocation -of the @code{gcc} command. - -@node Invoking G77 -@chapter GNU Fortran Command Options -@cindex GNU Fortran command options -@cindex command options -@cindex options, GNU Fortran command - -The @code{g77} command supports all the options supported by the -@code{gcc} command. -@xref{Invoking GCC,,GNU CC Command Options,gcc,Using and Porting GNU CC}, -for information -on the non-Fortran-specific aspects of the @code{gcc} command (and, -therefore, the @code{g77} command). - -@cindex options, negative forms -@cindex negative forms of options -All @code{gcc} and @code{g77} options -are accepted both by @code{g77} and by @code{gcc} -(as well as any other drivers built at the same time, -such as @code{g++}), -since adding @code{g77} to the @code{gcc} distribution -enables acceptance of @code{g77}-specific options -by all of the relevant drivers. - -In some cases, options have positive and negative forms; -the negative form of @samp{-ffoo} would be @samp{-fno-foo}. -This manual documents only one of these two forms, whichever -one is not the default. - -@menu -* Option Summary:: Brief list of all @code{g77} options, - without explanations. -* Overall Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. -* Shorthand Options:: Options that are shorthand for other options. -* Fortran Dialect Options:: Controlling the variant of Fortran language - compiled. -* Warning Options:: How picky should the compiler be? -* Debugging Options:: Symbol tables, measurements, and debugging dumps. -* Optimize Options:: How much optimization? -* Preprocessor Options:: Controlling header files and macro definitions. - Also, getting dependency information for Make. -* Directory Options:: Where to find header files and libraries. - Where to find the compiler executable files. -* Code Gen Options:: Specifying conventions for function calls, data layout - and register usage. -* Environment Variables:: Env vars that affect GNU Fortran. -@end menu - -@node Option Summary -@section Option Summary - -Here is a summary of all the options specific to GNU Fortran, grouped -by type. Explanations are in the following sections. - -@table @emph -@item Overall Options -@xref{Overall Options,,Options Controlling the Kind of Output}. -@smallexample --fversion -fset-g77-defaults -fno-silent -@end smallexample - -@item Shorthand Options -@xref{Shorthand Options}. -@smallexample --ff66 -fno-f66 -ff77 -fno-f77 -fno-ugly -@end smallexample - -@item Fortran Language Options -@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}. -@smallexample --ffree-form -fno-fixed-form -ff90 --fvxt -fdollar-ok -fno-backslash --fno-ugly-args -fno-ugly-assign -fno-ugly-assumed --fugly-comma -fugly-complex -fugly-init -fugly-logint --fonetrip -ftypeless-boz --fintrin-case-initcap -fintrin-case-upper --fintrin-case-lower -fintrin-case-any --fmatch-case-initcap -fmatch-case-upper --fmatch-case-lower -fmatch-case-any --fsource-case-upper -fsource-case-lower -fsource-case-preserve --fsymbol-case-initcap -fsymbol-case-upper --fsymbol-case-lower -fsymbol-case-any --fcase-strict-upper -fcase-strict-lower --fcase-initcap -fcase-upper -fcase-lower -fcase-preserve --ff2c-intrinsics-delete -ff2c-intrinsics-hide --ff2c-intrinsics-disable -ff2c-intrinsics-enable --fbadu77-intrinsics-delete -fbadu77-intrinsics-hide --fbadu77-intrinsics-disable -fbadu77-intrinsics-enable --ff90-intrinsics-delete -ff90-intrinsics-hide --ff90-intrinsics-disable -ff90-intrinsics-enable --fgnu-intrinsics-delete -fgnu-intrinsics-hide --fgnu-intrinsics-disable -fgnu-intrinsics-enable --fmil-intrinsics-delete -fmil-intrinsics-hide --fmil-intrinsics-disable -fmil-intrinsics-enable --funix-intrinsics-delete -funix-intrinsics-hide --funix-intrinsics-disable -funix-intrinsics-enable --fvxt-intrinsics-delete -fvxt-intrinsics-hide --fvxt-intrinsics-disable -fvxt-intrinsics-enable --ffixed-line-length-@var{n} -ffixed-line-length-none -@end smallexample - -@item Warning Options -@xref{Warning Options,,Options to Request or Suppress Warnings}. -@smallexample --fsyntax-only -pedantic -pedantic-errors -fpedantic --w -Wno-globals -Wimplicit -Wunused -Wuninitialized --Wall -Wsurprising --Werror -W -@end smallexample - -@item Debugging Options -@xref{Debugging Options,,Options for Debugging Your Program or GCC}. -@smallexample --g -@end smallexample - -@item Optimization Options -@xref{Optimize Options,,Options that Control Optimization}. -@smallexample --malign-double --ffloat-store -fforce-mem -fforce-addr -fno-inline --ffast-math -fstrength-reduce -frerun-cse-after-loop --fexpensive-optimizations -fdelayed-branch --fschedule-insns -fschedule-insn2 -fcaller-saves --funroll-loops -funroll-all-loops --fno-move-all-movables -fno-reduce-all-givs --fno-rerun-loop-opt -@end smallexample - -@item Directory Options -@xref{Directory Options,,Options for Directory Search}. -@smallexample --I@var{dir} -I- -@end smallexample - -@item Code Generation Options -@xref{Code Gen Options,,Options for Code Generation Conventions}. -@smallexample --fno-automatic -finit-local-zero -fno-f2c --ff2c-library -fno-underscoring -fno-ident --fpcc-struct-return -freg-struct-return --fshort-double -fno-common -fpack-struct --fzeros -fno-second-underscore --fdebug-kludge -femulate-complex --falias-check -fargument-alias --fargument-noalias -fno-argument-noalias-global --fno-globals -fflatten-arrays --fbounds-check -ffortran-bounds-check -@end smallexample -@end table - -@menu -* Overall Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. -* Shorthand Options:: Options that are shorthand for other options. -* Fortran Dialect Options:: Controlling the variant of Fortran language - compiled. -* Warning Options:: How picky should the compiler be? -* Debugging Options:: Symbol tables, measurements, and debugging dumps. -* Optimize Options:: How much optimization? -* Preprocessor Options:: Controlling header files and macro definitions. - Also, getting dependency information for Make. -* Directory Options:: Where to find header files and libraries. - Where to find the compiler executable files. -* Code Gen Options:: Specifying conventions for function calls, data layout - and register usage. -@end menu - -@node Overall Options -@section Options Controlling the Kind of Output -@cindex overall options -@cindex options, overall - -Compilation can involve as many as four stages: preprocessing, code -generation (often what is really meant by the term ``compilation''), -assembly, and linking, always in that order. The first three -stages apply to an individual source file, and end by producing an -object file; linking combines all the object files (those newly -compiled, and those specified as input) into an executable file. - -@cindex file name suffix -@cindex suffixes, file name -@cindex file name extension -@cindex extensions, file name -@cindex file type -@cindex types, file -For any given input file, the file name suffix determines what kind of -program is contained in the file---that is, the language in which the -program is written is generally indicated by the suffix. -Suffixes specific to GNU Fortran are listed below. -@xref{Overall Options,,gcc,Using and Porting GNU CC}, for -information on suffixes recognized by GNU CC. - -@table @code -@cindex .f filename suffix -@cindex .for filename suffix -@cindex .FOR filename suffix -@item @var{file}.f -@item @var{file}.for -@item @var{file}.FOR -Fortran source code that should not be preprocessed. - -Such source code cannot contain any preprocessor directives, such -as @code{#include}, @code{#define}, @code{#if}, and so on. - -You can force @samp{.f} files to be preprocessed by @code{cpp} by using -@samp{-x f77-cpp-input}. -@xref{LEX}. - -@cindex preprocessor -@cindex C preprocessor -@cindex cpp preprocessor -@cindex Fortran preprocessor -@cindex cpp program -@cindex programs, cpp -@cindex .F filename suffix -@cindex .fpp filename suffix -@cindex .FPP filename suffix -@item @var{file}.F -@item @var{file}.fpp -@item @var{file}.FPP -Fortran source code that must be preprocessed (by the C preprocessor -@code{cpp}, which is part of GNU CC). - -Note that preprocessing is not extended to the contents of -files included by the @code{INCLUDE} directive---the @code{#include} -preprocessor directive must be used instead. - -@cindex Ratfor preprocessor -@cindex programs, @code{ratfor} -@cindex @samp{.r} filename suffix -@cindex @code{ratfor} -@item @var{file}.r -Ratfor source code, which must be preprocessed by the @code{ratfor} -command, which is available separately (as it is not yet part of the GNU -Fortran distribution). -One version in Fortran, adapted for use with @code{g77}, is at -@uref{ftp://members.aol.com/n8tm/rat7.uue} (of uncertain copyright -status). Another, public domain version in C is at -@uref{http://sepwww.stanford.edu/sep/prof/ratfor.shar.2}. -@end table - -UNIX users typically use the @file{@var{file}.f} and @file{@var{file}.F} -nomenclature. -Users of other operating systems, especially those that cannot -distinguish upper-case -letters from lower-case letters in their file names, typically use -the @file{@var{file}.for} and @file{@var{file}.fpp} nomenclature. - -@cindex #define -@cindex #include -@cindex #if -Use of the preprocessor @code{cpp} allows use of C-like -constructs such as @code{#define} and @code{#include}, but can -lead to unexpected, even mistaken, results due to Fortran's source file -format. -It is recommended that use of the C preprocessor -be limited to @code{#include} and, in -conjunction with @code{#define}, only @code{#if} and related directives, -thus avoiding in-line macro expansion entirely. -This recommendation applies especially -when using the traditional fixed source form. -With free source form, -fewer unexpected transformations are likely to happen, but use of -constructs such as Hollerith and character constants can nevertheless -present problems, especially when these are continued across multiple -source lines. -These problems result, primarily, from differences between the way -such constants are interpreted by the C preprocessor and by a Fortran -compiler. - -Another example of a problem that results from using the C preprocessor -is that a Fortran comment line that happens to contain any -characters ``interesting'' to the C preprocessor, -such as a backslash at the end of the line, -is not recognized by the preprocessor as a comment line, -so instead of being passed through ``raw'', -the line is edited according to the rules for the preprocessor. -For example, the backslash at the end of the line is removed, -along with the subsequent newline, resulting in the next -line being effectively commented out---unfortunate if that -line is a non-comment line of important code! - -@emph{Note:} The @samp{-traditional} and @samp{-undef} flags are supplied -to @code{cpp} by default, to help avoid unpleasant surprises. -@xref{Preprocessor Options,,Options Controlling the Preprocessor, -gcc,Using and Porting GNU CC}. -This means that ANSI C preprocessor features (such as the @samp{#} -operator) aren't available, and only variables in the C reserved -namespace (generally, names with a leading underscore) are liable to -substitution by C predefines. -Thus, if you want to do system-specific -tests, use, for example, @samp{#ifdef __linux__} rather than @samp{#ifdef linux}. -Use the @samp{-v} option to see exactly how the preprocessor is invoked. - -@cindex /* -Unfortunately, the @samp{-traditional} flag will not avoid an error from -anything that @code{cpp} sees as an unterminated C comment, such as: -@smallexample -C Some Fortran compilers accept /* as starting -C an inline comment. -@end smallexample -@xref{Trailing Comment}. - -The following options that affect overall processing are recognized -by the @code{g77} and @code{gcc} commands in a GNU Fortran installation: - -@table @code -@cindex -fversion option -@cindex options, -fversion -@cindex printing version information -@cindex version information, printing -@cindex consistency checks -@cindex internal consistency checks -@cindex checks, of internal consistency -@item -fversion -Ensure that the @code{g77}-specific version of the compiler phase is reported, -if run, -and, starting in @code{egcs} version 1.1, -that internal consistency checks in the @file{f771} program are run. - -This option is supplied automatically when @samp{-v} or @samp{--verbose} -is specified as a command-line option for @code{g77} or @code{gcc} -and when the resulting commands compile Fortran source files. - -@cindex -fset-g77-defaults option -@cindex options, -fset-g77-defaults -@item -fset-g77-defaults -@emph{Version info:} -This option is obsolete in @code{egcs} -as of version 1.1. -The effect is instead achieved -by the @code{lang_init_options} routine -in @file{egcs/gcc/f/com.c}. - -@cindex consistency checks -@cindex internal consistency checks -@cindex checks, of internal consistency -Set up whatever @code{gcc} options are to apply to Fortran -compilations, and avoid running internal consistency checks -that might take some time. - -This option is supplied automatically when compiling Fortran code -via the @code{g77} or @code{gcc} command. -The description of this option is provided so that users seeing -it in the output of, say, @samp{g77 -v} understand why it is -there. - -@cindex modifying g77 -@cindex code, modifying -Also, developers who run @code{f771} directly might want to specify it -by hand to get the same defaults as they would running @code{f771} -via @code{g77} or @code{gcc}. -However, such developers should, after linking a new @code{f771} -executable, invoke it without this option once, -e.g. via @kbd{./f771 -quiet < /dev/null}, -to ensure that they have not introduced any -internal inconsistencies (such as in the table of -intrinsics) before proceeding---@code{g77} will crash -with a diagnostic if it detects an inconsistency. - -@cindex -fno-silent option -@cindex options, -fno-silent -@cindex f2c compatibility -@cindex compatibility, f2c -@cindex status, compilation -@cindex compilation, status -@cindex reporting compilation status -@cindex printing compilation status -@item -fno-silent -Print (to @code{stderr}) the names of the program units as -they are compiled, in a form similar to that used by popular -UNIX @code{f77} implementations and @code{f2c}. -@end table - -@xref{Overall Options,,Options Controlling the Kind of Output, -gcc,Using and Porting GNU CC}, for information -on more options that control the overall operation of the @code{gcc} command -(and, by extension, the @code{g77} command). - -@node Shorthand Options -@section Shorthand Options -@cindex shorthand options -@cindex options, shorthand -@cindex macro options -@cindex options, macro - -The following options serve as ``shorthand'' -for other options accepted by the compiler: - -@table @code -@cindex -fugly option -@cindex options, -fugly -@item -fugly -@cindex ugly features -@cindex features, ugly -@emph{Note:} This option is no longer supported. -The information, below, is provided to aid -in the conversion of old scripts. - -Specify that certain ``ugly'' constructs are to be quietly accepted. -Same as: - -@smallexample --fugly-args -fugly-assign -fugly-assumed --fugly-comma -fugly-complex -fugly-init --fugly-logint -@end smallexample - -These constructs are considered inappropriate to use in new -or well-maintained portable Fortran code, but widely used -in old code. -@xref{Distensions}, for more information. - -@cindex -fno-ugly option -@cindex options, -fno-ugly -@item -fno-ugly -@cindex ugly features -@cindex features, ugly -Specify that all ``ugly'' constructs are to be noisily rejected. -Same as: - -@smallexample --fno-ugly-args -fno-ugly-assign -fno-ugly-assumed --fno-ugly-comma -fno-ugly-complex -fno-ugly-init --fno-ugly-logint -@end smallexample - -@xref{Distensions}, for more information. - -@cindex -ff66 option -@cindex options, -ff66 -@item -ff66 -@cindex FORTRAN 66 -@cindex compatibility, FORTRAN 66 -Specify that the program is written in idiomatic FORTRAN 66. -Same as @samp{-fonetrip -fugly-assumed}. - -The @samp{-fno-f66} option is the inverse of @samp{-ff66}. -As such, it is the same as @samp{-fno-onetrip -fno-ugly-assumed}. - -The meaning of this option is likely to be refined as future -versions of @code{g77} provide more compatibility with other -existing and obsolete Fortran implementations. - -@cindex -ff77 option -@cindex options, -ff77 -@item -ff77 -@cindex UNIX f77 -@cindex f2c compatibility -@cindex compatibility, f2c -@cindex f77 compatibility -@cindex compatibility, f77 -Specify that the program is written in idiomatic UNIX FORTRAN 77 -and/or the dialect accepted by the @code{f2c} product. -Same as @samp{-fbackslash -fno-typeless-boz}. - -The meaning of this option is likely to be refined as future -versions of @code{g77} provide more compatibility with other -existing and obsolete Fortran implementations. - -@cindex -fno-f77 option -@cindex options, -fno-f77 -@item -fno-f77 -@cindex UNIX f77 -The @samp{-fno-f77} option is @emph{not} the inverse -of @samp{-ff77}. -It specifies that the program is not written in idiomatic UNIX -FORTRAN 77 or @code{f2c}, but in a more widely portable dialect. -@samp{-fno-f77} is the same as @samp{-fno-backslash}. - -The meaning of this option is likely to be refined as future -versions of @code{g77} provide more compatibility with other -existing and obsolete Fortran implementations. -@end table - -@node Fortran Dialect Options -@section Options Controlling Fortran Dialect -@cindex dialect options -@cindex language, dialect options -@cindex options, dialect - -The following options control the dialect of Fortran -that the compiler accepts: - -@table @code -@cindex -ffree-form option -@cindex options, -ffree-form -@cindex -fno-fixed-form option -@cindex options, -fno-fixed-form -@cindex source file format -@cindex free form -@cindex fixed form -@cindex Fortran 90, features -@item -ffree-form -@item -fno-fixed-form -Specify that the source file is written in free form -(introduced in Fortran 90) instead of the more-traditional fixed form. - -@cindex -ff90 option -@cindex options, -ff90 -@cindex Fortran 90, features -@item -ff90 -Allow certain Fortran-90 constructs. - -This option controls whether certain -Fortran 90 constructs are recognized. -(Other Fortran 90 constructs -might or might not be recognized depending on other options such as -@samp{-fvxt}, @samp{-ff90-intrinsics-enable}, and the -current level of support for Fortran 90.) - -@xref{Fortran 90}, for more information. - -@cindex -fvxt option -@cindex options, -fvxt -@item -fvxt -@cindex Fortran 90, features -@cindex VXT extensions -Specify the treatment of certain constructs that have different -meanings depending on whether the code is written in -GNU Fortran (based on FORTRAN 77 and akin to Fortran 90) -or VXT Fortran (more like VAX FORTRAN). - -The default is @samp{-fno-vxt}. -@samp{-fvxt} specifies that the VXT Fortran interpretations -for those constructs are to be chosen. - -@xref{VXT Fortran}, for more information. - -@cindex -fdollar-ok option -@cindex options, -fdollar-ok -@item -fdollar-ok -@cindex dollar sign -@cindex symbol names -@cindex character set -Allow @samp{$} as a valid character in a symbol name. - -@cindex -fno-backslash option -@cindex options, -fno-backslash -@item -fno-backslash -@cindex backslash -@cindex character constants -@cindex Hollerith constants -Specify that @samp{\} is not to be specially interpreted in character -and Hollerith constants a la C and many UNIX Fortran compilers. - -For example, with @samp{-fbackslash} in effect, @samp{A\nB} specifies -three characters, with the second one being newline. -With @samp{-fno-backslash}, it specifies four characters, -@samp{A}, @samp{\}, @samp{n}, and @samp{B}. - -Note that @code{g77} implements a fairly general form of backslash -processing that is incompatible with the narrower forms supported -by some other compilers. -For example, @samp{'A\003B'} is a three-character string in @code{g77}, -whereas other compilers that support backslash might not support -the three-octal-digit form, and thus treat that string as longer -than three characters. - -@xref{Backslash in Constants}, for -information on why @samp{-fbackslash} is the default -instead of @samp{-fno-backslash}. - -@cindex -fno-ugly-args option -@cindex options, -fno-ugly-args -@item -fno-ugly-args -Disallow passing Hollerith and typeless constants as actual -arguments (for example, @samp{CALL FOO(4HABCD)}). - -@xref{Ugly Implicit Argument Conversion}, for more information. - -@cindex -fugly-assign option -@cindex options, -fugly-assign -@item -fugly-assign -Use the same storage for a given variable regardless of -whether it is used to hold an assigned-statement label -(as in @samp{ASSIGN 10 TO I}) or used to hold numeric data -(as in @samp{I = 3}). - -@xref{Ugly Assigned Labels}, for more information. - -@cindex -fugly-assumed option -@cindex options, -fugly-assumed -@item -fugly-assumed -Assume any dummy array with a final dimension specified as @samp{1} -is really an assumed-size array, as if @samp{*} had been specified -for the final dimension instead of @samp{1}. - -For example, @samp{DIMENSION X(1)} is treated as if it -had read @samp{DIMENSION X(*)}. - -@xref{Ugly Assumed-Size Arrays}, for more information. - -@cindex -fugly-comma option -@cindex options, -fugly-comma -@item -fugly-comma -In an external-procedure invocation, -treat a trailing comma in the argument list -as specification of a trailing null argument, -and treat an empty argument list -as specification of a single null argument. - -For example, @samp{CALL FOO(,)} is treated as -@samp{CALL FOO(%VAL(0), %VAL(0))}. -That is, @emph{two} null arguments are specified -by the procedure call when @samp{-fugly-comma} is in force. -And @samp{F = FUNC()} is treated as @samp{F = FUNC(%VAL(0))}. - -The default behavior, @samp{-fno-ugly-comma}, is to ignore -a single trailing comma in an argument list. -So, by default, @samp{CALL FOO(X,)} is treated -exactly the same as @samp{CALL FOO(X)}. - -@xref{Ugly Null Arguments}, for more information. - -@cindex -fugly-complex option -@cindex options, -fugly-complex -@item -fugly-complex -Do not complain about @samp{REAL(@var{expr})} or -@samp{AIMAG(@var{expr})} when @var{expr} is a @code{COMPLEX} -type other than @code{COMPLEX(KIND=1)}---usually -this is used to permit @code{COMPLEX(KIND=2)} -(@code{DOUBLE COMPLEX}) operands. - -The @samp{-ff90} option controls the interpretation -of this construct. - -@xref{Ugly Complex Part Extraction}, for more information. - -@cindex -fno-ugly-init option -@cindex options, -fno-ugly-init -@item -fno-ugly-init -Disallow use of Hollerith and typeless constants as initial -values (in @code{PARAMETER} and @code{DATA} statements), and -use of character constants to -initialize numeric types and vice versa. - -For example, @samp{DATA I/'F'/, CHRVAR/65/, J/4HABCD/} is disallowed by -@samp{-fno-ugly-init}. - -@xref{Ugly Conversion of Initializers}, for more information. - -@cindex -fugly-logint option -@cindex options, -fugly-logint -@item -fugly-logint -Treat @code{INTEGER} and @code{LOGICAL} variables and -expressions as potential stand-ins for each other. - -For example, automatic conversion between @code{INTEGER} and -@code{LOGICAL} is enabled, for many contexts, via this option. - -@xref{Ugly Integer Conversions}, for more information. - -@cindex -fonetrip option -@cindex options, -fonetrip -@item -fonetrip -@cindex FORTRAN 66 -@cindex @code{DO} loops, one-trip -@cindex one-trip @code{DO} loops -@cindex @code{DO} loops, zero-trip -@cindex zero-trip @code{DO} loops -@cindex compatibility, FORTRAN 66 -Executable iterative @code{DO} loops are to be executed at -least once each time they are reached. - -ANSI FORTRAN 77 and more recent versions of the Fortran standard -specify that the body of an iterative @code{DO} loop is not executed -if the number of iterations calculated from the parameters of the -loop is less than 1. -(For example, @samp{DO 10 I = 1, 0}.) -Such a loop is called a @dfn{zero-trip loop}. - -Prior to ANSI FORTRAN 77, many compilers implemented @code{DO} loops -such that the body of a loop would be executed at least once, even -if the iteration count was zero. -Fortran code written assuming this behavior is said to require -@dfn{one-trip loops}. -For example, some code written to the FORTRAN 66 standard -expects this behavior from its @code{DO} loops, although that -standard did not specify this behavior. - -The @samp{-fonetrip} option specifies that the source file(s) being -compiled require one-trip loops. - -This option affects only those loops specified by the (iterative) @code{DO} -statement and by implied-@code{DO} lists in I/O statements. -Loops specified by implied-@code{DO} lists in @code{DATA} and -specification (non-executable) statements are not affected. - -@cindex -ftypeless-boz option -@cindex options, -ftypeless-boz -@cindex prefix-radix constants -@cindex constants, prefix-radix -@cindex constants, types -@cindex types, constants -@item -ftypeless-boz -Specifies that prefix-radix non-decimal constants, such as -@samp{Z'ABCD'}, are typeless instead of @code{INTEGER(KIND=1)}. - -You can test for yourself whether a particular compiler treats -the prefix form as @code{INTEGER(KIND=1)} or typeless by running the -following program: - -@smallexample -EQUIVALENCE (I, R) -R = Z'ABCD1234' -J = Z'ABCD1234' -IF (J .EQ. I) PRINT *, 'Prefix form is TYPELESS' -IF (J .NE. I) PRINT *, 'Prefix form is INTEGER' -END -@end smallexample - -Reports indicate that many compilers process this form as -@code{INTEGER(KIND=1)}, though a few as typeless, and at least one -based on a command-line option specifying some kind of -compatibility. - -@cindex -fintrin-case-initcap option -@cindex options, -fintrin-case-initcap -@item -fintrin-case-initcap -@cindex -fintrin-case-upper option -@cindex options, -fintrin-case-upper -@item -fintrin-case-upper -@cindex -fintrin-case-lower option -@cindex options, -fintrin-case-lower -@item -fintrin-case-lower -@cindex -fintrin-case-any option -@cindex options, -fintrin-case-any -@item -fintrin-case-any -Specify expected case for intrinsic names. -@samp{-fintrin-case-lower} is the default. - -@cindex -fmatch-case-initcap option -@cindex options, -fmatch-case-initcap -@item -fmatch-case-initcap -@cindex -fmatch-case-upper option -@cindex options, -fmatch-case-upper -@item -fmatch-case-upper -@cindex -fmatch-case-lower option -@cindex options, -fmatch-case-lower -@item -fmatch-case-lower -@cindex -fmatch-case-any option -@cindex options, -fmatch-case-any -@item -fmatch-case-any -Specify expected case for keywords. -@samp{-fmatch-case-lower} is the default. - -@cindex -fsource-case-upper option -@cindex options, -fsource-case-upper -@item -fsource-case-upper -@cindex -fsource-case-lower option -@cindex options, -fsource-case-lower -@item -fsource-case-lower -@cindex -fsource-case-preserve option -@cindex options, -fsource-case-preserve -@item -fsource-case-preserve -Specify whether source text other than character and Hollerith constants -is to be translated to uppercase, to lowercase, or preserved as is. -@samp{-fsource-case-lower} is the default. - -@cindex -fsymbol-case-initcap option -@cindex options, -fsymbol-case-initcap -@item -fsymbol-case-initcap -@cindex -fsymbol-case-upper option -@cindex options, -fsymbol-case-upper -@item -fsymbol-case-upper -@cindex -fsymbol-case-lower option -@cindex options, -fsymbol-case-lower -@item -fsymbol-case-lower -@cindex -fsymbol-case-any option -@cindex options, -fsymbol-case-any -@item -fsymbol-case-any -Specify valid cases for user-defined symbol names. -@samp{-fsymbol-case-any} is the default. - -@cindex -fcase-strict-upper option -@cindex options, -fcase-strict-upper -@item -fcase-strict-upper -Same as @samp{-fintrin-case-upper -fmatch-case-upper -fsource-case-preserve --fsymbol-case-upper}. -(Requires all pertinent source to be in uppercase.) - -@cindex -fcase-strict-lower option -@cindex options, -fcase-strict-lower -@item -fcase-strict-lower -Same as @samp{-fintrin-case-lower -fmatch-case-lower -fsource-case-preserve --fsymbol-case-lower}. -(Requires all pertinent source to be in lowercase.) - -@cindex -fcase-initcap option -@cindex options, -fcase-initcap -@item -fcase-initcap -Same as @samp{-fintrin-case-initcap -fmatch-case-initcap -fsource-case-preserve --fsymbol-case-initcap}. -(Requires all pertinent source to be in initial capitals, -as in @samp{Print *,SqRt(Value)}.) - -@cindex -fcase-upper option -@cindex options, -fcase-upper -@item -fcase-upper -Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-upper --fsymbol-case-any}. -(Maps all pertinent source to uppercase.) - -@cindex -fcase-lower option -@cindex options, -fcase-lower -@item -fcase-lower -Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-lower --fsymbol-case-any}. -(Maps all pertinent source to lowercase.) - -@cindex -fcase-preserve option -@cindex options, -fcase-preserve -@item -fcase-preserve -Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-preserve --fsymbol-case-any}. -(Preserves all case in user-defined symbols, -while allowing any-case matching of intrinsics and keywords. -For example, @samp{call Foo(i,I)} would pass two @emph{different} -variables named @samp{i} and @samp{I} to a procedure named @samp{Foo}.) - -@cindex -fbadu77-intrinsics-delete option -@cindex options, -fbadu77-intrinsics-delete -@item -fbadu77-intrinsics-delete -@cindex -fbadu77-intrinsics-hide option -@cindex options, -fbadu77-intrinsics-hide -@item -fbadu77-intrinsics-hide -@cindex -fbadu77-intrinsics-disable option -@cindex options, -fbadu77-intrinsics-disable -@item -fbadu77-intrinsics-disable -@cindex -fbadu77-intrinsics-enable option -@cindex options, -fbadu77-intrinsics-enable -@item -fbadu77-intrinsics-enable -@cindex @code{badu77} intrinsics -@cindex intrinsics, @code{badu77} -Specify status of UNIX intrinsics having inappropriate forms. -@samp{-fbadu77-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -ff2c-intrinsics-delete option -@cindex options, -ff2c-intrinsics-delete -@item -ff2c-intrinsics-delete -@cindex -ff2c-intrinsics-hide option -@cindex options, -ff2c-intrinsics-hide -@item -ff2c-intrinsics-hide -@cindex -ff2c-intrinsics-disable option -@cindex options, -ff2c-intrinsics-disable -@item -ff2c-intrinsics-disable -@cindex -ff2c-intrinsics-enable option -@cindex options, -ff2c-intrinsics-enable -@item -ff2c-intrinsics-enable -@cindex @code{f2c} intrinsics -@cindex intrinsics, @code{f2c} -Specify status of f2c-specific intrinsics. -@samp{-ff2c-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -ff90-intrinsics-delete option -@cindex options, -ff90-intrinsics-delete -@item -ff90-intrinsics-delete -@cindex -ff90-intrinsics-hide option -@cindex options, -ff90-intrinsics-hide -@item -ff90-intrinsics-hide -@cindex -ff90-intrinsics-disable option -@cindex options, -ff90-intrinsics-disable -@item -ff90-intrinsics-disable -@cindex -ff90-intrinsics-enable option -@cindex options, -ff90-intrinsics-enable -@item -ff90-intrinsics-enable -@cindex Fortran 90, intrinsics -@cindex intrinsics, Fortran 90 -Specify status of F90-specific intrinsics. -@samp{-ff90-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -fgnu-intrinsics-delete option -@cindex options, -fgnu-intrinsics-delete -@item -fgnu-intrinsics-delete -@cindex -fgnu-intrinsics-hide option -@cindex options, -fgnu-intrinsics-hide -@item -fgnu-intrinsics-hide -@cindex -fgnu-intrinsics-disable option -@cindex options, -fgnu-intrinsics-disable -@item -fgnu-intrinsics-disable -@cindex -fgnu-intrinsics-enable option -@cindex options, -fgnu-intrinsics-enable -@item -fgnu-intrinsics-enable -@cindex Digital Fortran features -@cindex @code{COMPLEX} intrinsics -@cindex intrinsics, @code{COMPLEX} -Specify status of Digital's COMPLEX-related intrinsics. -@samp{-fgnu-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -fmil-intrinsics-delete option -@cindex options, -fmil-intrinsics-delete -@item -fmil-intrinsics-delete -@cindex -fmil-intrinsics-hide option -@cindex options, -fmil-intrinsics-hide -@item -fmil-intrinsics-hide -@cindex -fmil-intrinsics-disable option -@cindex options, -fmil-intrinsics-disable -@item -fmil-intrinsics-disable -@cindex -fmil-intrinsics-enable option -@cindex options, -fmil-intrinsics-enable -@item -fmil-intrinsics-enable -@cindex MIL-STD 1753 -@cindex intrinsics, MIL-STD 1753 -Specify status of MIL-STD-1753-specific intrinsics. -@samp{-fmil-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -funix-intrinsics-delete option -@cindex options, -funix-intrinsics-delete -@item -funix-intrinsics-delete -@cindex -funix-intrinsics-hide option -@cindex options, -funix-intrinsics-hide -@item -funix-intrinsics-hide -@cindex -funix-intrinsics-disable option -@cindex options, -funix-intrinsics-disable -@item -funix-intrinsics-disable -@cindex -funix-intrinsics-enable option -@cindex options, -funix-intrinsics-enable -@item -funix-intrinsics-enable -@cindex UNIX intrinsics -@cindex intrinsics, UNIX -Specify status of UNIX intrinsics. -@samp{-funix-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -fvxt-intrinsics-delete option -@cindex options, -fvxt-intrinsics-delete -@item -fvxt-intrinsics-delete -@cindex -fvxt-intrinsics-hide option -@cindex options, -fvxt-intrinsics-hide -@item -fvxt-intrinsics-hide -@cindex -fvxt-intrinsics-disable option -@cindex options, -fvxt-intrinsics-disable -@item -fvxt-intrinsics-disable -@cindex -fvxt-intrinsics-enable option -@cindex options, -fvxt-intrinsics-enable -@item -fvxt-intrinsics-enable -@cindex VXT intrinsics -@cindex intrinsics, VXT -Specify status of VXT intrinsics. -@samp{-fvxt-intrinsics-enable} is the default. -@xref{Intrinsic Groups}. - -@cindex -ffixed-line-length-@var{n} option -@cindex options, -ffixed-line-length-@var{n} -@item -ffixed-line-length-@var{n} -@cindex source file format -@cindex lines, length -@cindex length of source lines -@cindex fixed form -@cindex limits, lengths of source lines -Set column after which characters are ignored in typical fixed-form -lines in the source file, and through which spaces are assumed (as -if padded to that length) after the ends of short fixed-form lines. - -@cindex card image -@cindex extended-source option -Popular values for @var{n} include 72 (the -standard and the default), 80 (card image), and 132 (corresponds -to ``extended-source'' options in some popular compilers). -@var{n} may be @samp{none}, meaning that the entire line is meaningful -and that continued character constants never have implicit spaces appended -to them to fill out the line. -@samp{-ffixed-line-length-0} means the same thing as -@samp{-ffixed-line-length-none}. - -@xref{Source Form}, for more information. -@end table - -@node Warning Options -@section Options to Request or Suppress Warnings -@cindex options, warnings -@cindex warnings, suppressing -@cindex messages, warning -@cindex suppressing warnings - -Warnings are diagnostic messages that report constructions which -are not inherently erroneous but which are risky or suggest there -might have been an error. - -You can request many specific warnings with options beginning @samp{-W}, -for example @samp{-Wimplicit} to request warnings on implicit -declarations. Each of these specific warning options also has a -negative form beginning @samp{-Wno-} to turn off warnings; -for example, @samp{-Wno-implicit}. This manual lists only one of the -two forms, whichever is not the default. - -These options control the amount and kinds of warnings produced by GNU -Fortran: - -@table @code -@cindex syntax checking -@cindex -fsyntax-only option -@cindex options, -fsyntax-only -@item -fsyntax-only -Check the code for syntax errors, but don't do anything beyond that. - -@cindex -pedantic option -@cindex options, -pedantic -@item -pedantic -Issue warnings for uses of extensions to ANSI FORTRAN 77. -@samp{-pedantic} also applies to C-language constructs where they -occur in GNU Fortran source files, such as use of @samp{\e} in a -character constant within a directive like @samp{#include}. - -Valid ANSI FORTRAN 77 programs should compile properly with or without -this option. -However, without this option, certain GNU extensions and traditional -Fortran features are supported as well. -With this option, many of them are rejected. - -Some users try to use @samp{-pedantic} to check programs for strict ANSI -conformance. -They soon find that it does not do quite what they want---it finds some -non-ANSI practices, but not all. -However, improvements to @code{g77} in this area are welcome. - -@cindex -pedantic-errors option -@cindex options, -pedantic-errors -@item -pedantic-errors -Like @samp{-pedantic}, except that errors are produced rather than -warnings. - -@cindex -fpedantic option -@cindex options, -fpedantic -@item -fpedantic -Like @samp{-pedantic}, but applies only to Fortran constructs. - -@cindex -w option -@cindex options, -w -@item -w -Inhibit all warning messages. - -@cindex -Wno-globals option -@cindex options, -Wno-globals -@item -Wno-globals -@cindex global names, warning -@cindex warnings, global names -Inhibit warnings about use of a name as both a global name -(a subroutine, function, or block data program unit, or a -common block) and implicitly as the name of an intrinsic -in a source file. - -Also inhibit warnings about inconsistent invocations and/or -definitions of global procedures (function and subroutines). -Such inconsistencies include different numbers of arguments -and different types of arguments. - -@cindex -Wimplicit option -@cindex options, -Wimplicit -@item -Wimplicit -@cindex implicit declaration, warning -@cindex warnings, implicit declaration -@cindex -u option -@cindex /WARNINGS=DECLARATIONS switch -@cindex IMPLICIT NONE, similar effect -@cindex effecting IMPLICIT NONE -Warn whenever a variable, array, or function is implicitly -declared. -Has an effect similar to using the @code{IMPLICIT NONE} statement -in every program unit. -(Some Fortran compilers provide this feature by an option -named @samp{-u} or @samp{/WARNINGS=DECLARATIONS}.) - -@cindex -Wunused option -@cindex options, -Wunused -@item -Wunused -@cindex unused variables -@cindex variables, unused -Warn whenever a variable is unused aside from its declaration. - -@cindex -Wuninitialized option -@cindex options, -Wuninitialized -@item -Wuninitialized -@cindex uninitialized variables -@cindex variables, uninitialized -Warn whenever an automatic variable is used without first being initialized. - -These warnings are possible only in optimizing compilation, -because they require data-flow information that is computed only -when optimizing. If you don't specify @samp{-O}, you simply won't -get these warnings. - -These warnings occur only for variables that are candidates for -register allocation. Therefore, they do not occur for a variable -@c that is declared @code{VOLATILE}, or -whose address is taken, or whose size -is other than 1, 2, 4 or 8 bytes. Also, they do not occur for -arrays, even when they are in registers. - -Note that there might be no warning about a variable that is used only -to compute a value that itself is never used, because such -computations may be deleted by data-flow analysis before the warnings -are printed. - -These warnings are made optional because GNU Fortran is not smart -enough to see all the reasons why the code might be correct -despite appearing to have an error. Here is one example of how -this can happen: - -@example -SUBROUTINE DISPAT(J) -IF (J.EQ.1) I=1 -IF (J.EQ.2) I=4 -IF (J.EQ.3) I=5 -CALL FOO(I) -END -@end example - -@noindent -If the value of @code{J} is always 1, 2 or 3, then @code{I} is -always initialized, but GNU Fortran doesn't know this. Here is -another common case: - -@example -SUBROUTINE MAYBE(FLAG) -LOGICAL FLAG -IF (FLAG) VALUE = 9.4 -@dots{} -IF (FLAG) PRINT *, VALUE -END -@end example - -@noindent -This has no bug because @code{VALUE} is used only if it is set. - -@cindex -Wall option -@cindex options, -Wall -@item -Wall -@cindex all warnings -@cindex warnings, all -The @samp{-Wunused} and @samp{-Wuninitialized} options combined. -These are all the -options which pertain to usage that we recommend avoiding and that we -believe is easy to avoid. -(As more warnings are added to @code{g77}, some might -be added to the list enabled by @samp{-Wall}.) -@end table - -The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall} -because they warn about constructions that we consider reasonable to -use, on occasion, in clean programs. - -@table @code -@c @item -W -@c Print extra warning messages for these events: -@c -@c @itemize @bullet -@c @item -@c If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused -@c arguments. -@c -@c @end itemize -@c -@cindex -Wsurprising option -@cindex options, -Wsurprising -@item -Wsurprising -Warn about ``suspicious'' constructs that are interpreted -by the compiler in a way that might well be surprising to -someone reading the code. -These differences can result in subtle, compiler-dependent -(even machine-dependent) behavioral differences. -The constructs warned about include: - -@itemize @bullet -@item -Expressions having two arithmetic operators in a row, such -as @samp{X*-Y}. -Such a construct is nonstandard, and can produce -unexpected results in more complicated situations such -as @samp{X**-Y*Z}. -@code{g77}, along with many other compilers, interprets -this example differently than many programmers, and a few -other compilers. -Specifically, @code{g77} interprets @samp{X**-Y*Z} as -@samp{(X**(-Y))*Z}, while others might think it should -be interpreted as @samp{X**(-(Y*Z))}. - -A revealing example is the constant expression @samp{2**-2*1.}, -which @code{g77} evaluates to .25, while others might evaluate -it to 0., the difference resulting from the way precedence affects -type promotion. - -(The @samp{-fpedantic} option also warns about expressions -having two arithmetic operators in a row.) - -@item -Expressions with a unary minus followed by an operand and then -a binary operator other than plus or minus. -For example, @samp{-2**2} produces a warning, because -the precedence is @samp{-(2**2)}, yielding -4, not -@samp{(-2)**2}, which yields 4, and which might represent -what a programmer expects. - -An example of an expression producing different results -in a surprising way is @samp{-I*S}, where @var{I} holds -the value @samp{-2147483648} and @var{S} holds @samp{0.5}. -On many systems, negating @var{I} results in the same -value, not a positive number, because it is already the -lower bound of what an @code{INTEGER(KIND=1)} variable can hold. -So, the expression evaluates to a positive number, while -the ``expected'' interpretation, @samp{(-I)*S}, would -evaluate to a negative number. - -Even cases such as @samp{-I*J} produce warnings, -even though, in most configurations and situations, -there is no computational difference between the -results of the two interpretations---the purpose -of this warning is to warn about differing interpretations -and encourage a better style of coding, not to identify -only those places where bugs might exist in the user's -code. - -@cindex DO statement -@cindex statements, DO -@item -@code{DO} loops with @code{DO} variables that are not -of integral type---that is, using @code{REAL} -variables as loop control variables. -Although such loops can be written to work in the -``obvious'' way, the way @code{g77} is required by the -Fortran standard to interpret such code is likely to -be quite different from the way many programmers expect. -(This is true of all @code{DO} loops, but the differences -are pronounced for non-integral loop control variables.) - -@xref{Loops}, for more information. -@end itemize - -@cindex -Werror option -@cindex options, -Werror -@item -Werror -Make all warnings into errors. - -@cindex -W option -@cindex options, -W -@item -W -@cindex extra warnings -@cindex warnings, extra -Turns on ``extra warnings'' and, if optimization is specified -via @samp{-O}, the @samp{-Wuninitialized} option. -(This might change in future versions of @code{g77}.) - -``Extra warnings'' are issued for: - -@itemize @bullet -@item -@cindex unused parameters -@cindex parameters, unused -@cindex unused arguments -@cindex arguments, unused -@cindex unused dummies -@cindex dummies, unused -Unused parameters to a procedure (when @samp{-Wunused} also is -specified). - -@item -@cindex overflow -Overflows involving floating-point constants (not available -for certain configurations). -@end itemize -@end table - -@xref{Warning Options,,Options to Request or Suppress Warnings, -gcc,Using and Porting GNU CC}, for information on more options offered -by the GBE shared by @code{g77}, @code{gcc}, and other GNU compilers. - -Some of these have no effect when compiling programs written in Fortran: - -@table @code -@cindex -Wcomment option -@cindex options, -Wcomment -@item -Wcomment -@cindex -Wformat option -@cindex options, -Wformat -@item -Wformat -@cindex -Wparentheses option -@cindex options, -Wparentheses -@item -Wparentheses -@cindex -Wswitch option -@cindex options, -Wswitch -@item -Wswitch -@cindex -Wtraditional option -@cindex options, -Wtraditional -@item -Wtraditional -@cindex -Wshadow option -@cindex options, -Wshadow -@item -Wshadow -@cindex -Wid-clash-@var{len} option -@cindex options, -Wid-clash-@var{len} -@item -Wid-clash-@var{len} -@cindex -Wlarger-than-@var{len} option -@cindex options, -Wlarger-than-@var{len} -@item -Wlarger-than-@var{len} -@cindex -Wconversion option -@cindex options, -Wconversion -@item -Wconversion -@cindex -Waggregate-return option -@cindex options, -Waggregate-return -@item -Waggregate-return -@cindex -Wredundant-decls option -@cindex options, -Wredundant-decls -@item -Wredundant-decls -@cindex unsupported warnings -@cindex warnings, unsupported -These options all could have some relevant meaning for -GNU Fortran programs, but are not yet supported. -@end table - -@node Debugging Options -@section Options for Debugging Your Program or GNU Fortran -@cindex options, debugging -@cindex debugging information options - -GNU Fortran has various special options that are used for debugging -either your program or @code{g77}. - -@table @code -@cindex -g option -@cindex options, -g -@item -g -Produce debugging information in the operating system's native format -(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging -information. - -@cindex common blocks -@cindex equivalence areas -@cindex missing debug features -Support for this option in Fortran programs is incomplete. -In particular, names of variables and arrays in common blocks -or that are storage-associated via @code{EQUIVALENCE} are -unavailable to the debugger. - -However, version 0.5.19 of @code{g77} does provide this information -in a rudimentary way, as controlled by the -@samp{-fdebug-kludge} option. - -@xref{Code Gen Options,,Options for Code Generation Conventions}, -for more information. -@end table - -@xref{Debugging Options,,Options for Debugging Your Program or GNU CC, -gcc,Using and Porting GNU CC}, for more information on debugging options. - -@node Optimize Options -@section Options That Control Optimization -@cindex optimize options -@cindex options, optimization - -Most Fortran users will want to use no optimization when -developing and testing programs, and use @samp{-O} or @samp{-O2} when -compiling programs for late-cycle testing and for production use. -However, note that certain diagnostics---such as for uninitialized -variables---depend on the flow analysis done by @samp{-O}, i.e.@: you -must use @samp{-O} or @samp{-O2} to get such diagnostics. - -The following flags have particular applicability when -compiling Fortran programs: - -@table @code -@cindex -malign-double option -@cindex options, -malign-double -@item -malign-double -(Intel x86 architecture only.) - -Noticeably improves performance of @code{g77} programs making -heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data -on some systems. -In particular, systems using Pentium, Pentium Pro, 586, and -686 implementations -of the i386 architecture execute programs faster when -@code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data are -aligned on 64-bit boundaries -in memory. - -This option can, at least, make benchmark results more consistent -across various system configurations, versions of the program, -and data sets. - -@emph{Note:} The warning in the @code{gcc} documentation about -this option does not apply, generally speaking, to Fortran -code compiled by @code{g77}. - -@xref{Aligned Data}, for more information on alignment issues. - -@emph{Also also note:} The negative form of @samp{-malign-double} -is @samp{-mno-align-double}, not @samp{-benign-double}. - -@cindex -ffloat-store option -@cindex options, -ffloat-store -@item -ffloat-store -@cindex IEEE 754 conformance -@cindex conformance, IEEE 754 -@cindex floating-point, precision -Might help a Fortran program that depends on exact IEEE conformance on -some machines, but might slow down a program that doesn't. - -This option is effective when the floating-point unit is set to work in -IEEE 854 `extended precision'---as it typically is on x86 and m68k GNU -systems---rather than IEEE 754 double precision. @samp{-ffloat-store} -tries to remove the extra precision by spilling data from floating-point -registers into memory and this typically involves a big performance -hit. However, it doesn't affect intermediate results, so that it is -only partially effective. `Excess precision' is avoided in code like: -@smallexample -a = b + c -d = a * e -@end smallexample -but not in code like: -@smallexample - d = (b + c) * e -@end smallexample - -For another, potentially better, way of controlling the precision, -see @ref{Floating-point precision}. - -@cindex -fforce-mem option -@cindex options, -fforce-mem -@item -fforce-mem -@cindex -fforce-addr option -@cindex options, -fforce-addr -@item -fforce-addr -@cindex loops, speeding up -@cindex speed, of loops -Might improve optimization of loops. - -@cindex -fno-inline option -@cindex options, -fno-inline -@item -fno-inline -@cindex in-line code -@cindex compilation, in-line -@c DL: Only relevant for -O3? -Don't compile statement functions inline. -Might reduce the size of a program unit---which might be at -expense of some speed (though it should compile faster). -Note that if you are not optimizing, no functions can be expanded inline. - -@cindex -ffast-math option -@cindex options, -ffast-math -@item -ffast-math -@cindex IEEE 754 conformance -@cindex conformance, IEEE 754 -Might allow some programs designed to not be too dependent -on IEEE behavior for floating-point to run faster, or die trying. - -@cindex -fstrength-reduce option -@cindex options, -fstrength-reduce -@item -fstrength-reduce -@cindex loops, speeding up -@cindex speed, of loops -@c DL: normally defaulted? -Might make some loops run faster. - -@cindex -frerun-cse-after-loop option -@cindex options, -frerun-cse-after-loop -@item -frerun-cse-after-loop -@cindex -fexpensive-optimizations option -@cindex options, -fexpensive-optimizations -@c DL: This is -O2? -@item -fexpensive-optimizations -@cindex -fdelayed-branch option -@cindex options, -fdelayed-branch -@item -fdelayed-branch -@cindex -fschedule-insns option -@cindex options, -fschedule-insns -@item -fschedule-insns -@cindex -fschedule-insns2 option -@cindex options, -fschedule-insns2 -@item -fschedule-insns2 -@cindex -fcaller-saves option -@cindex options, -fcaller-saves -@item -fcaller-saves -Might improve performance on some code. - -@cindex -funroll-loops option -@cindex options, -funroll-loops -@item -funroll-loops -@cindex loops, unrolling -@cindex unrolling loops -@cindex loops, optimizing -@cindex indexed (iterative) @code{DO} -@cindex iterative @code{DO} -@c DL: fixme: Craig doesn't like `indexed' but f95 doesn't seem to -@c provide a suitable term -@c CB: I've decided on `iterative', for the time being, and changed -@c my previous, rather bizarre, use of `imperative' to that -@c (though `precomputed-trip' would be a more precise adjective) -Typically improves performance on code using iterative @code{DO} loops by -unrolling them and is probably generally appropriate for Fortran, though -it is not turned on at any optimization level. -Note that outer loop unrolling isn't done specifically; decisions about -whether to unroll a loop are made on the basis of its instruction count. - -@c DL: Fixme: This should obviously go somewhere else... -Also, no `loop discovery'@footnote{@dfn{loop discovery} refers to the -process by which a compiler, or indeed any reader of a program, -determines which portions of the program are more likely to be executed -repeatedly as it is being run. Such discovery typically is done early -when compiling using optimization techniques, so the ``discovered'' -loops get more attention---and more run-time resources, such as -registers---from the compiler. It is easy to ``discover'' loops that are -constructed out of looping constructs in the language -(such as Fortran's @code{DO}). For some programs, ``discovering'' loops -constructed out of lower-level constructs (such as @code{IF} and -@code{GOTO}) can lead to generation of more optimal code -than otherwise.} is done, so only loops written with @code{DO} -benefit from loop optimizations, including---but not limited -to---unrolling. Loops written with @code{IF} and @code{GOTO} are not -currently recognized as such. This option unrolls only iterative -@code{DO} loops, not @code{DO WHILE} loops. - -@cindex -funroll-all-loops option -@cindex options, -funroll-all-loops -@cindex DO WHILE -@item -funroll-all-loops -@c DL: Check my understanding of -funroll-all-loops v. -funroll-loops is correct. -Probably improves performance on code using @code{DO WHILE} loops by -unrolling them in addition to iterative @code{DO} loops. In the absence -of @code{DO WHILE}, this option is equivalent to @samp{-funroll-loops} -but possibly slower. - -@item -fno-move-all-movables -@cindex -fno-move-all-movables option -@cindex options, -fno-move-all-movables -@item -fno-reduce-all-givs -@cindex -fno-reduce-all-givs option -@cindex options, -fno-reduce-all-givs -@item -fno-rerun-loop-opt -@cindex -fno-rerun-loop-opt option -@cindex options, -fno-rerun-loop-opt -@emph{Version info:} -These options are not supported by -versions of @code{g77} based on @code{gcc} version 2.8. - -Each of these might improve performance on some code. - -Analysis of Fortran code optimization and the resulting -optimizations triggered by the above options were -contributed by Toon Moene (@email{toon@@moene.indiv.nluug.nl}). - -These three options are intended to be removed someday, once -they have helped determine the efficacy of various -approaches to improving the performance of Fortran code. - -Please let us know how use of these options affects -the performance of your production code. -We're particularly interested in code that runs faster -when these options are @emph{disabled}, and in -non-Fortran code that benefits when they are -@emph{enabled} via the above @code{gcc} command-line options. -@end table - -@xref{Optimize Options,,Options That Control Optimization, -gcc,Using and Porting GNU CC}, for more information on options -to optimize the generated machine code. - -@node Preprocessor Options -@section Options Controlling the Preprocessor -@cindex preprocessor options -@cindex options, preprocessor -@cindex cpp program -@cindex programs, cpp - -These options control the C preprocessor, which is run on each C source -file before actual compilation. - -@xref{Preprocessor Options,,Options Controlling the Preprocessor, -gcc,Using and Porting GNU CC}, for information on C preprocessor options. - -@cindex INCLUDE directive -@cindex directive, INCLUDE -Some of these options also affect how @code{g77} processes the -@code{INCLUDE} directive. -Since this directive is processed even when preprocessing -is not requested, it is not described in this section. -@xref{Directory Options,,Options for Directory Search}, for -information on how @code{g77} processes the @code{INCLUDE} directive. - -However, the @code{INCLUDE} directive does not apply -preprocessing to the contents of the included file itself. - -Therefore, any file that contains preprocessor directives -(such as @code{#include}, @code{#define}, and @code{#if}) -must be included via the @code{#include} directive, not -via the @code{INCLUDE} directive. -Therefore, any file containing preprocessor directives, -if included, is necessarily included by a file that itself -contains preprocessor directives. - -@node Directory Options -@section Options for Directory Search -@cindex directory, options -@cindex options, directory search -@cindex search path - -These options affect how the @code{cpp} preprocessor searches -for files specified via the @code{#include} directive. -Therefore, when compiling Fortran programs, they are meaningful -when the preprocessor is used. - -@cindex INCLUDE directive -@cindex directive, INCLUDE -Some of these options also affect how @code{g77} searches -for files specified via the @code{INCLUDE} directive, -although files included by that directive are not, -themselves, preprocessed. -These options are: - -@table @code -@cindex -I- option -@cindex options, -I- -@item -I- -@cindex -Idir option -@cindex options, -Idir -@item -I@var{dir} -@cindex directory, search paths for inclusion -@cindex inclusion, directory search paths for -@cindex search paths, for included files -@cindex paths, search -These affect interpretation of the @code{INCLUDE} directive -(as well as of the @code{#include} directive of the @code{cpp} -preprocessor). - -Note that @samp{-I@var{dir}} must be specified @emph{without} any -spaces between @samp{-I} and the directory name---that is, -@samp{-Ifoo/bar} is valid, but @samp{-I foo/bar} -is rejected by the @code{g77} compiler (though the preprocessor supports -the latter form). -@c this is due to toplev.c's inflexible option processing -Also note that the general behavior of @samp{-I} and -@code{INCLUDE} is pretty much the same as of @samp{-I} with -@code{#include} in the @code{cpp} preprocessor, with regard to -looking for @file{header.gcc} files and other such things. - -@xref{Directory Options,,Options for Directory Search, -gcc,Using and Porting GNU CC}, for information on the @samp{-I} option. -@end table - -@node Code Gen Options -@section Options for Code Generation Conventions -@cindex code generation, conventions -@cindex options, code generation -@cindex run-time, options - -These machine-independent options control the interface conventions -used in code generation. - -Most of them have both positive and negative forms; the negative form -of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only -one of the forms is listed---the one which is not the default. You -can figure out the other form by either removing @samp{no-} or adding -it. - -@table @code -@cindex -fno-automatic option -@cindex options, -fno-automatic -@item -fno-automatic -@cindex SAVE statement -@cindex statements, SAVE -Treat each program unit as if the @code{SAVE} statement was specified -for every local variable and array referenced in it. -Does not affect common blocks. -(Some Fortran compilers provide this option under -the name @samp{-static}.) - -@cindex -finit-local-zero option -@cindex options, -finit-local-zero -@item -finit-local-zero -@cindex DATA statement -@cindex statements, DATA -@cindex initialization, of local variables -@cindex variables, initialization of -@cindex uninitialized variables -@cindex variables, uninitialized -Specify that variables and arrays that are local to a program unit -(not in a common block and not passed as an argument) are to be initialized -to binary zeros. - -Since there is a run-time penalty for initialization of variables -that are not given the @code{SAVE} attribute, it might be a -good idea to also use @samp{-fno-automatic} with @samp{-finit-local-zero}. - -@cindex -fno-f2c option -@cindex options, -fno-f2c -@item -fno-f2c -@cindex @code{f2c} compatibility -@cindex compatibility, @code{f2c} -Do not generate code designed to be compatible with code generated -by @code{f2c}; use the GNU calling conventions instead. - -The @code{f2c} calling conventions require functions that return -type @code{REAL(KIND=1)} to actually return the C type @code{double}, -and functions that return type @code{COMPLEX} to return the -values via an extra argument in the calling sequence that points -to where to store the return value. -Under the GNU calling conventions, such functions simply return -their results as they would in GNU C---@code{REAL(KIND=1)} functions -return the C type @code{float}, and @code{COMPLEX} functions -return the GNU C type @code{complex} (or its @code{struct} -equivalent). - -This does not affect the generation of code that interfaces with the -@code{libg2c} library. - -However, because the @code{libg2c} library uses @code{f2c} -calling conventions, @code{g77} rejects attempts to pass -intrinsics implemented by routines in this library as actual -arguments when @samp{-fno-f2c} is used, to avoid bugs when -they are actually called by code expecting the GNU calling -conventions to work. - -For example, @samp{INTRINSIC ABS;CALL FOO(ABS)} is -rejected when @samp{-fno-f2c} is in force. -(Future versions of the @code{g77} run-time library might -offer routines that provide GNU-callable versions of the -routines that implement the @code{f2c}-callable intrinsics -that may be passed as actual arguments, so that -valid programs need not be rejected when @samp{-fno-f2c} -is used.) - -@strong{Caution:} If @samp{-fno-f2c} is used when compiling any -source file used in a program, it must be used when compiling -@emph{all} Fortran source files used in that program. - -@c seems kinda dumb to tell people about an option they can't use -- jcb -@c then again, we want users building future-compatible libraries with it. -@cindex -ff2c-library option -@cindex options, -ff2c-library -@item -ff2c-library -Specify that use of @code{libg2c} (or the original @code{libf2c}) -is required. -This is the default for the current version of @code{g77}. - -Currently it is not -valid to specify @samp{-fno-f2c-library}. -This option is provided so users can specify it in shell -scripts that build programs and libraries that require the -@code{libf2c} library, even when being compiled by future -versions of @code{g77} that might otherwise default to -generating code for an incompatible library. - -@cindex -fno-underscoring option -@cindex options, -fno-underscoring -@item -fno-underscoring -@cindex underscore -@cindex symbol names, underscores -@cindex transforming symbol names -@cindex symbol names, transforming -Do not transform names of entities specified in the Fortran -source file by appending underscores to them. - -With @samp{-funderscoring} in effect, @code{g77} appends two underscores -to names with underscores and one underscore to external names with -no underscores. (@code{g77} also appends two underscores to internal -names with underscores to avoid naming collisions with external names. -The @samp{-fno-second-underscore} option disables appending of the -second underscore in all cases.) - -This is done to ensure compatibility with code produced by many -UNIX Fortran compilers, including @code{f2c}, which perform the -same transformations. - -Use of @samp{-fno-underscoring} is not recommended unless you are -experimenting with issues such as integration of (GNU) Fortran into -existing system environments (vis-a-vis existing libraries, tools, and -so on). - -For example, with @samp{-funderscoring}, and assuming other defaults like -@samp{-fcase-lower} and that @samp{j()} and @samp{max_count()} are -external functions while @samp{my_var} and @samp{lvar} are local variables, -a statement like - -@smallexample -I = J() + MAX_COUNT (MY_VAR, LVAR) -@end smallexample - -@noindent -is implemented as something akin to: - -@smallexample -i = j_() + max_count__(&my_var__, &lvar); -@end smallexample - -With @samp{-fno-underscoring}, the same statement is implemented as: - -@smallexample -i = j() + max_count(&my_var, &lvar); -@end smallexample - -Use of @samp{-fno-underscoring} allows direct specification of -user-defined names while debugging and when interfacing @code{g77}-compiled -code with other languages. - -Note that just because the names match does @emph{not} mean that the -interface implemented by @code{g77} for an external name matches the -interface implemented by some other language for that same name. -That is, getting code produced by @code{g77} to link to code produced -by some other compiler using this or any other method can be only a -small part of the overall solution---getting the code generated by -both compilers to agree on issues other than naming can require -significant effort, and, unlike naming disagreements, linkers normally -cannot detect disagreements in these other areas. - -Also, note that with @samp{-fno-underscoring}, the lack of appended -underscores introduces the very real possibility that a user-defined -external name will conflict with a name in a system library, which -could make finding unresolved-reference bugs quite difficult in some -cases---they might occur at program run time, and show up only as -buggy behavior at run time. - -In future versions of @code{g77}, we hope to improve naming and linking -issues so that debugging always involves using the names as they appear -in the source, even if the names as seen by the linker are mangled to -prevent accidental linking between procedures with incompatible -interfaces. - -@cindex -fno-second-underscore option -@cindex options, -fno-second-underscore -@item -fno-second-underscore -@cindex underscore -@cindex symbol names, underscores -@cindex transforming symbol names -@cindex symbol names, transforming -Do not append a second underscore to names of entities specified -in the Fortran source file. - -This option has no effect if @samp{-fno-underscoring} is -in effect. - -Otherwise, with this option, an external name such as @samp{MAX_COUNT} -is implemented as a reference to the link-time external symbol -@samp{max_count_}, instead of @samp{max_count__}. - -@cindex -fno-ident option -@cindex options, -fno-ident -@item -fno-ident -Ignore the @samp{#ident} directive. - -@cindex -fzeros option -@cindex options, -fzeros -@item -fzeros -Treat initial values of zero as if they were any other value. - -As of version 0.5.18, @code{g77} normally treats @code{DATA} and -other statements that are used to specify initial values of zero -for variables and arrays as if no values were actually specified, -in the sense that no diagnostics regarding multiple initializations -are produced. - -This is done to speed up compiling of programs that initialize -large arrays to zeros. - -Use @samp{-fzeros} to revert to the simpler, slower behavior -that can catch multiple initializations by keeping track of -all initializations, zero or otherwise. - -@emph{Caution:} Future versions of @code{g77} might disregard this option -(and its negative form, the default) or interpret it somewhat -differently. -The interpretation changes will affect only non-standard -programs; standard-conforming programs should not be affected. - -@cindex -fdebug-kludge option -@cindex options, -fdebug-kludge -@item -fdebug-kludge -Emit information on @code{COMMON} and @code{EQUIVALENCE} members -that might help users of debuggers work around lack of proper debugging -information on such members. - -As of version 0.5.19, @code{g77} offers this option to emit -information on members of aggregate areas to help users while debugging. -This information consists of establishing the type and contents of each -such member so that, when a debugger is asked to print the contents, -the printed information provides rudimentary debugging information. -This information identifies the name of the aggregate area (either the -@code{COMMON} block name, or the @code{g77}-assigned name for the -@code{EQUIVALENCE} name) and the offset, in bytes, of the member from -the beginning of the area. - -Using @code{gdb}, this information is not coherently displayed in the Fortran -language mode, so temporarily switching to the C language mode to display the -information is suggested. -Use @samp{set language c} and @samp{set language fortran} to accomplish this. - -For example: - -@smallexample - COMMON /X/A,B - EQUIVALENCE (C,D) - CHARACTER XX*50 - EQUIVALENCE (I,XX(20:20)) - END - -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is absolutely no warranty for GDB; type "show warranty" for details. -GDB 4.16 (lm-gnits-dwim), Copyright 1996 Free Software Foundation, Inc... -(gdb) b MAIN__ -Breakpoint 1 at 0t1200000201120112: file cd.f, line 5. -(gdb) r -Starting program: /home/user/a.out - -Breakpoint 1, MAIN__ () at cd.f:5 -Current language: auto; currently fortran -(gdb) set language c -Warning: the current language does not match this frame. -(gdb) p a -$2 = "At (COMMON) `x_' plus 0 bytes" -(gdb) p b -$3 = "At (COMMON) `x_' plus 4 bytes" -(gdb) p c -$4 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" -(gdb) p d -$5 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" -(gdb) p i -$6 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 20 bytes" -(gdb) p xx -$7 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 1 bytes" -(gdb) set language fortran -(gdb) -@end smallexample - -@noindent -Use @samp{-fdebug-kludge} to generate this information, -which might make some programs noticeably larger. - -@emph{Caution:} Future versions of @code{g77} might disregard this option -(and its negative form). -Current plans call for this to happen when published versions of @code{g77} -and @code{gdb} exist that provide proper access to debugging information on -@code{COMMON} and @code{EQUIVALENCE} members. - -@cindex -femulate-complex option -@cindex options, -femulate-complex -@item -femulate-complex -Implement @code{COMPLEX} arithmetic via emulation, -instead of using the facilities of -the @code{gcc} back end that provide direct support of -@code{complex} arithmetic. - -(@code{gcc} had some bugs in its back-end support -for @code{complex} arithmetic, due primarily to the support not being -completed as of version 2.8.1 and @code{egcs} 1.1.2.) - -Use @samp{-femulate-complex} if you suspect code-generation bugs, -or experience compiler crashes, -that might result from @code{g77} using the @code{COMPLEX} support -in the @code{gcc} back end. -If using that option fixes the bugs or crashes you are seeing, -that indicates a likely @code{g77} bugs -(though, all compiler crashes are considered bugs), -so, please report it. -(Note that the known bugs, now believed fixed, produced compiler crashes -rather than causing the generation of incorrect code.) - -Use of this option should not affect how Fortran code compiled -by @code{g77} works in terms of its interfaces to other code, -e.g. that compiled by @code{f2c}. - -@emph{Caution:} Future versions of @code{g77} might ignore both forms -of this option. - -@cindex -falias-check option -@cindex options, -falias-check -@cindex -fargument-alias option -@cindex options, -fargument-alias -@cindex -fargument-noalias option -@cindex options, -fargument-noalias -@cindex -fno-argument-noalias-global option -@cindex options, -fno-argument-noalias-global -@item -falias-check -@item -fargument-alias -@item -fargument-noalias -@item -fno-argument-noalias-global -@emph{Version info:} -These options are not supported by -versions of @code{g77} based on @code{gcc} version 2.8. - -These options specify to what degree aliasing -(overlap) -is permitted between -arguments (passed as pointers) and @code{COMMON} (external, or -public) storage. - -The default for Fortran code, as mandated by the FORTRAN 77 and -Fortran 90 standards, is @samp{-fargument-noalias-global}. -The default for code written in the C language family is -@samp{-fargument-alias}. - -Note that, on some systems, compiling with @samp{-fforce-addr} in -effect can produce more optimal code when the default aliasing -options are in effect (and when optimization is enabled). - -@xref{Aliasing Assumed To Work}, for detailed information on the implications -of compiling Fortran code that depends on the ability to alias dummy -arguments. - -@cindex -fno-globals option -@cindex options, -fno-globals -@item -fno-globals -@cindex global names, warning -@cindex warnings, global names -@cindex in-line code -@cindex compilation, in-line -Disable diagnostics about inter-procedural -analysis problems, such as disagreements about the -type of a function or a procedure's argument, -that might cause a compiler crash when attempting -to inline a reference to a procedure within a -program unit. -(The diagnostics themselves are still produced, but -as warnings, unless @samp{-Wno-globals} is specified, -in which case no relevant diagnostics are produced.) - -Further, this option disables such inlining, to -avoid compiler crashes resulting from incorrect -code that would otherwise be diagnosed. - -As such, this option might be quite useful when -compiling existing, ``working'' code that happens -to have a few bugs that do not generally show themselves, -but which @code{g77} diagnoses. - -Use of this option therefore has the effect of -instructing @code{g77} to behave more like it did -up through version 0.5.19.1, when it paid little or -no attention to disagreements between program units -about a procedure's type and argument information, -and when it performed no inlining of procedures -(except statement functions). - -Without this option, @code{g77} defaults to performing -the potentially inlining procedures as it started doing -in version 0.5.20, but as of version 0.5.21, it also -diagnoses disagreements that might cause such inlining -to crash the compiler as (fatal) errors, -and warns about similar disagreements -that are currently believed to not -likely to result in the compiler later crashing -or producing incorrect code. - -@cindex -fflatten-arrays option -@item -fflatten-arrays -@cindex array performance -@cindex arrays, flattening -Use back end's C-like constructs -(pointer plus offset) -instead of its @code{ARRAY_REF} construct -to handle all array references. - -@emph{Note:} This option is not supported. -It is intended for use only by @code{g77} developers, -to evaluate code-generation issues. -It might be removed at any time. - -@cindex -fbounds-check option -@cindex -ffortran-bounds-check option -@item -fbounds-check -@itemx -ffortran-bounds-check -@cindex bounds checking -@cindex range checking -@cindex array bounds checking -@cindex subscript checking -@cindex substring checking -@cindex checking subscripts -@cindex checking substrings -Enable generation of run-time checks for array subscripts -and substring start and end points -against the (locally) declared minimum and maximum values. - -The current implementation uses the @code{libf2c} -library routine @code{s_rnge} to print the diagnostic. - -However, whereas @code{f2c} generates a single check per -reference for a multi-dimensional array, of the computed -offset against the valid offset range (0 through the size of the array), -@code{g77} generates a single check per @emph{subscript} expression. -This catches some cases of potential bugs that @code{f2c} does not, -such as references to below the beginning of an assumed-size array. - -@code{g77} also generates checks for @code{CHARACTER} substring references, -something @code{f2c} currently does not do. - -Use the new @samp{-ffortran-bounds-check} option -to specify bounds-checking for only the Fortran code you are compiling, -not necessarily for code written in other languages. - -@emph{Note:} To provide more detailed information on the offending subscript, -@code{g77} provides the @code{libg2c} run-time library routine @code{s_rnge} -with somewhat differently-formatted information. -Here's a sample diagnostic: - -@smallexample -Subscript out of range on file line 4, procedure rnge.f/bf. -Attempt to access the -6-th element of variable b[subscript-2-of-2]. -Aborted -@end smallexample - -The above message indicates that the offending source line is -line 4 of the file @file{rnge.f}, -within the program unit (or statement function) named @samp{bf}. -The offended array is named @samp{b}. -The offended array dimension is the second for a two-dimensional array, -and the offending, computed subscript expression was @samp{-6}. - -For a @code{CHARACTER} substring reference, the second line has -this appearance: - -@smallexample -Attempt to access the 11-th element of variable a[start-substring]. -@end smallexample - -This indicates that the offended @code{CHARACTER} variable or array -is named @samp{a}, -the offended substring position is the starting (leftmost) position, -and the offending substring expression is @samp{11}. - -(Though the verbage of @code{s_rnge} is not ideal -for the purpose of the @code{g77} compiler, -the above information should provide adequate diagnostic abilities -to it users.) -@end table - -@xref{Code Gen Options,,Options for Code Generation Conventions, -gcc,Using and Porting GNU CC}, for information on more options -offered by the GBE -shared by @code{g77}, @code{gcc}, and other GNU compilers. - -Some of these do @emph{not} work when compiling programs written in Fortran: - -@table @code -@cindex -fpcc-struct-return option -@cindex options, -fpcc-struct-return -@item -fpcc-struct-return -@cindex -freg-struct-return option -@cindex options, -freg-struct-return -@item -freg-struct-return -You should not use these except strictly the same way as you -used them to build the version of @code{libg2c} with which -you will be linking all code compiled by @code{g77} with the -same option. - -@cindex -fshort-double option -@cindex options, -fshort-double -@item -fshort-double -This probably either has no effect on Fortran programs, or -makes them act loopy. - -@cindex -fno-common option -@cindex options, -fno-common -@item -fno-common -Do not use this when compiling Fortran programs, -or there will be Trouble. - -@cindex -fpack-struct option -@cindex options, -fpack-struct -@item -fpack-struct -This probably will break any calls to the @code{libg2c} library, -at the very least, even if it is built with the same option. -@end table - -@node Environment Variables -@section Environment Variables Affecting GNU Fortran -@cindex environment variables - -GNU Fortran currently does not make use of any environment -variables to control its operation above and beyond those -that affect the operation of @code{gcc}. - -@xref{Environment Variables,,Environment Variables Affecting GNU CC, -gcc,Using and Porting GNU CC}, for information on environment -variables. - -@include news.texi - -@set USERVISONLY -@include news.texi -@clear USERVISONLY - -@node Language -@chapter The GNU Fortran Language - -@cindex standard, ANSI FORTRAN 77 -@cindex ANSI FORTRAN 77 standard -@cindex reference works -GNU Fortran supports a variety of extensions to, and dialects -of, the Fortran language. -Its primary base is the ANSI FORTRAN 77 standard, currently available on -the network at -@uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html} -or as monolithic text at -@uref{http://www.fortran.com/fortran/F77_std/f77_std.html}. -It offers some extensions that are popular among users -of UNIX @code{f77} and @code{f2c} compilers, some that -are popular among users of other compilers (such as Digital -products), some that are popular among users of the -newer Fortran 90 standard, and some that are introduced -by GNU Fortran. - -@cindex textbooks -(If you need a text on Fortran, -a few freely available electronic references have pointers from -@uref{http://www.fortran.com/fortran/Books/}. There is a `cooperative -net project', @cite{User Notes on Fortran Programming} at -@uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this -material might not apply specifically to @code{g77}.) - -Part of what defines a particular implementation of a Fortran -system, such as @code{g77}, is the particular characteristics -of how it supports types, constants, and so on. -Much of this is left up to the implementation by the various -Fortran standards and accepted practice in the industry. - -The GNU Fortran @emph{language} is described below. -Much of the material is organized along the same lines -as the ANSI FORTRAN 77 standard itself. - -@xref{Other Dialects}, for information on features @code{g77} supports -that are not part of the GNU Fortran language. - -@emph{Note}: This portion of the documentation definitely needs a lot -of work! - -@menu -Relationship to the ANSI FORTRAN 77 standard: -* Direction of Language Development:: Where GNU Fortran is headed. -* Standard Support:: Degree of support for the standard. - -Extensions to the ANSI FORTRAN 77 standard: -* Conformance:: -* Notation Used:: -* Terms and Concepts:: -* Characters Lines Sequence:: -* Data Types and Constants:: -* Expressions:: -* Specification Statements:: -* Control Statements:: -* Functions and Subroutines:: -* Scope and Classes of Names:: -* I/O:: -* Fortran 90 Features:: -@end menu - -@node Direction of Language Development -@section Direction of Language Development -@cindex direction of language development -@cindex features, language -@cindex language, features - -The purpose of the following description of the GNU Fortran -language is to promote wide portability of GNU Fortran programs. - -GNU Fortran is an evolving language, due to the -fact that @code{g77} itself is in beta test. -Some current features of the language might later -be redefined as dialects of Fortran supported by @code{g77} -when better ways to express these features are added to @code{g77}, -for example. -Such features would still be supported by -@code{g77}, but would be available only when -one or more command-line options were used. - -The GNU Fortran @emph{language} is distinct from the -GNU Fortran @emph{compilation system} (@code{g77}). - -For example, @code{g77} supports various dialects of -Fortran---in a sense, these are languages other than -GNU Fortran---though its primary -purpose is to support the GNU Fortran language, which also is -described in its documentation and by its implementation. - -On the other hand, non-GNU compilers might offer -support for the GNU Fortran language, and are encouraged -to do so. - -Currently, the GNU Fortran language is a fairly fuzzy object. -It represents something of a cross between what @code{g77} accepts -when compiling using the prevailing defaults and what this -document describes as being part of the language. - -Future versions of @code{g77} are expected to clarify the -definition of the language in the documentation. -Often, this will mean adding new features to the language, in the form -of both new documentation and new support in @code{g77}. -However, it might occasionally mean removing a feature -from the language itself to ``dialect'' status. -In such a case, the documentation would be adjusted -to reflect the change, and @code{g77} itself would likely be changed -to require one or more command-line options to continue supporting -the feature. - -The development of the GNU Fortran language is intended to strike -a balance between: - -@itemize @bullet -@item -Serving as a mostly-upwards-compatible language from the -de facto UNIX Fortran dialect as supported by @code{f77}. - -@item -Offering new, well-designed language features. -Attributes of such features include -not making existing code any harder to read -(for those who might be unaware that the new -features are not in use) and -not making state-of-the-art -compilers take longer to issue diagnostics, -among others. - -@item -Supporting existing, well-written code without gratuitously -rejecting non-standard constructs, regardless of the origin -of the code (its dialect). - -@item -Offering default behavior and command-line options to reduce -and, where reasonable, eliminate the need for programmers to make -any modifications to code that already works in existing -production environments. - -@item -Diagnosing constructs that have different meanings in different -systems, languages, and dialects, while offering clear, -less ambiguous ways to express each of the different meanings -so programmers can change their code appropriately. -@end itemize - -One of the biggest practical challenges for the developers of the -GNU Fortran language is meeting the sometimes contradictory demands -of the above items. - -For example, a feature might be widely used in one popular environment, -but the exact same code that utilizes that feature might not work -as expected---perhaps it might mean something entirely different---in -another popular environment. - -Traditionally, Fortran compilers---even portable ones---have solved this -problem by simply offering the appropriate feature to users of -the respective systems. -This approach treats users of various Fortran systems and dialects -as remote ``islands'', or camps, of programmers, and assume that these -camps rarely come into contact with each other (or, -especially, with each other's code). - -Project GNU takes a radically different approach to software and language -design, in that it assumes that users of GNU software do not necessarily -care what kind of underlying system they are using, regardless -of whether they are using software (at the user-interface -level) or writing it (for example, writing Fortran or C code). - -As such, GNU users rarely need consider just what kind of underlying -hardware (or, in many cases, operating system) they are using at any -particular time. -They can use and write software designed for a general-purpose, -widely portable, heterogenous environment---the GNU environment. - -In line with this philosophy, GNU Fortran must evolve into a product -that is widely ported and portable not only in the sense that it can -be successfully built, installed, and run by users, but in the larger -sense that its users can use it in the same way, and expect largely the -same behaviors from it, regardless of the kind of system they are using -at any particular time. - -This approach constrains the solutions @code{g77} can use to resolve -conflicts between various camps of Fortran users. -If these two camps disagree about what a particular construct should -mean, @code{g77} cannot simply be changed to treat that particular construct as -having one meaning without comment (such as a warning), lest the users -expecting it to have the other meaning are unpleasantly surprised that -their code misbehaves when executed. - -The use of the ASCII backslash character in character constants is -an excellent (and still somewhat unresolved) example of this kind of -controversy. -@xref{Backslash in Constants}. -Other examples are likely to arise in the future, as @code{g77} developers -strive to improve its ability to accept an ever-wider variety of existing -Fortran code without requiring significant modifications to said code. - -Development of GNU Fortran is further constrained by the desire -to avoid requiring programmers to change their code. -This is important because it allows programmers, administrators, -and others to more faithfully evaluate and validate @code{g77} -(as an overall product and as new versions are distributed) -without having to support multiple versions of their programs -so that they continue to work the same way on their existing -systems (non-GNU perhaps, but possibly also earlier versions -of @code{g77}). - -@node Standard Support -@section ANSI FORTRAN 77 Standard Support -@cindex ANSI FORTRAN 77 support -@cindex standard, support for -@cindex support, FORTRAN 77 -@cindex compatibility, FORTRAN 77 -@cindex FORTRAN 77 compatibility - -GNU Fortran supports ANSI FORTRAN 77 with the following caveats. -In summary, the only ANSI FORTRAN 77 features @code{g77} doesn't -support are those that are probably rarely used in actual code, -some of which are explicitly disallowed by the Fortran 90 standard. - -@menu -* No Passing External Assumed-length:: CHAR*(*) CFUNC restriction. -* No Passing Dummy Assumed-length:: CHAR*(*) CFUNC restriction. -* No Pathological Implied-DO:: No @samp{((@dots{}, I=@dots{}), I=@dots{})}. -* No Useless Implied-DO:: No @samp{(A, I=1, 1)}. -@end menu - -@node No Passing External Assumed-length -@subsection No Passing External Assumed-length - -@code{g77} disallows passing of an external procedure -as an actual argument if the procedure's -type is declared @code{CHARACTER*(*)}. For example: - -@example -CHARACTER*(*) CFUNC -EXTERNAL CFUNC -CALL FOO(CFUNC) -END -@end example - -@noindent -It isn't clear whether the standard considers this conforming. - -@node No Passing Dummy Assumed-length -@subsection No Passing Dummy Assumed-length - -@code{g77} disallows passing of a dummy procedure -as an actual argument if the procedure's -type is declared @code{CHARACTER*(*)}. - -@example -SUBROUTINE BAR(CFUNC) -CHARACTER*(*) CFUNC -EXTERNAL CFUNC -CALL FOO(CFUNC) -END -@end example - -@noindent -It isn't clear whether the standard considers this conforming. - -@node No Pathological Implied-DO -@subsection No Pathological Implied-DO - -The @code{DO} variable for an implied-@code{DO} construct in a -@code{DATA} statement may not be used as the @code{DO} variable -for an outer implied-@code{DO} construct. For example, this -fragment is disallowed by @code{g77}: - -@smallexample -DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/ -@end smallexample - -@noindent -This also is disallowed by Fortran 90, as it offers no additional -capabilities and would have a variety of possible meanings. - -Note that it is @emph{very} unlikely that any production Fortran code -tries to use this unsupported construct. - -@node No Useless Implied-DO -@subsection No Useless Implied-DO - -An array element initializer in an implied-@code{DO} construct in a -@code{DATA} statement must contain at least one reference to the @code{DO} -variables of each outer implied-@code{DO} construct. For example, -this fragment is disallowed by @code{g77}: - -@smallexample -DATA (A, I= 1, 1) /1./ -@end smallexample - -@noindent -This also is disallowed by Fortran 90, as FORTRAN 77's more permissive -requirements offer no additional capabilities. -However, @code{g77} doesn't necessarily diagnose all cases -where this requirement is not met. - -Note that it is @emph{very} unlikely that any production Fortran code -tries to use this unsupported construct. - -@node Conformance -@section Conformance - -(The following information augments or overrides the information in -Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 1 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -The definition of the GNU Fortran language is akin to that of -the ANSI FORTRAN 77 language in that it does not generally require -conforming implementations to diagnose cases where programs do -not conform to the language. - -However, @code{g77} as a compiler is being developed in a way that -is intended to enable it to diagnose such cases in an easy-to-understand -manner. - -A program that conforms to the GNU Fortran language should, when -compiled, linked, and executed using a properly installed @code{g77} -system, perform as described by the GNU Fortran language definition. -Reasons for different behavior include, among others: - -@itemize @bullet -@item -Use of resources (memory---heap, stack, and so on; disk space; CPU -time; etc.) exceeds those of the system. - -@item -Range and/or precision of calculations required by the program -exceeds that of the system. - -@item -Excessive reliance on behaviors that are system-dependent -(non-portable Fortran code). - -@item -Bugs in the program. - -@item -Bug in @code{g77}. - -@item -Bugs in the system. -@end itemize - -Despite these ``loopholes'', the availability of a clear specification -of the language of programs submitted to @code{g77}, as this document -is intended to provide, is considered an important aspect of providing -a robust, clean, predictable Fortran implementation. - -The definition of the GNU Fortran language, while having no special -legal status, can therefore be viewed as a sort of contract, or agreement. -This agreement says, in essence, ``if you write a program in this language, -and run it in an environment (such as a @code{g77} system) that supports -this language, the program should behave in a largely predictable way''. - -@node Notation Used -@section Notation Used in This Chapter - -(The following information augments or overrides the information in -Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 1 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -In this chapter, ``must'' denotes a requirement, ``may'' denotes permission, -and ``must not'' and ``may not'' denote prohibition. -Terms such as ``might'', ``should'', and ``can'' generally add little or -nothing in the way of weight to the GNU Fortran language itself, -but are used to explain or illustrate the language. - -For example: - -@display -``The @code{FROBNITZ} statement must precede all executable -statements in a program unit, and may not specify any dummy -arguments. It may specify local or common variables and arrays. -Its use should be limited to portions of the program designed to -be non-portable and system-specific, because it might cause the -containing program unit to behave quite differently on different -systems.'' -@end display - -Insofar as the GNU Fortran language is specified, -the requirements and permissions denoted by the above sample statement -are limited to the placement of the statement and the kinds of -things it may specify. -The rest of the statement---the content regarding non-portable portions -of the program and the differing behavior of program units containing -the @code{FROBNITZ} statement---does not pertain the GNU Fortran -language itself. -That content offers advice and warnings about the @code{FROBNITZ} -statement. - -@emph{Remember:} The GNU Fortran language definition specifies -both what constitutes a valid GNU Fortran program and how, -given such a program, a valid GNU Fortran implementation is -to interpret that program. - -It is @emph{not} incumbent upon a valid GNU Fortran implementation -to behave in any particular way, any consistent way, or any -predictable way when it is asked to interpret input that is -@emph{not} a valid GNU Fortran program. - -Such input is said to have @dfn{undefined} behavior when -interpreted by a valid GNU Fortran implementation, though -an implementation may choose to specify behaviors for some -cases of inputs that are not valid GNU Fortran programs. - -Other notation used herein is that of the GNU texinfo format, -which is used to generate printed hardcopy, on-line hypertext -(Info), and on-line HTML versions, all from a single source -document. -This notation is used as follows: - -@itemize @bullet -@item -Keywords defined by the GNU Fortran language are shown -in uppercase, as in: @code{COMMON}, @code{INTEGER}, and -@code{BLOCK DATA}. - -Note that, in practice, many Fortran programs are written -in lowercase---uppercase is used in this manual as a -means to readily distinguish keywords and sample Fortran-related -text from the prose in this document. - -@item -Portions of actual sample program, input, or output text -look like this: @samp{Actual program text}. - -Generally, uppercase is used for all Fortran-specific and -Fortran-related text, though this does not always include -literal text within Fortran code. - -For example: @samp{PRINT *, 'My name is Bob'}. - -@item -A metasyntactic variable---that is, a name used in this document -to serve as a placeholder for whatever text is used by the -user or programmer---appears as shown in the following example: - -``The @code{INTEGER @var{ivar}} statement specifies that -@var{ivar} is a variable or array of type @code{INTEGER}.'' - -In the above example, any valid text may be substituted for -the metasyntactic variable @var{ivar} to make the statement -apply to a specific instance, as long as the same text is -substituted for @emph{both} occurrences of @var{ivar}. - -@item -Ellipses (``@dots{}'') are used to indicate further text that -is either unimportant or expanded upon further, elsewhere. - -@item -Names of data types are in the style of Fortran 90, in most -cases. - -@xref{Kind Notation}, for information on the relationship -between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)}) -and the more traditional, less portably concise nomenclature -(such as @code{INTEGER*4}). -@end itemize - -@node Terms and Concepts -@section Fortran Terms and Concepts - -(The following information augments or overrides the information in -Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 2 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* Syntactic Items:: -* Statements Comments Lines:: -* Scope of Names and Labels:: -@end menu - -@node Syntactic Items -@subsection Syntactic Items - -(Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.) - -@cindex limits, lengths of names -In GNU Fortran, a symbolic name is at least one character long, -and has no arbitrary upper limit on length. -However, names of entities requiring external linkage (such as -external functions, external subroutines, and @code{COMMON} areas) -might be restricted to some arbitrary length by the system. -Such a restriction is no more constrained than that of one -through six characters. - -Underscores (@samp{_}) are accepted in symbol names after the first -character (which must be a letter). - -@node Statements Comments Lines -@subsection Statements, Comments, and Lines - -(Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.) - -@cindex trailing comment -@cindex comment -@cindex characters, comment -@cindex ! -@cindex exclamation point -@cindex continuation character -@cindex characters, continuation -Use of an exclamation point (@samp{!}) to begin a -trailing comment (a comment that extends to the end of the same -source line) is permitted under the following conditions: - -@itemize @bullet -@item -The exclamation point does not appear in column 6. -Otherwise, it is treated as an indicator of a continuation -line. - -@item -The exclamation point appears outside a character or Hollerith -constant. -Otherwise, the exclamation point is considered part of the -constant. - -@item -The exclamation point appears to the left of any other possible -trailing comment. -That is, a trailing comment may contain exclamation points -in their commentary text. -@end itemize - -@cindex ; -@cindex semicolon -@cindex statements, separated by semicolon -Use of a semicolon (@samp{;}) as a statement separator -is permitted under the following conditions: - -@itemize @bullet -@item -The semicolon appears outside a character or Hollerith -constant. -Otherwise, the semicolon is considered part of the -constant. - -@item -The semicolon appears to the left of a trailing comment. -Otherwise, the semicolon is considered part of that -comment. - -@item -Neither a logical @code{IF} statement nor a non-construct -@code{WHERE} statement (a Fortran 90 feature) may be -followed (in the same, possibly continued, line) by -a semicolon used as a statement separator. - -This restriction avoids the confusion -that can result when reading a line such as: - -@smallexample -IF (VALIDP) CALL FOO; CALL BAR -@end smallexample - -@noindent -Some readers might think the @samp{CALL BAR} is executed -only if @samp{VALIDP} is @code{.TRUE.}, while others might -assume its execution is unconditional. - -(At present, @code{g77} does not diagnose code that -violates this restriction.) -@end itemize - -@node Scope of Names and Labels -@subsection Scope of Symbolic Names and Statement Labels -@cindex scope - -(Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.) - -Included in the list of entities that have a scope of a -program unit are construct names (a Fortran 90 feature). -@xref{Construct Names}, for more information. - -@node Characters Lines Sequence -@section Characters, Lines, and Execution Sequence - -(The following information augments or overrides the information in -Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 3 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* Character Set:: -* Lines:: -* Continuation Line:: -* Statements:: -* Statement Labels:: -* Order:: -* INCLUDE:: -* Cpp-style directives:: -@end menu - -@node Character Set -@subsection GNU Fortran Character Set -@cindex characters - -(Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.) - -Letters include uppercase letters (the twenty-six characters -of the English alphabet) and lowercase letters (their lowercase -equivalent). -Generally, lowercase letters may be used in place of uppercase -letters, though in character and Hollerith constants, they -are distinct. - -Special characters include: - -@itemize @bullet -@item -@cindex ; -@cindex semicolon -Semicolon (@samp{;}) - -@item -@cindex ! -@cindex exclamation point -Exclamation point (@samp{!}) - -@item -@cindex " -@cindex double quote -Double quote (@samp{"}) - -@item -@cindex \ -@cindex backslash -Backslash (@samp{\}) - -@item -@cindex ? -@cindex question mark -Question mark (@samp{?}) - -@item -@cindex # -@cindex hash mark -@cindex pound sign -Hash mark (@samp{#}) - -@item -@cindex & -@cindex ampersand -Ampersand (@samp{&}) - -@item -@cindex % -@cindex percent sign -Percent sign (@samp{%}) - -@item -@cindex _ -@cindex underscore -Underscore (@samp{_}) - -@item -@cindex < -@cindex open angle -@cindex left angle -@cindex open bracket -@cindex left bracket -Open angle (@samp{<}) - -@item -@cindex > -@cindex close angle -@cindex right angle -@cindex close bracket -@cindex right bracket -Close angle (@samp{>}) - -@item -The FORTRAN 77 special characters (@key{SPC}, @samp{=}, -@samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(}, -@samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'}, -and @samp{:}) -@end itemize - -@cindex blank -@cindex space -@cindex SPC -Note that this document refers to @key{SPC} as @dfn{space}, -while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}. - -@node Lines -@subsection Lines -@cindex lines -@cindex source file format -@cindex source format -@cindex file, source -@cindex source code -@cindex code, source -@cindex fixed form -@cindex free form - -(Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.) - -The way a Fortran compiler views source files depends entirely on the -implementation choices made for the compiler, since those choices -are explicitly left to the implementation by the published Fortran -standards. - -The GNU Fortran language mandates a view applicable to UNIX-like -text files---files that are made up of an arbitrary number of lines, -each with an arbitrary number of characters (sometimes called stream-based -files). - -This view does not apply to types of files that are specified as -having a particular number of characters on every single line (sometimes -referred to as record-based files). - -Because a ``line in a program unit is a sequence of 72 characters'', -to quote X3.9-1978, the GNU Fortran language specifies that a -stream-based text file is translated to GNU Fortran lines as follows: - -@itemize @bullet -@item -A newline in the file is the character that represents the end of -a line of text to the underlying system. -For example, on ASCII-based systems, a newline is the @key{NL} -character, which has ASCII value 10 (decimal). - -@item -Each newline in the file serves to end the line of text that precedes -it (and that does not contain a newline). - -@item -The end-of-file marker (@code{EOF}) also serves to end the line -of text that precedes it (and that does not contain a newline). - -@item -@cindex blank -@cindex space -@cindex SPC -Any line of text that is shorter than 72 characters is padded to that length -with spaces (called ``blanks'' in the standard). - -@item -Any line of text that is longer than 72 characters is truncated to that -length, but the truncated remainder must consist entirely of spaces. - -@item -Characters other than newline and the GNU Fortran character set -are invalid. -@end itemize - -For the purposes of the remainder of this description of the GNU -Fortran language, the translation described above has already -taken place, unless otherwise specified. - -The result of the above translation is that the source file appears, -in terms of the remainder of this description of the GNU Fortran language, -as if it had an arbitrary -number of 72-character lines, each character being among the GNU Fortran -character set. - -For example, if the source file itself has two newlines in a row, -the second newline becomes, after the above translation, a single -line containing 72 spaces. - -@node Continuation Line -@subsection Continuation Line -@cindex continuation line, number of -@cindex lines, continuation -@cindex number of continuation lines -@cindex limits, continuation lines - -(Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.) - -A continuation line is any line that both - -@itemize @bullet -@item -Contains a continuation character, and - -@item -Contains only spaces in columns 1 through 5 -@end itemize - -A continuation character is any character of the GNU Fortran character set -other than space (@key{SPC}) or zero (@samp{0}) -in column 6, or a digit (@samp{0} through @samp{9}) in column -7 through 72 of a line that has only spaces to the left of that -digit. - -The continuation character is ignored as far as the content of -the statement is concerned. - -The GNU Fortran language places no limit on the number of -continuation lines in a statement. -In practice, the limit depends on a variety of factors, such as -available memory, statement content, and so on, but no -GNU Fortran system may impose an arbitrary limit. - -@node Statements -@subsection Statements - -(Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.) - -Statements may be written using an arbitrary number of continuation -lines. - -Statements may be separated using the semicolon (@samp{;}), except -that the logical @code{IF} and non-construct @code{WHERE} statements -may not be separated from subsequent statements using only a semicolon -as statement separator. - -The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION}, -and @code{END BLOCK DATA} statements are alternatives to the @code{END} -statement. -These alternatives may be written as normal statements---they are not -subject to the restrictions of the @code{END} statement. - -However, no statement other than @code{END} may have an initial line -that appears to be an @code{END} statement---even @code{END PROGRAM}, -for example, must not be written as: - -@example - END - &PROGRAM -@end example - -@node Statement Labels -@subsection Statement Labels - -(Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.) - -A statement separated from its predecessor via a semicolon may be -labeled as follows: - -@itemize @bullet -@item -The semicolon is followed by the label for the statement, -which in turn follows the label. - -@item -The label must be no more than five digits in length. - -@item -The first digit of the label for the statement is not -the first non-space character on a line. -Otherwise, that character is treated as a continuation -character. -@end itemize - -A statement may have only one label defined for it. - -@node Order -@subsection Order of Statements and Lines - -(Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.) - -Generally, @code{DATA} statements may precede executable statements. -However, specification statements pertaining to any entities -initialized by a @code{DATA} statement must precede that @code{DATA} -statement. -For example, -after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but -@samp{INTEGER J} is permitted. - -The last line of a program unit may be an @code{END} statement, -or may be: - -@itemize @bullet -@item -An @code{END PROGRAM} statement, if the program unit is a main program. - -@item -An @code{END SUBROUTINE} statement, if the program unit is a subroutine. - -@item -An @code{END FUNCTION} statement, if the program unit is a function. - -@item -An @code{END BLOCK DATA} statement, if the program unit is a block data. -@end itemize - -@node INCLUDE -@subsection Including Source Text -@cindex INCLUDE directive - -Additional source text may be included in the processing of -the source file via the @code{INCLUDE} directive: - -@example -INCLUDE @var{filename} -@end example - -@noindent -The source text to be included is identified by @var{filename}, -which is a literal GNU Fortran character constant. -The meaning and interpretation of @var{filename} depends on the -implementation, but typically is a filename. - -(@code{g77} treats it as a filename that it searches for -in the current directory and/or directories specified -via the @samp{-I} command-line option.) - -The effect of the @code{INCLUDE} directive is as if the -included text directly replaced the directive in the source -file prior to interpretation of the program. -Included text may itself use @code{INCLUDE}. -The depth of nested @code{INCLUDE} references depends on -the implementation, but typically is a positive integer. - -This virtual replacement treats the statements and @code{INCLUDE} -directives in the included text as syntactically distinct from -those in the including text. - -Therefore, the first non-comment line of the included text -must not be a continuation line. -The included text must therefore have, after the non-comment -lines, either an initial line (statement), an @code{INCLUDE} -directive, or nothing (the end of the included text). - -Similarly, the including text may end the @code{INCLUDE} -directive with a semicolon or the end of the line, but it -cannot follow an @code{INCLUDE} directive at the end of its -line with a continuation line. -Thus, the last statement in an included text may not be -continued. - -Any statements between two @code{INCLUDE} directives on the -same line are treated as if they appeared in between the -respective included texts. -For example: - -@smallexample -INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM -@end smallexample - -@noindent -If the text included by @samp{INCLUDE 'A'} constitutes -a @samp{PRINT *, 'A'} statement and the text included by -@samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement, -then the output of the above sample program would be - -@example -A -B -C -@end example - -@noindent -(with suitable allowances for how an implementation defines -its handling of output). - -Included text must not include itself directly or indirectly, -regardless of whether the @var{filename} used to reference -the text is the same. - -Note that @code{INCLUDE} is @emph{not} a statement. -As such, it is neither a non-executable or executable -statement. -However, if the text it includes constitutes one or more -executable statements, then the placement of @code{INCLUDE} -is subject to effectively the same restrictions as those -on executable statements. - -An @code{INCLUDE} directive may be continued across multiple -lines as if it were a statement. -This permits long names to be used for @var{filename}. - -@node Cpp-style directives -@subsection Cpp-style directives -@cindex # -@cindex preprocessor - -@code{cpp} output-style @code{#} directives -(@pxref{C Preprocessor Output,,, cpp, The C Preprocessor}) -are recognized by the compiler even -when the preprocessor isn't run on the input (as it is when compiling -@samp{.F} files). (Note the distinction between these @code{cpp} -@code{#} @emph{output} directives and @code{#line} @emph{input} -directives.) - -@node Data Types and Constants -@section Data Types and Constants - -(The following information augments or overrides the information in -Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 4 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -To more concisely express the appropriate types for -entities, this document uses the more concise -Fortran 90 nomenclature such as @code{INTEGER(KIND=1)} -instead of the more traditional, but less portably concise, -byte-size-based nomenclature such as @code{INTEGER*4}, -wherever reasonable. - -When referring to generic types---in contexts where the -specific precision and range of a type are not important---this -document uses the generic type names @code{INTEGER}, @code{LOGICAL}, -@code{REAL}, @code{COMPLEX}, and @code{CHARACTER}. - -In some cases, the context requires specification of a -particular type. -This document uses the @samp{KIND=} notation to accomplish -this throughout, sometimes supplying the more traditional -notation for clarification, though the traditional notation -might not work the same way on all GNU Fortran implementations. - -Use of @samp{KIND=} makes this document more concise because -@code{g77} is able to define values for @samp{KIND=} that -have the same meanings on all systems, due to the way the -Fortran 90 standard specifies these values are to be used. - -(In particular, that standard permits an implementation to -arbitrarily assign nonnegative values. -There are four distinct sets of assignments: one to the @code{CHARACTER} -type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type; -and the fourth to both the @code{REAL} and @code{COMPLEX} types. -Implementations are free to assign these values in any order, -leave gaps in the ordering of assignments, and assign more than -one value to a representation.) - -This makes @samp{KIND=} values superior to the values used -in non-standard statements such as @samp{INTEGER*4}, because -the meanings of the values in those statements vary from machine -to machine, compiler to compiler, even operating system to -operating system. - -However, use of @samp{KIND=} is @emph{not} generally recommended -when writing portable code (unless, for example, the code is -going to be compiled only via @code{g77}, which is a widely -ported compiler). -GNU Fortran does not yet have adequate language constructs to -permit use of @samp{KIND=} in a fashion that would make the -code portable to Fortran 90 implementations; and, this construct -is known to @emph{not} be accepted by many popular FORTRAN 77 -implementations, so it cannot be used in code that is to be ported -to those. - -The distinction here is that this document is able to use -specific values for @samp{KIND=} to concisely document the -types of various operations and operands. - -A Fortran program should use the FORTRAN 77 designations for the -appropriate GNU Fortran types---such as @code{INTEGER} for -@code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)}, -and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and, -where no such designations exist, make use of appropriate -techniques (preprocessor macros, parameters, and so on) -to specify the types in a fashion that may be easily adjusted -to suit each particular implementation to which the program -is ported. -(These types generally won't need to be adjusted for ports of -@code{g77}.) - -Further details regarding GNU Fortran data types and constants -are provided below. - -@menu -* Types:: -* Constants:: -* Integer Type:: -* Character Type:: -@end menu - -@node Types -@subsection Data Types - -(Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.) - -GNU Fortran supports these types: - -@enumerate -@item -Integer (generic type @code{INTEGER}) - -@item -Real (generic type @code{REAL}) - -@item -Double precision - -@item -Complex (generic type @code{COMPLEX}) - -@item -Logical (generic type @code{LOGICAL}) - -@item -Character (generic type @code{CHARACTER}) - -@item -Double Complex -@end enumerate - -(The types numbered 1 through 6 above are standard FORTRAN 77 types.) - -The generic types shown above are referred to in this document -using only their generic type names. -Such references usually indicate that any specific type (kind) -of that generic type is valid. - -For example, a context described in this document as accepting -the @code{COMPLEX} type also is likely to accept the -@code{DOUBLE COMPLEX} type. - -The GNU Fortran language supports three ways to specify -a specific kind of a generic type. - -@menu -* Double Notation:: As in @code{DOUBLE COMPLEX}. -* Star Notation:: As in @code{INTEGER*4}. -* Kind Notation:: As in @code{INTEGER(KIND=1)}. -@end menu - -@node Double Notation -@subsubsection Double Notation - -The GNU Fortran language supports two uses of the keyword -@code{DOUBLE} to specify a specific kind of type: - -@itemize @bullet -@item -@code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)} - -@item -@code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)} -@end itemize - -Use one of the above forms where a type name is valid. - -While use of this notation is popular, it doesn't scale -well in a language or dialect rich in intrinsic types, -as is the case for the GNU Fortran language (especially -planned future versions of it). - -After all, one rarely sees type names such as @samp{DOUBLE INTEGER}, -@samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}. -Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1} -often are substituted for these, respectively, even though they -do not always have the same meanings on all systems. -(And, the fact that @samp{DOUBLE REAL} does not exist as such -is an inconsistency.) - -Therefore, this document uses ``double notation'' only on occasion -for the benefit of those readers who are accustomed to it. - -@node Star Notation -@subsubsection Star Notation -@cindex *@var{n} notation - -The following notation specifies the storage size for a type: - -@smallexample -@var{generic-type}*@var{n} -@end smallexample - -@noindent -@var{generic-type} must be a generic type---one of -@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, -or @code{CHARACTER}. -@var{n} must be one or more digits comprising a decimal -integer number greater than zero. - -Use the above form where a type name is valid. - -The @samp{*@var{n}} notation specifies that the amount of storage -occupied by variables and array elements of that type is @var{n} -times the storage occupied by a @code{CHARACTER*1} variable. - -This notation might indicate a different degree of precision and/or -range for such variables and array elements, and the functions that -return values of types using this notation. -It does not limit the precision or range of values of that type -in any particular way---use explicit code to do that. - -Further, the GNU Fortran language requires no particular values -for @var{n} to be supported by an implementation via the @samp{*@var{n}} -notation. -@code{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)}) -on all systems, for example, -but not all implementations are required to do so, and @code{g77} -is known to not support @code{REAL*1} on most (or all) systems. - -As a result, except for @var{generic-type} of @code{CHARACTER}, -uses of this notation should be limited to isolated -portions of a program that are intended to handle system-specific -tasks and are expected to be non-portable. - -(Standard FORTRAN 77 supports the @samp{*@var{n}} notation for -only @code{CHARACTER}, where it signifies not only the amount -of storage occupied, but the number of characters in entities -of that type. -However, almost all Fortran compilers have supported this -notation for generic types, though with a variety of meanings -for @var{n}.) - -Specifications of types using the @samp{*@var{n}} notation -always are interpreted as specifications of the appropriate -types described in this document using the @samp{KIND=@var{n}} -notation, described below. - -While use of this notation is popular, it doesn't serve well -in the context of a widely portable dialect of Fortran, such as -the GNU Fortran language. - -For example, even on one particular machine, two or more popular -Fortran compilers might well disagree on the size of a type -declared @code{INTEGER*2} or @code{REAL*16}. -Certainly there -is known to be disagreement over such things among Fortran -compilers on @emph{different} systems. - -Further, this notation offers no elegant way to specify sizes -that are not even multiples of the ``byte size'' typically -designated by @code{INTEGER*1}. -Use of ``absurd'' values (such as @code{INTEGER*1000}) would -certainly be possible, but would perhaps be stretching the original -intent of this notation beyond the breaking point in terms -of widespread readability of documentation and code making use -of it. - -Therefore, this document uses ``star notation'' only on occasion -for the benefit of those readers who are accustomed to it. - -@node Kind Notation -@subsubsection Kind Notation -@cindex KIND= notation - -The following notation specifies the kind-type selector of a type: - -@smallexample -@var{generic-type}(KIND=@var{n}) -@end smallexample - -@noindent -Use the above form where a type name is valid. - -@var{generic-type} must be a generic type---one of -@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, -or @code{CHARACTER}. -@var{n} must be an integer initialization expression that -is a positive, nonzero value. - -Programmers are discouraged from writing these values directly -into their code. -Future versions of the GNU Fortran language will offer -facilities that will make the writing of code portable -to @code{g77} @emph{and} Fortran 90 implementations simpler. - -However, writing code that ports to existing FORTRAN 77 -implementations depends on avoiding the @samp{KIND=} construct. - -The @samp{KIND=} construct is thus useful in the context -of GNU Fortran for two reasons: - -@itemize @bullet -@item -It provides a means to specify a type in a fashion that -is portable across all GNU Fortran implementations (though -not other FORTRAN 77 and Fortran 90 implementations). - -@item -It provides a sort of Rosetta stone for this document to use -to concisely describe the types of various operations and -operands. -@end itemize - -The values of @var{n} in the GNU Fortran language are -assigned using a scheme that: - -@itemize @bullet -@item -Attempts to maximize the ability of readers -of this document to quickly familiarize themselves -with assignments for popular types - -@item -Provides a unique value for each specific desired -meaning - -@item -Provides a means to automatically assign new values so -they have a ``natural'' relationship to existing values, -if appropriate, or, if no such relationship exists, will -not interfere with future values assigned on the basis -of such relationships - -@item -Avoids using values that are similar to values used -in the existing, popular @samp{*@var{n}} notation, -to prevent readers from expecting that these implied -correspondences work on all GNU Fortran implementations -@end itemize - -The assignment system accomplishes this by assigning -to each ``fundamental meaning'' of a specific type a -unique prime number. -Combinations of fundamental meanings---for example, a type -that is two times the size of some other type---are assigned -values of @var{n} that are the products of the values for -those fundamental meanings. - -A prime value of @var{n} is never given more than one fundamental -meaning, to avoid situations where some code or system -cannot reasonably provide those meanings in the form of a -single type. - -The values of @var{n} assigned so far are: - -@table @code -@item KIND=0 -This value is reserved for future use. - -The planned future use is for this value to designate, -explicitly, context-sensitive kind-type selection. -For example, the expression @samp{1D0 * 0.1_0} would -be equivalent to @samp{1D0 * 0.1D0}. - -@item KIND=1 -This corresponds to the default types for -@code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX}, -and @code{CHARACTER}, as appropriate. - -These are the ``default'' types described in the Fortran 90 standard, -though that standard does not assign any particular @samp{KIND=} -value to these types. - -(Typically, these are @code{REAL*4}, @code{INTEGER*4}, -@code{LOGICAL*4}, and @code{COMPLEX*8}.) - -@item KIND=2 -This corresponds to types that occupy twice as much -storage as the default types. -@code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}), -@code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}), - -These are the ``double precision'' types described in the Fortran 90 -standard, -though that standard does not assign any particular @samp{KIND=} -value to these types. - -@var{n} of 4 thus corresponds to types that occupy four times -as much storage as the default types, @var{n} of 8 to types that -occupy eight times as much storage, and so on. - -The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types -are not necessarily supported by every GNU Fortran implementation. - -@item KIND=3 -This corresponds to types that occupy as much -storage as the default @code{CHARACTER} type, -which is the same effective type as @code{CHARACTER(KIND=1)} -(making that type effectively the same as @code{CHARACTER(KIND=3)}). - -(Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.) - -@var{n} of 6 thus corresponds to types that occupy twice as -much storage as the @var{n}=3 types, @var{n} of 12 to types -that occupy four times as much storage, and so on. - -These are not necessarily supported by every GNU Fortran -implementation. - -@item KIND=5 -This corresponds to types that occupy half the -storage as the default (@var{n}=1) types. - -(Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.) - -@var{n} of 25 thus corresponds to types that occupy one-quarter -as much storage as the default types. - -These are not necessarily supported by every GNU Fortran -implementation. - -@item KIND=7 -@cindex pointers -This is valid only as @code{INTEGER(KIND=7)} and -denotes the @code{INTEGER} type that has the smallest -storage size that holds a pointer on the system. - -A pointer representable by this type is capable of uniquely -addressing a @code{CHARACTER*1} variable, array, array element, -or substring. - -(Typically this is equivalent to @code{INTEGER*4} or, -on 64-bit systems, @code{INTEGER*8}. -In a compatible C implementation, it typically would -be the same size and semantics of the C type @code{void *}.) -@end table - -Note that these are @emph{proposed} correspondences and might change -in future versions of @code{g77}---avoid writing code depending -on them while @code{g77}, and therefore the GNU Fortran language -it defines, is in beta testing. - -Values not specified in the above list are reserved to -future versions of the GNU Fortran language. - -Implementation-dependent meanings will be assigned new, -unique prime numbers so as to not interfere with other -implementation-dependent meanings, and offer the possibility -of increasing the portability of code depending on such -types by offering support for them in other GNU Fortran -implementations. - -Other meanings that might be given unique values are: - -@itemize @bullet -@item -Types that make use of only half their storage size for -representing precision and range. - -For example, some compilers offer options that cause -@code{INTEGER} types to occupy the amount of storage -that would be needed for @code{INTEGER(KIND=2)} types, but the -range remains that of @code{INTEGER(KIND=1)}. - -@item -The IEEE single floating-point type. - -@item -Types with a specific bit pattern (endianness), such as the -little-endian form of @code{INTEGER(KIND=1)}. -These could permit, conceptually, use of portable code and -implementations on data files written by existing systems. -@end itemize - -Future @emph{prime} numbers should be given meanings in as incremental -a fashion as possible, to allow for flexibility and -expressiveness in combining types. - -For example, instead of defining a prime number for little-endian -IEEE doubles, one prime number might be assigned the meaning -``little-endian'', another the meaning ``IEEE double'', and the -value of @var{n} for a little-endian IEEE double would thus -naturally be the product of those two respective assigned values. -(It could even be reasonable to have IEEE values result from the -products of prime values denoting exponent and fraction sizes -and meanings, hidden bit usage, availability and representations -of special values such as subnormals, infinities, and Not-A-Numbers -(NaNs), and so on.) - -This assignment mechanism, while not inherently required for -future versions of the GNU Fortran language, is worth using -because it could ease management of the ``space'' of supported -types much easier in the long run. - -The above approach suggests a mechanism for specifying inheritance -of intrinsic (built-in) types for an entire, widely portable -product line. -It is certainly reasonable that, unlike programmers of other languages -offering inheritance mechanisms that employ verbose names for classes -and subclasses, along with graphical browsers to elucidate the -relationships, Fortran programmers would employ -a mechanism that works by multiplying prime numbers together -and finding the prime factors of such products. - -Most of the advantages for the above scheme have been explained -above. -One disadvantage is that it could lead to the defining, -by the GNU Fortran language, of some fairly large prime numbers. -This could lead to the GNU Fortran language being declared -``munitions'' by the United States Department of Defense. - -@node Constants -@subsection Constants -@cindex constants -@cindex types, constants - -(Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.) - -A @dfn{typeless constant} has one of the following forms: - -@smallexample -'@var{binary-digits}'B -'@var{octal-digits}'O -'@var{hexadecimal-digits}'Z -'@var{hexadecimal-digits}'X -@end smallexample - -@noindent -@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} -are nonempty strings of characters in the set @samp{01}, @samp{01234567}, -and @samp{0123456789ABCDEFabcdef}, respectively. -(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} -is 11, and so on.) - -A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be -treated as typeless. @xref{Fortran Dialect Options,, Options -Controlling Fortran Dialect}, for information on the -@samp{-ftypeless-boz} option. - -Typeless constants have values that depend on the context in which -they are used. - -All other constants, called @dfn{typed constants}, are interpreted---converted -to internal form---according to their inherent type. -Thus, context is @emph{never} a determining factor for the type, and hence -the interpretation, of a typed constant. -(All constants in the ANSI FORTRAN 77 language are typed constants.) - -For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU -Fortran (called default INTEGER in Fortran 90), -@samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the -additional precision specified is lost, and even when used in a -@code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)}, -and @samp{1D0} is always type @code{REAL(KIND=2)}. - -@node Integer Type -@subsection Integer Type - -(Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.) - -An integer constant also may have one of the following forms: - -@smallexample -B'@var{binary-digits}' -O'@var{octal-digits}' -Z'@var{hexadecimal-digits}' -X'@var{hexadecimal-digits}' -@end smallexample - -@noindent -@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} -are nonempty strings of characters in the set @samp{01}, @samp{01234567}, -and @samp{0123456789ABCDEFabcdef}, respectively. -(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} -is 11, and so on.) - -@node Character Type -@subsection Character Type - -(Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.) - -@cindex double quoted character constants -A character constant may be delimited by a pair of double quotes -(@samp{"}) instead of apostrophes. -In this case, an apostrophe within the constant represents -a single apostrophe, while a double quote is represented in -the source text of the constant by two consecutive double -quotes with no intervening spaces. - -@cindex zero-length CHARACTER -@cindex null CHARACTER strings -@cindex empty CHARACTER strings -@cindex strings, empty -@cindex CHARACTER, null -A character constant may be empty (have a length of zero). - -A character constant may include a substring specification, -The value of such a constant is the value of the substring---for -example, the value of @samp{'hello'(3:5)} is the same -as the value of @samp{'llo'}. - -@node Expressions -@section Expressions - -(The following information augments or overrides the information in -Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 6 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* %LOC():: -@end menu - -@node %LOC() -@subsection The @code{%LOC()} Construct -@cindex %LOC() construct - -@example -%LOC(@var{arg}) -@end example - -The @code{%LOC()} construct is an expression -that yields the value of the location of its argument, -@var{arg}, in memory. -The size of the type of the expression depends on the system---typically, -it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)}, -though it is actually type @code{INTEGER(KIND=7)}. - -The argument to @code{%LOC()} must be suitable as the -left-hand side of an assignment statement. -That is, it may not be a general expression involving -operators such as addition, subtraction, and so on, -nor may it be a constant. - -Use of @code{%LOC()} is recommended only for code that -is accessing facilities outside of GNU Fortran, such as -operating system or windowing facilities. -It is best to constrain such uses to isolated portions of -a program---portions that deal specifically and exclusively -with low-level, system-dependent facilities. -Such portions might well provide a portable interface for -use by the program as a whole, but are themselves not -portable, and should be thoroughly tested each time they -are rebuilt using a new compiler or version of a compiler. - -Do not depend on @code{%LOC()} returning a pointer that -can be safely used to @emph{define} (change) the argument. -While this might work in some circumstances, it is hard -to predict whether it will continue to work when a program -(that works using this unsafe behavior) -is recompiled using different command-line options or -a different version of @code{g77}. - -Generally, @code{%LOC()} is safe when used as an argument -to a procedure that makes use of the value of the corresponding -dummy argument only during its activation, and only when -such use is restricted to referencing (reading) the value -of the argument to @code{%LOC()}. - -@emph{Implementation Note:} Currently, @code{g77} passes -arguments (those not passed using a construct such as @code{%VAL()}) -by reference or descriptor, depending on the type of -the actual argument. -Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would -seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and -in fact might compile to identical code. - -However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means -``pass, by value, the address of @samp{I} in memory''. -While @samp{CALL FOO(I)} might use that same approach in a -particular version of @code{g77}, another version or compiler -might choose a different implementation, such as copy-in/copy-out, -to effect the desired behavior---and which will therefore not -necessarily compile to the same code as would -@samp{CALL FOO(%VAL(%LOC(I)))} -using the same version or compiler. - -@xref{Debugging and Interfacing}, for detailed information on -how this particular version of @code{g77} implements various -constructs. - -@node Specification Statements -@section Specification Statements - -(The following information augments or overrides the information in -Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 8 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* NAMELIST:: -* DOUBLE COMPLEX:: -@end menu - -@node NAMELIST -@subsection @code{NAMELIST} Statement -@cindex NAMELIST statement -@cindex statements, NAMELIST - -The @code{NAMELIST} statement, and related I/O constructs, are -supported by the GNU Fortran language in essentially the same -way as they are by @code{f2c}. - -This follows Fortran 90 with the restriction that on @code{NAMELIST} -input, subscripts must have the form -@smallexample -@var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]] -@end smallexample -i.e.@: -@smallexample -&xx x(1:3,8:10:2)=1,2,3,4,5,6/ -@end smallexample -is allowed, but not, say, -@smallexample -&xx x(:3,8::2)=1,2,3,4,5,6/ -@end smallexample - -As an extension of the Fortran 90 form, @code{$} and @code{$END} may be -used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that -@smallexample -$&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end -@end smallexample -could be used instead of the example above. - -@node DOUBLE COMPLEX -@subsection @code{DOUBLE COMPLEX} Statement -@cindex DOUBLE COMPLEX - -@code{DOUBLE COMPLEX} is a type-statement (and type) that -specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran. - -@node Control Statements -@section Control Statements - -(The following information augments or overrides the information in -Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 11 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* DO WHILE:: -* END DO:: -* Construct Names:: -* CYCLE and EXIT:: -@end menu - -@node DO WHILE -@subsection DO WHILE -@cindex DO WHILE -@cindex DO -@cindex MIL-STD 1753 - -The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and -Fortran 90 standards, is provided by the GNU Fortran language. -The Fortran 90 ``do forever'' statement comprising just @code{DO} is -also supported. - -@node END DO -@subsection END DO -@cindex END DO -@cindex MIL-STD 1753 - -The @code{END DO} statement is provided by the GNU Fortran language. - -This statement is used in one of two ways: - -@itemize @bullet -@item -The Fortran 90 meaning, in which it specifies the termination -point of a single @code{DO} loop started with a @code{DO} statement -that specifies no termination label. - -@item -The MIL-STD 1753 meaning, in which it specifies the termination -point of one or more @code{DO} loops, all of which start with a -@code{DO} statement that specify the label defined for the -@code{END DO} statement. - -This kind of @code{END DO} statement is merely a synonym for -@code{CONTINUE}, except it is permitted only when the statement -is labeled and a target of one or more labeled @code{DO} loops. - -It is expected that this use of @code{END DO} will be removed from -the GNU Fortran language in the future, though it is likely that -it will long be supported by @code{g77} as a dialect form. -@end itemize - -@node Construct Names -@subsection Construct Names -@cindex construct names - -The GNU Fortran language supports construct names as defined -by the Fortran 90 standard. -These names are local to the program unit and are defined -as follows: - -@smallexample -@var{construct-name}: @var{block-statement} -@end smallexample - -@noindent -Here, @var{construct-name} is the construct name itself; -its definition is connoted by the single colon (@samp{:}); and -@var{block-statement} is an @code{IF}, @code{DO}, -or @code{SELECT CASE} statement that begins a block. - -A block that is given a construct name must also specify the -same construct name in its termination statement: - -@example -END @var{block} @var{construct-name} -@end example - -@noindent -Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT}, -as appropriate. - -@node CYCLE and EXIT -@subsection The @code{CYCLE} and @code{EXIT} Statements - -@cindex CYCLE statement -@cindex EXIT statement -@cindex statements, CYCLE -@cindex statements, EXIT -The @code{CYCLE} and @code{EXIT} statements specify that -the remaining statements in the current iteration of a -particular active (enclosing) @code{DO} loop are to be skipped. - -@code{CYCLE} specifies that these statements are skipped, -but the @code{END DO} statement that marks the end of the -@code{DO} loop be executed---that is, the next iteration, -if any, is to be started. -If the statement marking the end of the @code{DO} loop is -not @code{END DO}---in other words, if the loop is not -a block @code{DO}---the @code{CYCLE} statement does not -execute that statement, but does start the next iteration (if any). - -@code{EXIT} specifies that the loop specified by the -@code{DO} construct is terminated. - -The @code{DO} loop affected by @code{CYCLE} and @code{EXIT} -is the innermost enclosing @code{DO} loop when the following -forms are used: - -@example -CYCLE -EXIT -@end example - -Otherwise, the following forms specify the construct name -of the pertinent @code{DO} loop: - -@example -CYCLE @var{construct-name} -EXIT @var{construct-name} -@end example - -@code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO} -statements. -However, they cannot be easily thought of as @code{GO TO} statements -in obscure cases involving FORTRAN 77 loops. -For example: - -@smallexample - DO 10 I = 1, 5 - DO 10 J = 1, 5 - IF (J .EQ. 5) EXIT - DO 10 K = 1, 5 - IF (K .EQ. 3) CYCLE -10 PRINT *, 'I=', I, ' J=', J, ' K=', K -20 CONTINUE -@end smallexample - -@noindent -In particular, neither the @code{EXIT} nor @code{CYCLE} statements -above are equivalent to a @code{GO TO} statement to either label -@samp{10} or @samp{20}. - -To understand the effect of @code{CYCLE} and @code{EXIT} in the -above fragment, it is helpful to first translate it to its equivalent -using only block @code{DO} loops: - -@smallexample - DO I = 1, 5 - DO J = 1, 5 - IF (J .EQ. 5) EXIT - DO K = 1, 5 - IF (K .EQ. 3) CYCLE -10 PRINT *, 'I=', I, ' J=', J, ' K=', K - END DO - END DO - END DO -20 CONTINUE -@end smallexample - -Adding new labels allows translation of @code{CYCLE} and @code{EXIT} -to @code{GO TO} so they may be more easily understood by programmers -accustomed to FORTRAN coding: - -@smallexample - DO I = 1, 5 - DO J = 1, 5 - IF (J .EQ. 5) GOTO 18 - DO K = 1, 5 - IF (K .EQ. 3) GO TO 12 -10 PRINT *, 'I=', I, ' J=', J, ' K=', K -12 END DO - END DO -18 END DO -20 CONTINUE -@end smallexample - -@noindent -Thus, the @code{CYCLE} statement in the innermost loop skips over -the @code{PRINT} statement as it begins the next iteration of the -loop, while the @code{EXIT} statement in the middle loop ends that -loop but @emph{not} the outermost loop. - -@node Functions and Subroutines -@section Functions and Subroutines - -(The following information augments or overrides the information in -Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 15 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* %VAL():: -* %REF():: -* %DESCR():: -* Generics and Specifics:: -* REAL() and AIMAG() of Complex:: -* CMPLX() of DOUBLE PRECISION:: -* MIL-STD 1753:: -* f77/f2c Intrinsics:: -* Table of Intrinsic Functions:: -@end menu - -@node %VAL() -@subsection The @code{%VAL()} Construct -@cindex %VAL() construct - -@example -%VAL(@var{arg}) -@end example - -The @code{%VAL()} construct specifies that an argument, -@var{arg}, is to be passed by value, instead of by reference -or descriptor. - -@code{%VAL()} is restricted to actual arguments in -invocations of external procedures. - -Use of @code{%VAL()} is recommended only for code that -is accessing facilities outside of GNU Fortran, such as -operating system or windowing facilities. -It is best to constrain such uses to isolated portions of -a program---portions the deal specifically and exclusively -with low-level, system-dependent facilities. -Such portions might well provide a portable interface for -use by the program as a whole, but are themselves not -portable, and should be thoroughly tested each time they -are rebuilt using a new compiler or version of a compiler. - -@emph{Implementation Note:} Currently, @code{g77} passes -all arguments either by reference or by descriptor. - -Thus, use of @code{%VAL()} tends to be restricted to cases -where the called procedure is written in a language other -than Fortran that supports call-by-value semantics. -(C is an example of such a language.) - -@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, -for detailed information on -how this particular version of @code{g77} passes arguments -to procedures. - -@node %REF() -@subsection The @code{%REF()} Construct -@cindex %REF() construct - -@example -%REF(@var{arg}) -@end example - -The @code{%REF()} construct specifies that an argument, -@var{arg}, is to be passed by reference, instead of by -value or descriptor. - -@code{%REF()} is restricted to actual arguments in -invocations of external procedures. - -Use of @code{%REF()} is recommended only for code that -is accessing facilities outside of GNU Fortran, such as -operating system or windowing facilities. -It is best to constrain such uses to isolated portions of -a program---portions the deal specifically and exclusively -with low-level, system-dependent facilities. -Such portions might well provide a portable interface for -use by the program as a whole, but are themselves not -portable, and should be thoroughly tested each time they -are rebuilt using a new compiler or version of a compiler. - -Do not depend on @code{%REF()} supplying a pointer to the -procedure being invoked. -While that is a likely implementation choice, other -implementation choices are available that preserve Fortran -pass-by-reference semantics without passing a pointer to -the argument, @var{arg}. -(For example, a copy-in/copy-out implementation.) - -@emph{Implementation Note:} Currently, @code{g77} passes -all arguments -(other than variables and arrays of type @code{CHARACTER}) -by reference. -Future versions of, or dialects supported by, @code{g77} might -not pass @code{CHARACTER} functions by reference. - -Thus, use of @code{%REF()} tends to be restricted to cases -where @var{arg} is type @code{CHARACTER} but the called -procedure accesses it via a means other than the method -used for Fortran @code{CHARACTER} arguments. - -@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on -how this particular version of @code{g77} passes arguments -to procedures. - -@node %DESCR() -@subsection The @code{%DESCR()} Construct -@cindex %DESCR() construct - -@example -%DESCR(@var{arg}) -@end example - -The @code{%DESCR()} construct specifies that an argument, -@var{arg}, is to be passed by descriptor, instead of by -value or reference. - -@code{%DESCR()} is restricted to actual arguments in -invocations of external procedures. - -Use of @code{%DESCR()} is recommended only for code that -is accessing facilities outside of GNU Fortran, such as -operating system or windowing facilities. -It is best to constrain such uses to isolated portions of -a program---portions the deal specifically and exclusively -with low-level, system-dependent facilities. -Such portions might well provide a portable interface for -use by the program as a whole, but are themselves not -portable, and should be thoroughly tested each time they -are rebuilt using a new compiler or version of a compiler. - -Do not depend on @code{%DESCR()} supplying a pointer -and/or a length passed by value -to the procedure being invoked. -While that is a likely implementation choice, other -implementation choices are available that preserve the -pass-by-reference semantics without passing a pointer to -the argument, @var{arg}. -(For example, a copy-in/copy-out implementation.) -And, future versions of @code{g77} might change the -way descriptors are implemented, such as passing a -single argument pointing to a record containing the -pointer/length information instead of passing that same -information via two arguments as it currently does. - -@emph{Implementation Note:} Currently, @code{g77} passes -all variables and arrays of type @code{CHARACTER} -by descriptor. -Future versions of, or dialects supported by, @code{g77} might -pass @code{CHARACTER} functions by descriptor as well. - -Thus, use of @code{%DESCR()} tends to be restricted to cases -where @var{arg} is not type @code{CHARACTER} but the called -procedure accesses it via a means similar to the method -used for Fortran @code{CHARACTER} arguments. - -@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on -how this particular version of @code{g77} passes arguments -to procedures. - -@node Generics and Specifics -@subsection Generics and Specifics -@cindex generic intrinsics -@cindex intrinsics, generic - -The ANSI FORTRAN 77 language defines generic and specific -intrinsics. -In short, the distinctions are: - -@itemize @bullet -@item -@emph{Specific} intrinsics have -specific types for their arguments and a specific return -type. - -@item -@emph{Generic} intrinsics are treated, -on a case-by-case basis in the program's source code, -as one of several possible specific intrinsics. - -Typically, a generic intrinsic has a return type that -is determined by the type of one or more of its arguments. -@end itemize - -The GNU Fortran language generalizes these concepts somewhat, -especially by providing intrinsic subroutines and generic -intrinsics that are treated as either a specific intrinsic subroutine -or a specific intrinsic function (e.g. @code{SECOND}). - -However, GNU Fortran avoids generalizing this concept to -the point where existing code would be accepted as meaning -something possibly different than what was intended. - -For example, @code{ABS} is a generic intrinsic, so all working -code written using @code{ABS} of an @code{INTEGER} argument -expects an @code{INTEGER} return value. -Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2} -argument returns an @code{INTEGER*2} return value. - -Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only -an @code{INTEGER(KIND=1)} argument. -Code that passes something other than an @code{INTEGER(KIND=1)} -argument to @code{IABS} is not valid GNU Fortran code, because -it is not clear what the author intended. - -For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)} -is not defined by the GNU Fortran language, because the programmer -might have used that construct to mean any of the following, subtly -different, things: - -@itemize @bullet -@item -Convert @samp{J} to @code{INTEGER(KIND=1)} first -(as if @samp{IABS(INT(J))} had been written). - -@item -Convert the result of the intrinsic to @code{INTEGER(KIND=1)} -(as if @samp{INT(ABS(J))} had been written). - -@item -No conversion (as if @samp{ABS(J)} had been written). -@end itemize - -The distinctions matter especially when types and values wider than -@code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when -operations performing more ``arithmetic'' than absolute-value, are involved. - -The following sample program is not a valid GNU Fortran program, but -might be accepted by other compilers. -If so, the output is likely to be revealing in terms of how a given -compiler treats intrinsics (that normally are specific) when they -are given arguments that do not conform to their stated requirements: - -@cindex JCB002 program -@smallexample - PROGRAM JCB002 -C Version 1: -C Modified 1999-02-15 (Burley) to delete my email address. -C Modified 1997-05-21 (Burley) to accommodate compilers that implement -C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2. -C -C Version 0: -C Written by James Craig Burley 1997-02-20. -C -C Purpose: -C Determine how compilers handle non-standard IDIM -C on INTEGER*2 operands, which presumably can be -C extrapolated into understanding how the compiler -C generally treats specific intrinsics that are passed -C arguments not of the correct types. -C -C If your compiler implements INTEGER*2 and INTEGER -C as the same type, change all INTEGER*2 below to -C INTEGER*1. -C - INTEGER*2 I0, I4 - INTEGER I1, I2, I3 - INTEGER*2 ISMALL, ILARGE - INTEGER*2 ITOOLG, ITWO - INTEGER*2 ITMP - LOGICAL L2, L3, L4 -C -C Find smallest INTEGER*2 number. -C - ISMALL=0 - 10 I0 = ISMALL-1 - IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20 - ISMALL = I0 - GOTO 10 - 20 CONTINUE -C -C Find largest INTEGER*2 number. -C - ILARGE=0 - 30 I0 = ILARGE+1 - IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40 - ILARGE = I0 - GOTO 30 - 40 CONTINUE -C -C Multiplying by two adds stress to the situation. -C - ITWO = 2 -C -C Need a number that, added to -2, is too wide to fit in I*2. -C - ITOOLG = ISMALL -C -C Use IDIM the straightforward way. -C - I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG -C -C Calculate result for first interpretation. -C - I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG -C -C Calculate result for second interpretation. -C - ITMP = ILARGE - ISMALL - I3 = (INT (ITMP)) * ITWO + ITOOLG -C -C Calculate result for third interpretation. -C - I4 = (ILARGE - ISMALL) * ITWO + ITOOLG -C -C Print results. -C - PRINT *, 'ILARGE=', ILARGE - PRINT *, 'ITWO=', ITWO - PRINT *, 'ITOOLG=', ITOOLG - PRINT *, 'ISMALL=', ISMALL - PRINT *, 'I1=', I1 - PRINT *, 'I2=', I2 - PRINT *, 'I3=', I3 - PRINT *, 'I4=', I4 - PRINT * - L2 = (I1 .EQ. I2) - L3 = (I1 .EQ. I3) - L4 = (I1 .EQ. I4) - IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN - PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))' - STOP - END IF - IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN - PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))' - STOP - END IF - IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN - PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)' - STOP - END IF - PRINT *, 'Results need careful analysis.' - END -@end smallexample - -No future version of the GNU Fortran language -will likely permit specific intrinsic invocations with wrong-typed -arguments (such as @code{IDIM} in the above example), since -it has been determined that disagreements exist among -many production compilers on the interpretation of -such invocations. -These disagreements strongly suggest that Fortran programmers, -and certainly existing Fortran programs, disagree about the -meaning of such invocations. - -The first version of @code{JCB002} didn't accommodate some compilers' -treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are -@code{INTEGER*2}. -In such a case, these compilers apparently convert both -operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction, -instead of doing an @code{INTEGER*2} subtraction on the -original values in @samp{I1} and @samp{I2}. - -However, the results of the careful analyses done on the outputs -of programs compiled by these various compilers show that they -all implement either @samp{Interp 1} or @samp{Interp 2} above. - -Specifically, it is believed that the new version of @code{JCB002} -above will confirm that: - -@itemize @bullet -@item -Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5 -@code{f77} compilers all implement @samp{Interp 1}. - -@item -IRIX 5.3 @code{f77} compiler implements @samp{Interp 2}. - -@item -Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3, -and IRIX 6.1 @code{f77} compilers all implement @samp{Interp 3}. -@end itemize - -If you get different results than the above for the stated -compilers, or have results for other compilers that might be -worth adding to the above list, please let us know the details -(compiler product, version, machine, results, and so on). - -@node REAL() and AIMAG() of Complex -@subsection @code{REAL()} and @code{AIMAG()} of Complex -@cindex @code{Real} intrinsic -@cindex intrinsics, @code{Real} -@cindex @code{AImag} intrinsic -@cindex intrinsics, @code{AImag} - -The GNU Fortran language disallows @code{REAL(@var{expr})} -and @code{AIMAG(@var{expr})}, -where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}, -except when they are used in the following way: - -@example -REAL(REAL(@var{expr})) -REAL(AIMAG(@var{expr})) -@end example - -@noindent -The above forms explicitly specify that the desired effect -is to convert the real or imaginary part of @var{expr}, which might -be some @code{REAL} type other than @code{REAL(KIND=1)}, -to type @code{REAL(KIND=1)}, -and have that serve as the value of the expression. - -The GNU Fortran language offers clearly named intrinsics to extract the -real and imaginary parts of a complex entity without any -conversion: - -@example -REALPART(@var{expr}) -IMAGPART(@var{expr}) -@end example - -To express the above using typical extended FORTRAN 77, -use the following constructs -(when @var{expr} is @code{COMPLEX(KIND=2)}): - -@example -DBLE(@var{expr}) -DIMAG(@var{expr}) -@end example - -The FORTRAN 77 language offers no way -to explicitly specify the real and imaginary parts of a complex expression of -arbitrary type, apparently as a result of requiring support for -only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}). -The concepts of converting an expression to type @code{REAL(KIND=1)} and -of extracting the real part of a complex expression were -thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since -they happened to have the exact same effect in that language -(due to having only one @code{COMPLEX} type). - -@emph{Note:} When @samp{-ff90} is in effect, -@code{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of -type @code{COMPLEX}, as @samp{REALPART(@var{expr})}, -whereas with @samp{-fugly-complex -fno-f90} in effect, it is -treated as @samp{REAL(REALPART(@var{expr}))}. - -@xref{Ugly Complex Part Extraction}, for more information. - -@node CMPLX() of DOUBLE PRECISION -@subsection @code{CMPLX()} of @code{DOUBLE PRECISION} -@cindex @code{Cmplx} intrinsic -@cindex intrinsics, @code{Cmplx} - -In accordance with Fortran 90 and at least some (perhaps all) -other compilers, the GNU Fortran language defines @code{CMPLX()} -as always returning a result that is type @code{COMPLEX(KIND=1)}. - -This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2} -are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as: - -@example -CMPLX(SNGL(D1), SNGL(D2)) -@end example - -(It was necessary for Fortran 90 to specify this behavior -for @code{DOUBLE PRECISION} arguments, since that is -the behavior mandated by FORTRAN 77.) - -The GNU Fortran language also provides the @code{DCMPLX()} intrinsic, -which is provided by some FORTRAN 77 compilers to construct -a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION} -operands. -However, this solution does not scale well when more @code{COMPLEX} types -(having various precisions and ranges) are offered by Fortran implementations. - -Fortran 90 extends the @code{CMPLX()} intrinsic by adding -an extra argument used to specify the desired kind of complex -result. -However, this solution is somewhat awkward to use, and -@code{g77} currently does not support it. - -The GNU Fortran language provides a simple way to build a complex -value out of two numbers, with the precise type of the value -determined by the types of the two numbers (via the usual -type-promotion mechanism): - -@example -COMPLEX(@var{real}, @var{imag}) -@end example - -When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()} -performs no conversion other than to put them together to form a -complex result of the same (complex version of real) type. - -@xref{Complex Intrinsic}, for more information. - -@node MIL-STD 1753 -@subsection MIL-STD 1753 Support -@cindex MIL-STD 1753 - -The GNU Fortran language includes the MIL-STD 1753 intrinsics -@code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS}, -@code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT}, -@code{ISHFTC}, @code{MVBITS}, and @code{NOT}. - -@node f77/f2c Intrinsics -@subsection @code{f77}/@code{f2c} Intrinsics - -The bit-manipulation intrinsics supported by traditional -@code{f77} and by @code{f2c} are available in the GNU Fortran language. -These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT}, -and @code{XOR}. - -Also supported are the intrinsics @code{CDABS}, -@code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN}, -@code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT}, -@code{DIMAG}, @code{DREAL}, and @code{IMAG}, -@code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN}, -and @code{ZSQRT}. - -@node Table of Intrinsic Functions -@subsection Table of Intrinsic Functions -@cindex intrinsics, table of -@cindex table of intrinsics - -(Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.) - -The GNU Fortran language adds various functions, subroutines, types, -and arguments to the set of intrinsic functions in ANSI FORTRAN 77. -The complete set of intrinsics supported by the GNU Fortran language -is described below. - -Note that a name is not treated as that of an intrinsic if it is -specified in an @code{EXTERNAL} statement in the same program unit; -if a command-line option is used to disable the groups to which -the intrinsic belongs; or if the intrinsic is not named in an -@code{INTRINSIC} statement and a command-line option is used to -hide the groups to which the intrinsic belongs. - -So, it is recommended that any reference in a program unit to -an intrinsic procedure that is not a standard FORTRAN 77 -intrinsic be accompanied by an appropriate @code{INTRINSIC} -statement in that program unit. -This sort of defensive programming makes it more -likely that an implementation will issue a diagnostic rather -than generate incorrect code for such a reference. - -The terminology used below is based on that of the Fortran 90 -standard, so that the text may be more concise and accurate: - -@itemize @bullet -@item -@code{OPTIONAL} means the argument may be omitted. - -@item -@samp{A-1, A-2, @dots{}, A-n} means more than one argument -(generally named @samp{A}) may be specified. - -@item -@samp{scalar} means the argument must not be an array (must -be a variable or array element, or perhaps a constant if expressions -are permitted). - -@item -@samp{DIMENSION(4)} means the argument must be an array having 4 elements. - -@item -@code{INTENT(IN)} means the argument must be an expression -(such as a constant or a variable that is defined upon invocation -of the intrinsic). - -@item -@code{INTENT(OUT)} means the argument must be definable by the -invocation of the intrinsic (that is, must not be a constant nor -an expression involving operators other than array reference and -substring reference). - -@item -@code{INTENT(INOUT)} means the argument must be defined prior to, -and definable by, invocation of the intrinsic (a combination of -the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}. - -@item -@xref{Kind Notation}, for an explanation of @code{KIND}. -@end itemize - -@ifinfo -(Note that the empty lines appearing in the menu below -are not intentional---they result from a bug in the -GNU @code{makeinfo} program@dots{}a program that, if it -did not exist, would leave this document in far worse shape!) -@end ifinfo - -@c The actual documentation for intrinsics comes from -@c intdoc.texi, which in turn is automatically generated -@c from the internal g77 tables in intrin.def _and_ the -@c largely hand-written text in intdoc.h. So, if you want -@c to change or add to existing documentation on intrinsics, -@c you probably want to edit intdoc.h. -@c -@set familyF77 -@set familyGNU -@set familyASC -@set familyMIL -@set familyF90 -@clear familyVXT -@clear familyFVZ -@set familyF2C -@set familyF2U -@clear familyBADU77 -@include intdoc.texi - -@node Scope and Classes of Names -@section Scope and Classes of Symbolic Names -@cindex symbol names, scope and classes -@cindex scope - -(The following information augments or overrides the information in -Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran -language. -Chapter 18 of that document otherwise serves as the basis -for the relevant aspects of GNU Fortran.) - -@menu -* Underscores in Symbol Names:: -@end menu - -@node Underscores in Symbol Names -@subsection Underscores in Symbol Names -@cindex underscore - -Underscores (@samp{_}) are accepted in symbol names after the first -character (which must be a letter). - -@node I/O -@section I/O - -@cindex dollar sign -A dollar sign at the end of an output format specification suppresses -the newline at the end of the output. - -@cindex <> edit descriptor -@cindex edit descriptor, <> -Edit descriptors in @code{FORMAT} statements may contain compile-time -@code{INTEGER} constant expressions in angle brackets, such as -@smallexample -10 FORMAT (I<WIDTH>) -@end smallexample - -The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}. - -These Fortran 90 features are supported: -@itemize @bullet -@item -@cindex FORMAT descriptors -@cindex Z edit descriptor -@cindex edit descriptor, Z -@cindex O edit descriptor -@cindex edit descriptor, O -The @code{O} and @code{Z} edit descriptors are supported for I/O of -integers in octal and hexadecimal formats, respectively. -@item -The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if -@code{STATUS='SCRATCH'} is supplied. The @code{STATUS='REPLACE'} -specifier is supported. -@end itemize - -@node Fortran 90 Features -@section Fortran 90 Features -@cindex Fortran 90 -@cindex extensions, from Fortran 90 - -For convenience this section collects a list (probably incomplete) of -the Fortran 90 features supported by the GNU Fortran language, even if -they are documented elsewhere. -@xref{Characters Lines Sequence,,@asis{Characters, Lines, and Execution Sequence}}, -for information on additional fixed source form lexical issues. -@cindex @samp{-ffree-form} -Further, the free source form is supported through the -@samp{-ffree-form} option. -@cindex @samp{-ff90} -Other Fortran 90 features can be turned on by the @samp{-ff90} option; -see @ref{Fortran 90}. -For information on the Fortran 90 intrinsics available, -see @ref{Table of Intrinsic Functions}. - -@table @asis -@item Automatic arrays in procedures -@item Character assignments -@cindex character assignments -In character assignments, the variable being assigned may occur on the -right hand side of the assignment. -@item Character strings -@cindex double quoted character constants -Strings may have zero length and substrings of character constants are -permitted. Character constants may be enclosed in double quotes -(@code{"}) as well as single quotes. @xref{Character Type}. -@item Construct names -(Symbolic tags on blocks.) @xref{Construct Names}. -@item @code{CYCLE} and @code{EXIT} -@xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}. -@item @code{DOUBLE COMPLEX} -@xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement}. -@item @code{DO WHILE} -@xref{DO WHILE}. -@item @code{END} decoration -@xref{Statements}. -@item @code{END DO} -@xref{END DO}. -@item @code{KIND} -@item @code{IMPLICIT NONE} -@item @code{INCLUDE} statements -@xref{INCLUDE}. -@item List-directed and namelist I/O on internal files -@item Binary, octal and hexadecimal constants -These are supported more generally than required by Fortran 90. -@xref{Integer Type}. -@item @samp{O} and @samp{Z} edit descriptors -@item @code{NAMELIST} -@xref{NAMELIST}. -@item @code{OPEN} specifiers -@code{STATUS='REPLACE'} is supported. -The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if -@code{STATUS='SCRATCH'} is supplied. -@item @code{FORMAT} edit descriptors -@cindex FORMAT descriptors -@cindex Z edit descriptor -@cindex edit descriptor, Z -The @code{Z} edit descriptor is supported. -@item Relational operators -The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and -@code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.}, -@code{.NE.}, @code{.GT.} and @code{.GE.} respectively. -@item @code{SELECT CASE} -Not fully implemented. -@xref{SELECT CASE on CHARACTER Type,, @code{SELECT CASE} on @code{CHARACTER} Type}. -@item Specification statements -A limited subset of the Fortran 90 syntax and semantics for variable -declarations is supported, including @code{KIND}. @xref{Kind Notation}. -(@code{KIND} is of limited usefulness in the absence of the -@code{KIND}-related intrinsics, since these intrinsics permit writing -more widely portable code.) An example of supported @code{KIND} usage -is: -@smallexample -INTEGER (KIND=1) :: FOO=1, BAR=2 -CHARACTER (LEN=3) FOO -@end smallexample -@code{PARAMETER} and @code{DIMENSION} attributes aren't supported. -@end table - -@node Other Dialects -@chapter Other Dialects - -GNU Fortran supports a variety of features that are not -considered part of the GNU Fortran language itself, but -are representative of various dialects of Fortran that -@code{g77} supports in whole or in part. - -Any of the features listed below might be disallowed by -@code{g77} unless some command-line option is specified. -Currently, some of the features are accepted using the -default invocation of @code{g77}, but that might change -in the future. - -@emph{Note: This portion of the documentation definitely needs a lot -of work!} - -@menu -* Source Form:: Details of fixed-form and free-form source. -* Trailing Comment:: Use of @samp{/*} to start a comment. -* Debug Line:: Use of @samp{D} in column 1. -* Dollar Signs:: Use of @samp{$} in symbolic names. -* Case Sensitivity:: Uppercase and lowercase in source files. -* VXT Fortran:: @dots{}versus the GNU Fortran language. -* Fortran 90:: @dots{}versus the GNU Fortran language. -* Pedantic Compilation:: Enforcing the standard. -* Distensions:: Misfeatures supported by GNU Fortran. -@end menu - -@node Source Form -@section Source Form -@cindex source file format -@cindex source format -@cindex file, source -@cindex source code -@cindex code, source -@cindex fixed form -@cindex free form - -GNU Fortran accepts programs written in either fixed form or -free form. - -Fixed form -corresponds to ANSI FORTRAN 77 (plus popular extensions, such as -allowing tabs) and Fortran 90's fixed form. - -Free form corresponds to -Fortran 90's free form (though possibly not entirely up-to-date, and -without complaining about some things that for which Fortran 90 requires -diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}). - -The way a Fortran compiler views source files depends entirely on the -implementation choices made for the compiler, since those choices -are explicitly left to the implementation by the published Fortran -standards. -GNU Fortran currently tries to be somewhat like a few popular compilers -(@code{f2c}, Digital (``DEC'') Fortran, and so on), though a cleaner default -definition along with more -flexibility offered by command-line options is likely to be offered -in version 0.6. - -This section describes how @code{g77} interprets source lines. - -@menu -* Carriage Returns:: Carriage returns ignored. -* Tabs:: Tabs converted to spaces. -* Short Lines:: Short lines padded with spaces (fixed-form only). -* Long Lines:: Long lines truncated. -* Ampersands:: Special Continuation Lines. -@end menu - -@node Carriage Returns -@subsection Carriage Returns -@cindex carriage returns - -Carriage returns (@samp{\r}) in source lines are ignored. -This is somewhat different from @code{f2c}, which seems to treat them as -spaces outside character/Hollerith constants, and encodes them as @samp{\r} -inside such constants. - -@node Tabs -@subsection Tabs -@cindex tab character -@cindex horizontal tab - -A source line with a @key{TAB} character anywhere in it is treated as -entirely significant---however long it is---instead of ending in -column 72 (for fixed-form source) or 132 (for free-form source). -This also is different from @code{f2c}, which encodes tabs as -@samp{\t} (the ASCII @key{TAB} character) inside character -and Hollerith constants, but nevertheless seems to treat the column -position as if it had been affected by the canonical tab positioning. - -@code{g77} effectively -translates tabs to the appropriate number of spaces (a la the default -for the UNIX @code{expand} command) before doing any other processing, other -than (currently) noting whether a tab was found on a line and using this -information to decide how to interpret the length of the line and continued -constants. - -Note that this default behavior probably will change for version 0.6, -when it will presumably be available via a command-line option. -The default as of version 0.6 is planned to be a ``pure visual'' -model, where tabs are immediately -converted to spaces and otherwise have no effect, so the way a typical -user sees source lines produces a consistent result no matter how the -spacing in those source lines is actually implemented via tabs, spaces, -and trailing tabs/spaces before newline. -Command-line options are likely to be added to specify whether all or -just-tabbed lines are to be extended to 132 or full input-line length, -and perhaps even an option will be added to specify the truncated-line -behavior to which some Digital compilers default (and which affects -the way continued character/Hollerith constants are interpreted). - -@node Short Lines -@subsection Short Lines -@cindex short source lines -@cindex space, padding with -@cindex source lines, short -@cindex lines, short - -Source lines shorter than the applicable fixed-form length are treated as -if they were padded with spaces to that length. -(None of this is relevant to source files written in free form.) - -This affects only -continued character and Hollerith constants, and is a different -interpretation than provided by some other popular compilers -(although a bit more consistent with the traditional punched-card -basis of Fortran and the way the Fortran standard expressed fixed -source form). - -@code{g77} might someday offer an option to warn about cases where differences -might be seen as a result of this treatment, and perhaps an option to -specify the alternate behavior as well. - -Note that this padding cannot apply to lines that are effectively of -infinite length---such lines are specified using command-line options -like @samp{-ffixed-line-length-none}, for example. - -@node Long Lines -@subsection Long Lines -@cindex long source lines -@cindex truncation, of long lines -@cindex lines, long -@cindex source lines, long - -Source lines longer than the applicable length are truncated to that -length. -Currently, @code{g77} does not warn if the truncated characters are -not spaces, to accommodate existing code written for systems that -treated truncated text as commentary (especially in columns 73 through 80). - -@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}, -for information on the @samp{-ffixed-line-length-@var{n}} option, -which can be used to set the line length applicable to fixed-form -source files. - -@node Ampersands -@subsection Ampersand Continuation Line -@cindex ampersand continuation line -@cindex continuation line, ampersand - -A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length -continuation line, imitating the behavior of @code{f2c}. - -@node Trailing Comment -@section Trailing Comment - -@cindex trailing comment -@cindex comment -@cindex characters, comment -@cindex /* -@cindex ! -@cindex exclamation point -@code{g77} supports use of @samp{/*} to start a trailing -comment. -In the GNU Fortran language, @samp{!} is used for this purpose. - -@samp{/*} is not in the GNU Fortran language -because the use of @samp{/*} in a program might -suggest to some readers that a block, not trailing, comment is -started (and thus ended by @samp{*/}, not end of line), -since that is the meaning of @samp{/*} in C. - -Also, such readers might think they can use @samp{//} to start -a trailing comment as an alternative to @samp{/*}, but -@samp{//} already denotes concatenation, and such a ``comment'' -might actually result in a program that compiles without -error (though it would likely behave incorrectly). - -@node Debug Line -@section Debug Line -@cindex debug line -@cindex comment line, debug - -Use of @samp{D} or @samp{d} as the first character (column 1) of -a source line denotes a debug line. - -In turn, a debug line is treated as either a comment line -or a normal line, depending on whether debug lines are enabled. - -When treated as a comment line, a line beginning with @samp{D} or -@samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively. -When treated as a normal line, such a line is treated as if -the first character was @key{SPC} (space). - -(Currently, @code{g77} provides no means for treating debug -lines as normal lines.) - -@node Dollar Signs -@section Dollar Signs in Symbol Names -@cindex dollar sign -@cindex $ - -Dollar signs (@samp{$}) are allowed in symbol names (after the first character) -when the @samp{-fdollar-ok} option is specified. - -@node Case Sensitivity -@section Case Sensitivity -@cindex case sensitivity -@cindex source file format -@cindex code, source -@cindex source code -@cindex uppercase letters -@cindex lowercase letters -@cindex letters, uppercase -@cindex letters, lowercase - -GNU Fortran offers the programmer way too much flexibility in deciding -how source files are to be treated vis-a-vis uppercase and lowercase -characters. -There are 66 useful settings that affect case sensitivity, plus 10 -settings that are nearly useless, with the remaining 116 settings -being either redundant or useless. - -None of these settings have any effect on the contents of comments -(the text after a @samp{c} or @samp{C} in Column 1, for example) -or of character or Hollerith constants. -Note that things like the @samp{E} in the statement -@samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB} -are considered built-in keywords, and so are affected by -these settings. - -Low-level switches are identified in this section as follows: - -@itemize @w{} -@item A -Source Case Conversion: - -@itemize @w{} -@item 0 -Preserve (see Note 1) -@item 1 -Convert to Upper Case -@item 2 -Convert to Lower Case -@end itemize - -@item B -Built-in Keyword Matching: - -@itemize @w{} -@item 0 -Match Any Case (per-character basis) -@item 1 -Match Upper Case Only -@item 2 -Match Lower Case Only -@item 3 -Match InitialCaps Only (see tables for spellings) -@end itemize - -@item C -Built-in Intrinsic Matching: - -@itemize @w{} -@item 0 -Match Any Case (per-character basis) -@item 1 -Match Upper Case Only -@item 2 -Match Lower Case Only -@item 3 -Match InitialCaps Only (see tables for spellings) -@end itemize - -@item D -User-defined Symbol Possibilities (warnings only): - -@itemize @w{} -@item 0 -Allow Any Case (per-character basis) -@item 1 -Allow Upper Case Only -@item 2 -Allow Lower Case Only -@item 3 -Allow InitialCaps Only (see Note 2) -@end itemize -@end itemize - -Note 1: @code{g77} eventually will support @code{NAMELIST} in a manner that is -consistent with these source switches---in the sense that input will be -expected to meet the same requirements as source code in terms -of matching symbol names and keywords (for the exponent letters). - -Currently, however, @code{NAMELIST} is supported by @code{libg2c}, -which uppercases @code{NAMELIST} input and symbol names for matching. -This means not only that @code{NAMELIST} output currently shows symbol -(and keyword) names in uppercase even if lower-case source -conversion (option A2) is selected, but that @code{NAMELIST} cannot be -adequately supported when source case preservation (option A0) -is selected. - -If A0 is selected, a warning message will be -output for each @code{NAMELIST} statement to this effect. -The behavior -of the program is undefined at run time if two or more symbol names -appear in a given @code{NAMELIST} such that the names are identical -when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}). -For complete and total elegance, perhaps there should be a warning -when option A2 is selected, since the output of NAMELIST is currently -in uppercase but will someday be lowercase (when a @code{libg77} is written), -but that seems to be overkill for a product in beta test. - -Note 2: Rules for InitialCaps names are: - -@itemize @minus -@item -Must be a single uppercase letter, @strong{or} -@item -Must start with an uppercase letter and contain at least one -lowercase letter. -@end itemize - -So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are -valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are -not. -Note that most, but not all, built-in names meet these -requirements---the exceptions are some of the two-letter format -specifiers, such as @code{BN} and @code{BZ}. - -Here are the names of the corresponding command-line options: - -@smallexample -A0: -fsource-case-preserve -A1: -fsource-case-upper -A2: -fsource-case-lower - -B0: -fmatch-case-any -B1: -fmatch-case-upper -B2: -fmatch-case-lower -B3: -fmatch-case-initcap - -C0: -fintrin-case-any -C1: -fintrin-case-upper -C2: -fintrin-case-lower -C3: -fintrin-case-initcap - -D0: -fsymbol-case-any -D1: -fsymbol-case-upper -D2: -fsymbol-case-lower -D3: -fsymbol-case-initcap -@end smallexample - -Useful combinations of the above settings, along with abbreviated -option names that set some of these combinations all at once: - -@smallexample - 1: A0-- B0--- C0--- D0--- -fcase-preserve - 2: A0-- B0--- C0--- D-1-- - 3: A0-- B0--- C0--- D--2- - 4: A0-- B0--- C0--- D---3 - 5: A0-- B0--- C-1-- D0--- - 6: A0-- B0--- C-1-- D-1-- - 7: A0-- B0--- C-1-- D--2- - 8: A0-- B0--- C-1-- D---3 - 9: A0-- B0--- C--2- D0--- -10: A0-- B0--- C--2- D-1-- -11: A0-- B0--- C--2- D--2- -12: A0-- B0--- C--2- D---3 -13: A0-- B0--- C---3 D0--- -14: A0-- B0--- C---3 D-1-- -15: A0-- B0--- C---3 D--2- -16: A0-- B0--- C---3 D---3 -17: A0-- B-1-- C0--- D0--- -18: A0-- B-1-- C0--- D-1-- -19: A0-- B-1-- C0--- D--2- -20: A0-- B-1-- C0--- D---3 -21: A0-- B-1-- C-1-- D0--- -22: A0-- B-1-- C-1-- D-1-- -fcase-strict-upper -23: A0-- B-1-- C-1-- D--2- -24: A0-- B-1-- C-1-- D---3 -25: A0-- B-1-- C--2- D0--- -26: A0-- B-1-- C--2- D-1-- -27: A0-- B-1-- C--2- D--2- -28: A0-- B-1-- C--2- D---3 -29: A0-- B-1-- C---3 D0--- -30: A0-- B-1-- C---3 D-1-- -31: A0-- B-1-- C---3 D--2- -32: A0-- B-1-- C---3 D---3 -33: A0-- B--2- C0--- D0--- -34: A0-- B--2- C0--- D-1-- -35: A0-- B--2- C0--- D--2- -36: A0-- B--2- C0--- D---3 -37: A0-- B--2- C-1-- D0--- -38: A0-- B--2- C-1-- D-1-- -39: A0-- B--2- C-1-- D--2- -40: A0-- B--2- C-1-- D---3 -41: A0-- B--2- C--2- D0--- -42: A0-- B--2- C--2- D-1-- -43: A0-- B--2- C--2- D--2- -fcase-strict-lower -44: A0-- B--2- C--2- D---3 -45: A0-- B--2- C---3 D0--- -46: A0-- B--2- C---3 D-1-- -47: A0-- B--2- C---3 D--2- -48: A0-- B--2- C---3 D---3 -49: A0-- B---3 C0--- D0--- -50: A0-- B---3 C0--- D-1-- -51: A0-- B---3 C0--- D--2- -52: A0-- B---3 C0--- D---3 -53: A0-- B---3 C-1-- D0--- -54: A0-- B---3 C-1-- D-1-- -55: A0-- B---3 C-1-- D--2- -56: A0-- B---3 C-1-- D---3 -57: A0-- B---3 C--2- D0--- -58: A0-- B---3 C--2- D-1-- -59: A0-- B---3 C--2- D--2- -60: A0-- B---3 C--2- D---3 -61: A0-- B---3 C---3 D0--- -62: A0-- B---3 C---3 D-1-- -63: A0-- B---3 C---3 D--2- -64: A0-- B---3 C---3 D---3 -fcase-initcap -65: A-1- B01-- C01-- D01-- -fcase-upper -66: A--2 B0-2- C0-2- D0-2- -fcase-lower -@end smallexample - -Number 22 is the ``strict'' ANSI FORTRAN 77 model wherein all input -(except comments, character constants, and Hollerith strings) must -be entered in uppercase. -Use @samp{-fcase-strict-upper} to specify this -combination. - -Number 43 is like Number 22 except all input must be lowercase. Use -@samp{-fcase-strict-lower} to specify this combination. - -Number 65 is the ``classic'' ANSI FORTRAN 77 model as implemented on many -non-UNIX machines whereby all the source is translated to uppercase. -Use @samp{-fcase-upper} to specify this combination. - -Number 66 is the ``canonical'' UNIX model whereby all the source is -translated to lowercase. -Use @samp{-fcase-lower} to specify this combination. - -There are a few nearly useless combinations: - -@smallexample -67: A-1- B01-- C01-- D--2- -68: A-1- B01-- C01-- D---3 -69: A-1- B01-- C--23 D01-- -70: A-1- B01-- C--23 D--2- -71: A-1- B01-- C--23 D---3 -72: A--2 B01-- C0-2- D-1-- -73: A--2 B01-- C0-2- D---3 -74: A--2 B01-- C-1-3 D0-2- -75: A--2 B01-- C-1-3 D-1-- -76: A--2 B01-- C-1-3 D---3 -@end smallexample - -The above allow some programs to be compiled but with restrictions that -make most useful programs impossible: Numbers 67 and 72 warn about -@emph{any} user-defined symbol names (such as @samp{SUBROUTINE FOO}); -Numbers -68 and 73 warn about any user-defined symbol names longer than one -character that don't have at least one non-alphabetic character after -the first; -Numbers 69 and 74 disallow any references to intrinsics; -and Numbers 70, 71, 75, and 76 are combinations of the restrictions in -67+69, 68+69, 72+74, and 73+74, respectively. - -All redundant combinations are shown in the above tables anyplace -where more than one setting is shown for a low-level switch. -For example, @samp{B0-2-} means either setting 0 or 2 is valid for switch B. -The ``proper'' setting in such a case is the one that copies the setting -of switch A---any other setting might slightly reduce the speed of -the compiler, though possibly to an unmeasurable extent. - -All remaining combinations are useless in that they prevent successful -compilation of non-null source files (source files with something other -than comments). - -@node VXT Fortran -@section VXT Fortran - -@cindex VXT extensions -@cindex extensions, VXT -@code{g77} supports certain constructs that -have different meanings in VXT Fortran than they -do in the GNU Fortran language. - -Generally, this manual uses the invented term VXT Fortran to refer -VAX FORTRAN (circa v4). -That compiler offered many popular features, though not necessarily -those that are specific to the VAX processor architecture, -the VMS operating system, -or Digital Equipment Corporation's Fortran product line. -(VAX and VMS probably are trademarks of Digital Equipment -Corporation.) - -An extension offered by a Digital Fortran product that also is -offered by several other Fortran products for different kinds of -systems is probably going to be considered for inclusion in @code{g77} -someday, and is considered a VXT Fortran feature. - -The @samp{-fvxt} option generally specifies that, where -the meaning of a construct is ambiguous (means one thing -in GNU Fortran and another in VXT Fortran), the VXT Fortran -meaning is to be assumed. - -@menu -* Double Quote Meaning:: @samp{"2000} as octal constant. -* Exclamation Point:: @samp{!} in column 6. -@end menu - -@node Double Quote Meaning -@subsection Meaning of Double Quote -@cindex double quotes -@cindex character constants -@cindex constants, character -@cindex octal constants -@cindex constants, octal - -@code{g77} treats double-quote (@samp{"}) -as beginning an octal constant of @code{INTEGER(KIND=1)} type -when the @samp{-fvxt} option is specified. -The form of this octal constant is - -@example -"@var{octal-digits} -@end example - -@noindent -where @var{octal-digits} is a nonempty string of characters in -the set @samp{01234567}. - -For example, the @samp{-fvxt} option permits this: - -@example -PRINT *, "20 -END -@end example - -@noindent -The above program would print the value @samp{16}. - -@xref{Integer Type}, for information on the preferred construct -for integer constants specified using GNU Fortran's octal notation. - -(In the GNU Fortran language, the double-quote character (@samp{"}) -delimits a character constant just as does apostrophe (@samp{'}). -There is no way to allow -both constructs in the general case, since statements like -@samp{PRINT *,"2000 !comment?"} would be ambiguous.) - -@node Exclamation Point -@subsection Meaning of Exclamation Point in Column 6 -@cindex ! -@cindex exclamation point -@cindex continuation character -@cindex characters, continuation -@cindex comment character -@cindex characters, comment - -@code{g77} treats an exclamation point (@samp{!}) in column 6 of -a fixed-form source file -as a continuation character rather than -as the beginning of a comment -(as it does in any other column) -when the @samp{-fvxt} option is specified. - -The following program, when run, prints a message indicating -whether it is interpreted according to GNU Fortran (and Fortran 90) -rules or VXT Fortran rules: - -@smallexample -C234567 (This line begins in column 1.) - I = 0 - !1 - IF (I.EQ.0) PRINT *, ' I am a VXT Fortran program' - IF (I.EQ.1) PRINT *, ' I am a Fortran 90 program' - IF (I.LT.0 .OR. I.GT.1) PRINT *, ' I am a HAL 9000 computer' - END -@end smallexample - -(In the GNU Fortran and Fortran 90 languages, exclamation point is -a valid character and, unlike space (@key{SPC}) or zero (@samp{0}), -marks a line as a continuation line when it appears in column 6.) - -@node Fortran 90 -@section Fortran 90 -@cindex compatibility, Fortran 90 -@cindex Fortran 90, compatibility - -The GNU Fortran language includes a number of features that are -part of Fortran 90, even when the @samp{-ff90} option is not specified. -The features enabled by @samp{-ff90} are intended to be those that, -when @samp{-ff90} is not specified, would have another -meaning to @code{g77}---usually meaning something invalid in the -GNU Fortran language. - -So, the purpose of @samp{-ff90} is not to specify whether @code{g77} is -to gratuitously reject Fortran 90 constructs. -The @samp{-pedantic} option specified with @samp{-fno-f90} is intended -to do that, although its implementation is certainly incomplete at -this point. - -When @samp{-ff90} is specified: - -@itemize @bullet -@item -The type of @samp{REAL(@var{expr})} and @samp{AIMAG(@var{expr})}, -where @var{expr} is @code{COMPLEX} type, -is the same type as the real part of @var{expr}. - -For example, assuming @samp{Z} is type @code{COMPLEX(KIND=2)}, -@samp{REAL(Z)} would return a value of type @code{REAL(KIND=2)}, -not of type @code{REAL(KIND=1)}, since @samp{-ff90} is specified. -@end itemize - -@node Pedantic Compilation -@section Pedantic Compilation -@cindex pedantic compilation -@cindex compilation, pedantic - -The @samp{-fpedantic} command-line option specifies that @code{g77} -is to warn about code that is not standard-conforming. -This is useful for finding -some extensions @code{g77} accepts that other compilers might not accept. -(Note that the @samp{-pedantic} and @samp{-pedantic-errors} options -always imply @samp{-fpedantic}.) - -With @samp{-fno-f90} in force, ANSI FORTRAN 77 is used as the standard -for conforming code. -With @samp{-ff90} in force, Fortran 90 is used. - -The constructs for which @code{g77} issues diagnostics when @samp{-fpedantic} -and @samp{-fno-f90} are in force are: - -@itemize @bullet -@item -Automatic arrays, as in - -@example -SUBROUTINE X(N) -REAL A(N) -@dots{} -@end example - -@noindent -where @samp{A} is not listed in any @code{ENTRY} statement, -and thus is not a dummy argument. - -@item -The commas in @samp{READ (5), I} and @samp{WRITE (10), J}. - -These commas are disallowed by FORTRAN 77, but, while strictly -superfluous, are syntactically elegant, -especially given that commas are required in statements such -as @samp{READ 99, I} and @samp{PRINT *, J}. -Many compilers permit the superfluous commas for this reason. - -@item -@code{DOUBLE COMPLEX}, either explicitly or implicitly. - -An explicit use of this type is via a @code{DOUBLE COMPLEX} or -@code{IMPLICIT DOUBLE COMPLEX} statement, for examples. - -An example of an implicit use is the expression @samp{C*D}, -where @samp{C} is @code{COMPLEX(KIND=1)} -and @samp{D} is @code{DOUBLE PRECISION}. -This expression is prohibited by ANSI FORTRAN 77 -because the rules of promotion would suggest that it -produce a @code{DOUBLE COMPLEX} result---a type not -provided for by that standard. - -@item -Automatic conversion of numeric -expressions to @code{INTEGER(KIND=1)} in contexts such as: - -@itemize @minus -@item -Array-reference indexes. -@item -Alternate-return values. -@item -Computed @code{GOTO}. -@item -@code{FORMAT} run-time expressions (not yet supported). -@item -Dimension lists in specification statements. -@item -Numbers for I/O statements (such as @samp{READ (UNIT=3.2), I}) -@item -Sizes of @code{CHARACTER} entities in specification statements. -@item -Kind types in specification entities (a Fortran 90 feature). -@item -Initial, terminal, and incrementation parameters for implied-@code{DO} -constructs in @code{DATA} statements. -@end itemize - -@item -Automatic conversion of @code{LOGICAL} expressions to @code{INTEGER} -in contexts such as arithmetic @code{IF} (where @code{COMPLEX} -expressions are disallowed anyway). - -@item -Zero-size array dimensions, as in: - -@example -INTEGER I(10,20,4:2) -@end example - -@item -Zero-length @code{CHARACTER} entities, as in: - -@example -PRINT *, '' -@end example - -@item -Substring operators applied to character constants and named -constants, as in: - -@example -PRINT *, 'hello'(3:5) -@end example - -@item -Null arguments passed to statement function, as in: - -@example -PRINT *, FOO(,3) -@end example - -@item -Disagreement among program units regarding whether a given @code{COMMON} -area is @code{SAVE}d (for targets where program units in a single source -file are ``glued'' together as they typically are for UNIX development -environments). - -@item -Disagreement among program units regarding the size of a -named @code{COMMON} block. - -@item -Specification statements following first @code{DATA} statement. - -(In the GNU Fortran language, @samp{DATA I/1/} may be followed by @samp{INTEGER J}, -but not @samp{INTEGER I}. -The @samp{-fpedantic} option disallows both of these.) - -@item -Semicolon as statement separator, as in: - -@example -CALL FOO; CALL BAR -@end example -@c -@c @item -@c Comma before list of I/O items in @code{WRITE} -@c @c, @code{ENCODE}, @code{DECODE}, and @code{REWRITE} -@c statements, as with @code{READ} (as explained above). - -@item -Use of @samp{&} in column 1 of fixed-form source (to indicate continuation). - -@item -Use of @code{CHARACTER} constants to initialize numeric entities, and vice -versa. - -@item -Expressions having two arithmetic operators in a row, such -as @samp{X*-Y}. -@end itemize - -If @samp{-fpedantic} is specified along with @samp{-ff90}, the -following constructs result in diagnostics: - -@itemize @bullet -@item -Use of semicolon as a statement separator on a line -that has an @code{INCLUDE} directive. -@end itemize - -@node Distensions -@section Distensions -@cindex distensions -@cindex ugly features -@cindex features, ugly - -The @samp{-fugly-*} command-line options determine whether certain -features supported by VAX FORTRAN and other such compilers, but considered -too ugly to be in code that can be changed to use safer and/or more -portable constructs, are accepted. -These are humorously referred to as ``distensions'', -extensions that just plain look ugly in the harsh light of day. - -@menu -* Ugly Implicit Argument Conversion:: Disabled via @samp{-fno-ugly-args}. -* Ugly Assumed-Size Arrays:: Enabled via @samp{-fugly-assumed}. -* Ugly Null Arguments:: Enabled via @samp{-fugly-comma}. -* Ugly Complex Part Extraction:: Enabled via @samp{-fugly-complex}. -* Ugly Conversion of Initializers:: Disabled via @samp{-fno-ugly-init}. -* Ugly Integer Conversions:: Enabled via @samp{-fugly-logint}. -* Ugly Assigned Labels:: Enabled via @samp{-fugly-assign}. -@end menu - -@node Ugly Implicit Argument Conversion -@subsection Implicit Argument Conversion -@cindex Hollerith constants -@cindex constants, Hollerith - -The @samp{-fno-ugly-args} option disables -passing typeless and Hollerith constants as actual arguments -in procedure invocations. -For example: - -@example -CALL FOO(4HABCD) -CALL BAR('123'O) -@end example - -@noindent -These constructs can be too easily used to create non-portable -code, but are not considered as ``ugly'' as others. -Further, they are widely used in existing Fortran source code -in ways that often are quite portable. -Therefore, they are enabled by default. - -@node Ugly Assumed-Size Arrays -@subsection Ugly Assumed-Size Arrays -@cindex arrays, assumed-size -@cindex assumed-size arrays -@cindex DIMENSION X(1) - -The @samp{-fugly-assumed} option enables -the treatment of any array with a final dimension specified as @samp{1} -as an assumed-size array, as if @samp{*} had been specified -instead. - -For example, @samp{DIMENSION X(1)} is treated as if it -had read @samp{DIMENSION X(*)} if @samp{X} is listed as -a dummy argument in a preceding @code{SUBROUTINE}, @code{FUNCTION}, -or @code{ENTRY} statement in the same program unit. - -Use an explicit lower bound to avoid this interpretation. -For example, @samp{DIMENSION X(1:1)} is never treated as if -it had read @samp{DIMENSION X(*)} or @samp{DIMENSION X(1:*)}. -Nor is @samp{DIMENSION X(2-1)} affected by this option, -since that kind of expression is unlikely to have been -intended to designate an assumed-size array. - -This option is used to prevent warnings being issued about apparent -out-of-bounds reference such as @samp{X(2) = 99}. - -It also prevents the array from being used in contexts that -disallow assumed-size arrays, such as @samp{PRINT *,X}. -In such cases, a diagnostic is generated and the source file is -not compiled. - -The construct affected by this option is used only in old code -that pre-exists the widespread acceptance of adjustable and assumed-size -arrays in the Fortran community. - -@emph{Note:} This option does not affect how @samp{DIMENSION X(1)} is -treated if @samp{X} is listed as a dummy argument only -@emph{after} the @code{DIMENSION} statement (presumably in -an @code{ENTRY} statement). -For example, @samp{-fugly-assumed} has no effect on the -following program unit: - -@example -SUBROUTINE X -REAL A(1) -RETURN -ENTRY Y(A) -PRINT *, A -END -@end example - -@node Ugly Complex Part Extraction -@subsection Ugly Complex Part Extraction -@cindex complex values -@cindex real part -@cindex imaginary part - -The @samp{-fugly-complex} option enables -use of the @code{REAL()} and @code{AIMAG()} -intrinsics with arguments that are -@code{COMPLEX} types other than @code{COMPLEX(KIND=1)}. - -With @samp{-ff90} in effect, these intrinsics return -the unconverted real and imaginary parts (respectively) -of their argument. - -With @samp{-fno-f90} in effect, these intrinsics convert -the real and imaginary parts to @code{REAL(KIND=1)}, and return -the result of that conversion. - -Due to this ambiguity, the GNU Fortran language defines -these constructs as invalid, except in the specific -case where they are entirely and solely passed as an -argument to an invocation of the @code{REAL()} intrinsic. -For example, - -@example -REAL(REAL(Z)) -@end example - -@noindent -is permitted even when @samp{Z} is @code{COMPLEX(KIND=2)} -and @samp{-fno-ugly-complex} is in effect, because the -meaning is clear. - -@code{g77} enforces this restriction, unless @samp{-fugly-complex} -is specified, in which case the appropriate interpretation is -chosen and no diagnostic is issued. - -@xref{CMPAMBIG}, for information on how to cope with existing -code with unclear expectations of @code{REAL()} and @code{AIMAG()} -with @code{COMPLEX(KIND=2)} arguments. - -@xref{RealPart Intrinsic}, for information on the @code{REALPART()} -intrinsic, used to extract the real part of a complex expression -without conversion. -@xref{ImagPart Intrinsic}, for information on the @code{IMAGPART()} -intrinsic, used to extract the imaginary part of a complex expression -without conversion. - -@node Ugly Null Arguments -@subsection Ugly Null Arguments -@cindex trailing comma -@cindex comma, trailing -@cindex characters, comma -@cindex null arguments -@cindex arguments, null - -The @samp{-fugly-comma} option enables use of a single trailing comma -to mean ``pass an extra trailing null argument'' -in a list of actual arguments to an external procedure, -and use of an empty list of arguments to such a procedure -to mean ``pass a single null argument''. - -@cindex omitting arguments -@cindex arguments, omitting -(Null arguments often are used in some procedure-calling -schemes to indicate omitted arguments.) - -For example, @samp{CALL FOO(,)} means ``pass -two null arguments'', rather than ``pass one null argument''. -Also, @samp{CALL BAR()} means ``pass one null argument''. - -This construct is considered ``ugly'' because it does not -provide an elegant way to pass a single null argument -that is syntactically distinct from passing no arguments. -That is, this construct changes the meaning of code that -makes no use of the construct. - -So, with @samp{-fugly-comma} in force, @samp{CALL FOO()} -and @samp{I = JFUNC()} pass a single null argument, instead -of passing no arguments as required by the Fortran 77 and -90 standards. - -@emph{Note:} Many systems gracefully allow the case -where a procedure call passes one extra argument that the -called procedure does not expect. - -So, in practice, there might be no difference in -the behavior of a program that does @samp{CALL FOO()} -or @samp{I = JFUNC()} and is compiled with @samp{-fugly-comma} -in force as compared to its behavior when compiled -with the default, @samp{-fno-ugly-comma}, in force, -assuming @samp{FOO} and @samp{JFUNC} do not expect any -arguments to be passed. - -@node Ugly Conversion of Initializers -@subsection Ugly Conversion of Initializers - -The constructs disabled by @samp{-fno-ugly-init} are: - -@itemize @bullet -@cindex Hollerith constants -@cindex constants, Hollerith -@item -Use of Hollerith and typeless constants in contexts where they set -initial (compile-time) values for variables, arrays, and named -constants---that is, @code{DATA} and @code{PARAMETER} statements, plus -type-declaration statements specifying initial values. - -Here are some sample initializations that are disabled by the -@samp{-fno-ugly-init} option: - -@example -PARAMETER (VAL='9A304FFE'X) -REAL*8 STRING/8HOUTPUT00/ -DATA VAR/4HABCD/ -@end example - -@cindex character constants -@cindex constants, character -@item -In the same contexts as above, use of character constants to initialize -numeric items and vice versa (one constant per item). - -Here are more sample initializations that are disabled by the -@samp{-fno-ugly-init} option: - -@example -INTEGER IA -CHARACTER BELL -PARAMETER (IA = 'A') -PARAMETER (BELL = 7) -@end example - -@item -Use of Hollerith and typeless constants on the right-hand side -of assignment statements to numeric types, and in other -contexts (such as passing arguments in invocations of -intrinsic procedures and statement functions) that -are treated as assignments to known types (the dummy -arguments, in these cases). - -Here are sample statements that are disabled by the -@samp{-fno-ugly-init} option: - -@example -IVAR = 4HABCD -PRINT *, IMAX0(2HAB, 2HBA) -@end example -@end itemize - -The above constructs, when used, -can tend to result in non-portable code. -But, they are widely used in existing Fortran code in ways -that often are quite portable. -Therefore, they are enabled by default. - -@node Ugly Integer Conversions -@subsection Ugly Integer Conversions - -The constructs enabled via @samp{-fugly-logint} are: - -@itemize @bullet -@item -Automatic conversion between @code{INTEGER} and @code{LOGICAL} as -dictated by -context (typically implies nonportable dependencies on how a -particular implementation encodes @code{.TRUE.} and @code{.FALSE.}). - -@item -Use of a @code{LOGICAL} variable in @code{ASSIGN} and assigned-@code{GOTO} -statements. -@end itemize - -The above constructs are disabled by default because use -of them tends to lead to non-portable code. -Even existing Fortran code that uses that often turns out -to be non-portable, if not outright buggy. - -Some of this is due to differences among implementations as -far as how @code{.TRUE.} and @code{.FALSE.} are encoded as -@code{INTEGER} values---Fortran code that assumes a particular -coding is likely to use one of the above constructs, and is -also likely to not work correctly on implementations using -different encodings. - -@xref{Equivalence Versus Equality}, for more information. - -@node Ugly Assigned Labels -@subsection Ugly Assigned Labels -@cindex ASSIGN statement -@cindex statements, ASSIGN -@cindex assigned labels -@cindex pointers - -The @samp{-fugly-assign} option forces @code{g77} to use the -same storage for assigned labels as it would for a normal -assignment to the same variable. - -For example, consider the following code fragment: - -@example -I = 3 -ASSIGN 10 TO I -@end example - -@noindent -Normally, for portability and improved diagnostics, @code{g77} -reserves distinct storage for a ``sibling'' of @samp{I}, used -only for @code{ASSIGN} statements to that variable (along with -the corresponding assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O -statements that reference the variable). - -However, some code (that violates the ANSI FORTRAN 77 standard) -attempts to copy assigned labels among variables involved with -@code{ASSIGN} statements, as in: - -@example -ASSIGN 10 TO I -ISTATE(5) = I -@dots{} -J = ISTATE(ICUR) -GOTO J -@end example - -@noindent -Such code doesn't work under @code{g77} unless @samp{-fugly-assign} -is specified on the command-line, ensuring that the value of @code{I} -referenced in the second line is whatever value @code{g77} uses -to designate statement label @samp{10}, so the value may be -copied into the @samp{ISTATE} array, later retrieved into a -variable of the appropriate type (@samp{J}), and used as the target of -an assigned-@code{GOTO} statement. - -@emph{Note:} To avoid subtle program bugs, -when @samp{-fugly-assign} is specified, -@code{g77} requires the type of variables -specified in assigned-label contexts -@emph{must} be the same type returned by @code{%LOC()}. -On many systems, this type is effectively the same -as @code{INTEGER(KIND=1)}, while, on others, it is -effectively the same as @code{INTEGER(KIND=2)}. - -Do @emph{not} depend on @code{g77} actually writing valid pointers -to these variables, however. -While @code{g77} currently chooses that implementation, it might -be changed in the future. - -@xref{Assigned Statement Labels,,Assigned Statement Labels (ASSIGN and GOTO)}, -for implementation details on assigned-statement labels. - -@node Compiler -@chapter The GNU Fortran Compiler - -The GNU Fortran compiler, @code{g77}, supports programs written -in the GNU Fortran language and in some other dialects of Fortran. - -Some aspects of how @code{g77} works are universal regardless -of dialect, and yet are not properly part of the GNU Fortran -language itself. -These are described below. - -@emph{Note: This portion of the documentation definitely needs a lot -of work!} - -@menu -* Compiler Limits:: -* Run-time Environment Limits:: -* Compiler Types:: -* Compiler Constants:: -* Compiler Intrinsics:: -@end menu - -@node Compiler Limits -@section Compiler Limits -@cindex limits, compiler -@cindex compiler limits - -@code{g77}, as with GNU tools in general, imposes few arbitrary restrictions -on lengths of identifiers, number of continuation lines, number of external -symbols in a program, and so on. - -@cindex options, -Nl -@cindex -Nl option -@cindex options, -Nx -@cindex -Nx option -@cindex limits, continuation lines -@cindex limits, lengths of names -For example, some other Fortran compiler have an option -(such as @samp{-Nl@var{x}}) to increase the limit on the -number of continuation lines. -Also, some Fortran compilation systems have an option -(such as @samp{-Nx@var{x}}) to increase the limit on the -number of external symbols. - -@code{g77}, @code{gcc}, and GNU @code{ld} (the GNU linker) have -no equivalent options, since they do not impose arbitrary -limits in these areas. - -@cindex rank, maximum -@cindex maximum rank -@cindex number of dimensions, maximum -@cindex maximum number of dimensions -@cindex limits, rank -@cindex limits, array dimensions -@code{g77} does currently limit the number of dimensions in an array -to the same degree as do the Fortran standards---seven (7). -This restriction might be lifted in a future version. - -@node Run-time Environment Limits -@section Run-time Environment Limits -@cindex limits, run-time library -@cindex wraparound - -As a portable Fortran implementation, -@code{g77} offers its users direct access to, -and otherwise depends upon, -the underlying facilities of the system -used to build @code{g77}, -the system on which @code{g77} itself is used to compile programs, -and the system on which the @code{g77}-compiled program is actually run. -(For most users, the three systems are of the same -type---combination of operating environment and hardware---often -the same physical system.) - -The run-time environment for a particular system -inevitably imposes some limits on a program's use -of various system facilities. -These limits vary from system to system. - -Even when such limits might be well beyond the -possibility of being encountered on a particular system, -the @code{g77} run-time environment -has certain built-in limits, -usually, but not always, stemming from intrinsics -with inherently limited interfaces. - -Currently, the @code{g77} run-time environment -does not generally offer a less-limiting environment -by augmenting the underlying system's own environment. - -Therefore, code written in the GNU Fortran language, -while syntactically and semantically portable, -might nevertheless make non-portable assumptions -about the run-time environment---assumptions that -prove to be false for some particular environments. - -The GNU Fortran language, -the @code{g77} compiler and run-time environment, -and the @code{g77} documentation -do not yet offer comprehensive portable work-arounds for such limits, -though programmers should be able to -find their own in specific instances. - -Not all of the limitations are described in this document. -Some of the known limitations include: - -@menu -* Timer Wraparounds:: -* Year 2000 (Y2K) Problems:: -* Array Size:: -* Character-variable Length:: -* Year 10000 (Y10K) Problems:: -@end menu - -@node Timer Wraparounds -@subsection Timer Wraparounds - -Intrinsics that return values computed from system timers, -whether elapsed (wall-clock) timers, -process CPU timers, -or other kinds of timers, -are prone to experiencing wrap-around errors -(or returning wrapped-around values from successive calls) -due to insufficient ranges -offered by the underlying system's timers. - -@cindex negative time -@cindex short time -@cindex long time -Some of the symptoms of such behaviors include -apparently negative time being computed for a duration, -an extremely short amount of time being computed for a long duration, -and an extremely long amount of time being computed for a short duration. - -See the following for intrinsics -known to have potential problems in these areas -on at least some systems: -@ref{CPU_Time Intrinsic}, -@ref{DTime Intrinsic (function)}, @ref{DTime Intrinsic (subroutine)}, -@ref{ETime Intrinsic (function)}, @ref{ETime Intrinsic (subroutine)}, -@ref{MClock Intrinsic}, @ref{MClock8 Intrinsic}, -@ref{Secnds Intrinsic}, -@ref{Second Intrinsic (function)}, @ref{Second Intrinsic (subroutine)}, -@ref{System_Clock Intrinsic}, -@ref{Time Intrinsic (UNIX)}, @ref{Time Intrinsic (VXT)}, -@ref{Time8 Intrinsic}. - -@node Year 2000 (Y2K) Problems -@subsection Year 2000 (Y2K) Problems -@cindex Y2K compliance -@cindex Year 2000 compliance - -While the @code{g77} compiler itself is believed to -be Year-2000 (Y2K) compliant, -some intrinsics are not, -and, potentially, some underlying systems are not, -perhaps rendering some Y2K-compliant intrinsics -non-compliant when used on those particular systems. - -Fortran code that uses non-Y2K-compliant intrinsics -(listed below) -is, itself, almost certainly not compliant, -and should be modified to use Y2K-compliant intrinsics instead. - -Fortran code that uses no non-Y2K-compliant intrinsics, -but which currently is running on a non-Y2K-compliant system, -can be made more Y2K compliant by compiling and -linking it for use on a new Y2K-compliant system, -such as a new version of an old, non-Y2K-compliant, system. - -Currently, information on Y2K and related issues -is being maintained at -@uref{http://www.gnu.org/software/year2000-list.html}. - -See the following for intrinsics -known to have potential problems in these areas -on at least some systems: -@ref{Date Intrinsic}, -@ref{IDate Intrinsic (VXT)}. - -@cindex y2kbuggy -@cindex date_y2kbuggy_0 -@cindex vxtidate_y2kbuggy_0 -@cindex G77_date_y2kbuggy_0 -@cindex G77_vxtidate_y2kbuggy_0 -The @code{libg2c} library -shipped with any @code{g77} that warns -about invocation of a non-Y2K-compliant intrinsic -has renamed the @code{EXTERNAL} procedure names -of those intrinsics. -This is done so that -the @code{libg2c} implementations of these intrinsics -cannot be directly linked to -as @code{EXTERNAL} names -(which normally would avoid the non-Y2K-intrinsic warning). - -The renamed forms of the @code{EXTERNAL} names -of these renamed procedures -may be linked to -by appending the string @samp{_y2kbug} -to the name of the procedure -in the source code. -For example: - -@smallexample -CHARACTER*20 STR -INTEGER YY, MM, DD -EXTERNAL DATE_Y2KBUG, VXTIDATE_Y2KBUG -CALL DATE_Y2KBUG (STR) -CALL VXTIDATE_Y2KBUG (MM, DD, YY) -@end smallexample - -(Note that the @code{EXTERNAL} statement -is not actually required, -since the modified names are not recognized as intrinsics -by the current version of @code{g77}. -But it is shown in this specific case, -for purposes of illustration.) - -The renaming of @code{EXTERNAL} procedure names of these intrinsics -causes unresolved references at link time. -For example, @samp{EXTERNAL DATE; CALL DATE(STR)} -is normally compiled by @code{g77} -as, in C, @samp{date_(&str, 20);}. -This, in turn, links to the @code{date_} procedure -in the @code{libE77} portion of @code{libg2c}, -which purposely calls a nonexistent procedure -named @code{G77_date_y2kbuggy_0}. -The resulting link-time error is designed, via this name, -to encourage the programmer to look up the -index entries to this portion of the @code{g77} documentation. - -Generally, we recommend that the @code{EXTERNAL} method -of invoking procedures in @code{libg2c} -@emph{not} be used. -When used, some of the correctness checking -normally performed by @code{g77} -is skipped. - -In particular, it is probably better to use the -@code{INTRINSIC} method of invoking -non-Y2K-compliant procedures, -so anyone compiling the code -can quickly notice the potential Y2K problems -(via the warnings printing by @code{g77}) -without having to even look at the code itself. - -If there are problems linking @code{libg2c} -to code compiled by @code{g77} -that involve the string @samp{y2kbug}, -and these are not explained above, -that probably indicates -that a version of @code{libg2c} -older than @code{g77} -is being linked to, -or that the new library is being linked -to code compiled by an older version of @code{g77}. - -That's because, as of the version that warns about -non-Y2K-compliant intrinsic invocation, -@code{g77} references the @code{libg2c} implementations -of those intrinsics -using new names, containing the string @samp{y2kbug}. - -So, linking newly-compiled code -(invoking one of the intrinsics in question) -to an old library -might yield an unresolved reference -to @code{G77_date_y2kbug_0}. -(The old library calls it @code{G77_date_0}.) - -Similarly, linking previously-compiled code -to a new library -might yield an unresolved reference -to @code{G77_vxtidate_0}. -(The new library calls it @code{G77_vxtidate_y2kbug_0}.) - -The proper fix for the above problems -is to obtain the latest release of @code{g77} -and related products -(including @code{libg2c}) -and install them on all systems, -then recompile, relink, and install -(as appropriate) -all existing Fortran programs. - -(Normally, this sort of renaming is steadfastly avoided. -In this case, however, it seems more important to highlight -potential Y2K problems -than to ease the transition -of potentially non-Y2K-compliant code -to new versions of @code{g77} and @code{libg2c}.) - -@node Array Size -@subsection Array Size -@cindex limits, array size -@cindex array size - -Currently, @code{g77} uses the default @code{INTEGER} type -for array indexes, -which limits the sizes of single-dimension arrays -on systems offering a larger address space -than can be addressed by that type. -(That @code{g77} puts all arrays in memory -could be considered another limitation---it -could use large temporary files---but that decision -is left to the programmer as an implementation choice -by most Fortran implementations.) - -@c ??? Investigate this, to offer a more clear statement -@c than the following paragraphs do. -- burley 1999-02-17 -It is not yet clear whether this limitation -never, sometimes, or always applies to the -sizes of multiple-dimension arrays as a whole. - -For example, on a system with 64-bit addresses -and 32-bit default @code{INTEGER}, -an array with a size greater than can be addressed -by a 32-bit offset -can be declared using multiple dimensions. -Such an array is therefore larger -than a single-dimension array can be, -on the same system. - -@cindex limits, multi-dimension arrays -@cindex multi-dimension arrays -@cindex arrays, dimensioning -Whether large multiple-dimension arrays are reliably supported -depends mostly on the @code{gcc} back end (code generator) -used by @code{g77}, and has not yet been fully investigated. - -@node Character-variable Length -@subsection Character-variable Length -@cindex limits, on character-variable length -@cindex character-variable length - -Currently, @code{g77} uses the default @code{INTEGER} type -for the lengths of @code{CHARACTER} variables -and array elements. - -This means that, for example, -a system with a 64-bit address space -and a 32-bit default @code{INTEGER} type -does not, under @code{g77}, -support a @code{CHARACTER*@var{n}} declaration -where @var{n} is greater than 2147483647. - -@node Year 10000 (Y10K) Problems -@subsection Year 10000 (Y10K) Problems -@cindex Y10K compliance -@cindex Year 10000 compliance - -Most intrinsics returning, or computing values based on, -date information are prone to Year-10000 (Y10K) problems, -due to supporting only 4 digits for the year. - -See the following for examples: -@ref{FDate Intrinsic (function)}, @ref{FDate Intrinsic (subroutine)}, -@ref{IDate Intrinsic (UNIX)}, -@ref{Time Intrinsic (VXT)}, -@ref{Date_and_Time Intrinsic}. - -@node Compiler Types -@section Compiler Types -@cindex types, of data -@cindex data types - -Fortran implementations have a fair amount of freedom given them by the -standard as far as how much storage space is used and how much precision -and range is offered by the various types such as @code{LOGICAL(KIND=1)}, -@code{INTEGER(KIND=1)}, @code{REAL(KIND=1)}, @code{REAL(KIND=2)}, -@code{COMPLEX(KIND=1)}, and @code{CHARACTER}. -Further, many compilers offer so-called @samp{*@var{n}} notation, but -the interpretation of @var{n} varies across compilers and target architectures. - -The standard requires that @code{LOGICAL(KIND=1)}, @code{INTEGER(KIND=1)}, -and @code{REAL(KIND=1)} -occupy the same amount of storage space, and that @code{COMPLEX(KIND=1)} -and @code{REAL(KIND=2)} take twice as much storage space as @code{REAL(KIND=1)}. -Further, it requires that @code{COMPLEX(KIND=1)} -entities be ordered such that when a @code{COMPLEX(KIND=1)} variable is -storage-associated (such as via @code{EQUIVALENCE}) -with a two-element @code{REAL(KIND=1)} array named @samp{R}, @samp{R(1)} -corresponds to the real element and @samp{R(2)} to the imaginary -element of the @code{COMPLEX(KIND=1)} variable. - -(Few requirements as to precision or ranges of any of these are -placed on the implementation, nor is the relationship of storage sizes of -these types to the @code{CHARACTER} type specified, by the standard.) - -@code{g77} follows the above requirements, warning when compiling -a program requires placement of items in memory that contradict the -requirements of the target architecture. -(For example, a program can require placement of a @code{REAL(KIND=2)} -on a boundary that is not an even multiple of its size, but still an -even multiple of the size of a @code{REAL(KIND=1)} variable. -On some target architectures, using the canonical -mapping of Fortran types to underlying architectural types, such -placement is prohibited by the machine definition or -the Application Binary Interface (ABI) in force for -the configuration defined for building @code{gcc} and @code{g77}. -@code{g77} warns about such -situations when it encounters them.) - -@code{g77} follows consistent rules for configuring the mapping between Fortran -types, including the @samp{*@var{n}} notation, and the underlying architectural -types as accessed by a similarly-configured applicable version of the -@code{gcc} compiler. -These rules offer a widely portable, consistent Fortran/C -environment, although they might well conflict with the expectations of -users of Fortran compilers designed and written for particular -architectures. - -These rules are based on the configuration that is in force for the -version of @code{gcc} built in the same release as @code{g77} (and -which was therefore used to build both the @code{g77} compiler -components and the @code{libg2c} run-time library): - -@table @code -@cindex REAL(KIND=1) type -@cindex types, REAL(KIND=1) -@item REAL(KIND=1) -Same as @code{float} type. - -@cindex REAL(KIND=2) type -@cindex types, REAL(KIND=2) -@item REAL(KIND=2) -Same as whatever floating-point type that is twice the size -of a @code{float}---usually, this is a @code{double}. - -@cindex INTEGER(KIND=1) type -@cindex types, INTEGER(KIND=1) -@item INTEGER(KIND=1) -Same as an integral type that is occupies the same amount -of memory storage as @code{float}---usually, this is either -an @code{int} or a @code{long int}. - -@cindex LOGICAL(KIND=1) type -@cindex types, LOGICAL(KIND=1) -@item LOGICAL(KIND=1) -Same @code{gcc} type as @code{INTEGER(KIND=1)}. - -@cindex INTEGER(KIND=2) type -@cindex types, INTEGER(KIND=2) -@item INTEGER(KIND=2) -Twice the size, and usually nearly twice the range, -as @code{INTEGER(KIND=1)}---usually, this is either -a @code{long int} or a @code{long long int}. - -@cindex LOGICAL(KIND=2) type -@cindex types, LOGICAL(KIND=2) -@item LOGICAL(KIND=2) -Same @code{gcc} type as @code{INTEGER(KIND=2)}. - -@cindex INTEGER(KIND=3) type -@cindex types, INTEGER(KIND=3) -@item INTEGER(KIND=3) -Same @code{gcc} type as signed @code{char}. - -@cindex LOGICAL(KIND=3) type -@cindex types, LOGICAL(KIND=3) -@item LOGICAL(KIND=3) -Same @code{gcc} type as @code{INTEGER(KIND=3)}. - -@cindex INTEGER(KIND=6) type -@cindex types, INTEGER(KIND=6) -@item INTEGER(KIND=6) -Twice the size, and usually nearly twice the range, -as @code{INTEGER(KIND=3)}---usually, this is -a @code{short}. - -@cindex LOGICAL(KIND=6) type -@cindex types, LOGICAL(KIND=6) -@item LOGICAL(KIND=6) -Same @code{gcc} type as @code{INTEGER(KIND=6)}. - -@cindex COMPLEX(KIND=1) type -@cindex types, COMPLEX(KIND=1) -@item COMPLEX(KIND=1) -Two @code{REAL(KIND=1)} scalars (one for the real part followed by -one for the imaginary part). - -@cindex COMPLEX(KIND=2) type -@cindex types, COMPLEX(KIND=2) -@item COMPLEX(KIND=2) -Two @code{REAL(KIND=2)} scalars. - -@cindex *@var{n} notation -@item @var{numeric-type}*@var{n} -(Where @var{numeric-type} is any type other than @code{CHARACTER}.) -Same as whatever @code{gcc} type occupies @var{n} times the storage -space of a @code{gcc} @code{char} item. - -@cindex DOUBLE PRECISION type -@cindex types, DOUBLE PRECISION -@item DOUBLE PRECISION -Same as @code{REAL(KIND=2)}. - -@cindex DOUBLE COMPLEX type -@cindex types, DOUBLE COMPLEX -@item DOUBLE COMPLEX -Same as @code{COMPLEX(KIND=2)}. -@end table - -Note that the above are proposed correspondences and might change -in future versions of @code{g77}---avoid writing code depending -on them. - -Other types supported by @code{g77} -are derived from gcc types such as @code{char}, @code{short}, -@code{int}, @code{long int}, @code{long long int}, @code{long double}, -and so on. -That is, whatever types @code{gcc} already supports, @code{g77} supports -now or probably will support in a future version. -The rules for the @samp{@var{numeric-type}*@var{n}} notation -apply to these types, -and new values for @samp{@var{numeric-type}(KIND=@var{n})} will be -assigned in a way that encourages clarity, consistency, and portability. - -@node Compiler Constants -@section Compiler Constants -@cindex constants -@cindex types, constants - -@code{g77} strictly assigns types to @emph{all} constants not -documented as ``typeless'' (typeless constants including @samp{'1'Z}, -for example). -Many other Fortran compilers attempt to assign types to typed constants -based on their context. -This results in hard-to-find bugs, nonportable -code, and is not in the spirit (though it strictly follows the letter) -of the 77 and 90 standards. - -@code{g77} might offer, in a future release, explicit constructs by -which a wider variety of typeless constants may be specified, and/or -user-requested warnings indicating places where @code{g77} might differ -from how other compilers assign types to constants. - -@xref{Context-Sensitive Constants}, for more information on this issue. - -@node Compiler Intrinsics -@section Compiler Intrinsics - -@code{g77} offers an ever-widening set of intrinsics. -Currently these all are procedures (functions and subroutines). - -Some of these intrinsics are unimplemented, but their names reserved -to reduce future problems with existing code as they are implemented. -Others are implemented as part of the GNU Fortran language, while -yet others are provided for compatibility with other dialects of -Fortran but are not part of the GNU Fortran language. - -To manage these distinctions, @code{g77} provides intrinsic @emph{groups}, -a facility that is simply an extension of the intrinsic groups provided -by the GNU Fortran language. - -@menu -* Intrinsic Groups:: How intrinsics are grouped for easy management. -* Other Intrinsics:: Intrinsics other than those in the GNU - Fortran language. -@end menu - -@node Intrinsic Groups -@subsection Intrinsic Groups -@cindex groups of intrinsics -@cindex intrinsics, groups - -A given specific intrinsic belongs in one or more groups. -Each group is deleted, disabled, hidden, or enabled -by default or a command-line option. -The meaning of each term follows. - -@table @b -@cindex deleted intrinsics -@cindex intrinsics, deleted -@item Deleted -No intrinsics are recognized as belonging to that group. - -@cindex disabled intrinsics -@cindex intrinsics, disabled -@item Disabled -Intrinsics are recognized as belonging to the group, but -references to them (other than via the @code{INTRINSIC} statement) -are disallowed through that group. - -@cindex hidden intrinsics -@cindex intrinsics, hidden -@item Hidden -Intrinsics in that group are recognized and enabled (if implemented) -@emph{only} if the first mention of the actual name of an intrinsic -in a program unit is in an @code{INTRINSIC} statement. - -@cindex enabled intrinsics -@cindex intrinsics, enabled -@item Enabled -Intrinsics in that group are recognized and enabled (if implemented). -@end table - -The distinction between deleting and disabling a group is illustrated -by the following example. -Assume intrinsic @samp{FOO} belongs only to group @samp{FGR}. -If group @samp{FGR} is deleted, the following program unit will -successfully compile, because @samp{FOO()} will be seen as a -reference to an external function named @samp{FOO}: - -@example -PRINT *, FOO() -END -@end example - -@noindent -If group @samp{FGR} is disabled, compiling the above program will produce -diagnostics, either because the @samp{FOO} intrinsic is improperly invoked -or, if properly invoked, it is not enabled. -To change the above program so it references an external function @samp{FOO} -instead of the disabled @samp{FOO} intrinsic, -add the following line to the top: - -@example -EXTERNAL FOO -@end example - -@noindent -So, deleting a group tells @code{g77} to pretend as though the intrinsics in -that group do not exist at all, whereas disabling it tells @code{g77} to -recognize them as (disabled) intrinsics in intrinsic-like contexts. - -Hiding a group is like enabling it, but the intrinsic must be first -named in an @code{INTRINSIC} statement to be considered a reference to the -intrinsic rather than to an external procedure. -This might be the ``safest'' way to treat a new group of intrinsics -when compiling old -code, because it allows the old code to be generally written as if -those new intrinsics never existed, but to be changed to use them -by inserting @code{INTRINSIC} statements in the appropriate places. -However, it should be the goal of development to use @code{EXTERNAL} -for all names of external procedures that might be intrinsic names. - -If an intrinsic is in more than one group, it is enabled if any of its -containing groups are enabled; if not so enabled, it is hidden if -any of its containing groups are hidden; if not so hidden, it is disabled -if any of its containing groups are disabled; if not so disabled, it is -deleted. -This extra complication is necessary because some intrinsics, -such as @code{IBITS}, belong to more than one group, and hence should be -enabled if any of the groups to which they belong are enabled, and so -on. - -The groups are: - -@cindex intrinsics, groups of -@cindex groups of intrinsics -@table @code -@cindex @code{badu77} intrinsics group -@item badu77 -UNIX intrinsics having inappropriate forms (usually functions that -have intended side effects). - -@cindex @code{gnu} intrinsics group -@item gnu -Intrinsics the GNU Fortran language supports that are extensions to -the Fortran standards (77 and 90). - -@cindex @code{f2c} intrinsics group -@item f2c -Intrinsics supported by AT&T's @code{f2c} converter and/or @code{libf2c}. - -@cindex @code{f90} intrinsics group -@item f90 -Fortran 90 intrinsics. - -@cindex @code{mil} intrinsics group -@item mil -MIL-STD 1753 intrinsics (@code{MVBITS}, @code{IAND}, @code{BTEST}, and so on). - -@cindex @code{mil} intrinsics group -@item unix -UNIX intrinsics (@code{IARGC}, @code{EXIT}, @code{ERF}, and so on). - -@cindex @code{mil} intrinsics group -@item vxt -VAX/VMS FORTRAN (current as of v4) intrinsics. -@end table - -@node Other Intrinsics -@subsection Other Intrinsics -@cindex intrinsics, others -@cindex other intrinsics - -@code{g77} supports intrinsics other than those in the GNU Fortran -language proper. -This set of intrinsics is described below. - -@ifinfo -(Note that the empty lines appearing in the menu below -are not intentional---they result from a bug in the -@code{makeinfo} program.) -@end ifinfo - -@c The actual documentation for intrinsics comes from -@c intdoc.texi, which in turn is automatically generated -@c from the internal g77 tables in intrin.def _and_ the -@c largely hand-written text in intdoc.h. So, if you want -@c to change or add to existing documentation on intrinsics, -@c you probably want to edit intdoc.h. -@c -@clear familyF77 -@clear familyGNU -@clear familyASC -@clear familyMIL -@clear familyF90 -@set familyVXT -@set familyFVZ -@clear familyF2C -@clear familyF2U -@set familyBADU77 -@include intdoc.texi - -@node Other Compilers -@chapter Other Compilers - -An individual Fortran source file can be compiled to -an object (@file{*.o}) file instead of to the final -program executable. -This allows several portions of a program to be compiled -at different times and linked together whenever a new -version of the program is needed. -However, it introduces the issue of @dfn{object compatibility} -across the various object files (and libraries, or @file{*.a} -files) that are linked together to produce any particular -executable file. - -Object compatibility is an issue when combining, in one -program, Fortran code compiled by more than one compiler -(or more than one configuration of a compiler). -If the compilers -disagree on how to transform the names of procedures, there -will normally be errors when linking such programs. -Worse, if the compilers agree on naming, but disagree on issues -like how to pass parameters, return arguments, and lay out -@code{COMMON} areas, the earliest detected errors might be the -incorrect results produced by the program (and that assumes -these errors are detected, which is not always the case). - -Normally, @code{g77} generates code that is -object-compatible with code generated by a version of -@code{f2c} configured (with, for example, @file{f2c.h} definitions) -to be generally compatible with @code{g77} as built by @code{gcc}. -(Normally, @code{f2c} will, by default, conform to the appropriate -configuration, but it is possible that older or perhaps even newer -versions of @code{f2c}, or versions having certain configuration changes -to @code{f2c} internals, will produce object files that are -incompatible with @code{g77}.) - -For example, a Fortran string subroutine -argument will become two arguments on the C side: a @code{char *} -and an @code{int} length. - -Much of this compatibility results from the fact that -@code{g77} uses the same run-time library, -@code{libf2c}, used by @code{f2c}, -though @code{g77} gives its version the name @code{libg2c} -so as to avoid conflicts when linking, -installing them in the same directories, -and so on. - -Other compilers might or might not generate code that -is object-compatible with @code{libg2c} and current @code{g77}, -and some might offer such compatibility only when explicitly -selected via a command-line option to the compiler. - -@emph{Note: This portion of the documentation definitely needs a lot -of work!} - -@menu -* Dropping f2c Compatibility:: When speed is more important. -* Compilers Other Than f2c:: Interoperation with code from other compilers. -@end menu - -@node Dropping f2c Compatibility -@section Dropping @code{f2c} Compatibility - -Specifying @samp{-fno-f2c} allows @code{g77} to generate, in -some cases, faster code, by not needing to allow to the possibility -of linking with code compiled by @code{f2c}. - -For example, this affects how @code{REAL(KIND=1)}, -@code{COMPLEX(KIND=1)}, and @code{COMPLEX(KIND=2)} functions are called. -With @samp{-fno-f2c}, they are -compiled as returning the appropriate @code{gcc} type -(@code{float}, @code{__complex__ float}, @code{__complex__ double}, -in many configurations). - -With @samp{-ff2c} in force, they -are compiled differently (with perhaps slower run-time performance) -to accommodate the restrictions inherent in @code{f2c}'s use of K&R -C as an intermediate language---@code{REAL(KIND=1)} functions -return C's @code{double} type, while @code{COMPLEX} functions return -@code{void} and use an extra argument pointing to a place for the functions to -return their values. - -It is possible that, in some cases, leaving @samp{-ff2c} in force -might produce faster code than using @samp{-fno-f2c}. -Feel free to experiment, but remember to experiment with changing the way -@emph{entire programs and their Fortran libraries are compiled} at -a time, since this sort of experimentation affects the interface -of code generated for a Fortran source file---that is, it affects -object compatibility. - -Note that @code{f2c} compatibility is a fairly static target to achieve, -though not necessarily perfectly so, since, like @code{g77}, it is -still being improved. -However, specifying @samp{-fno-f2c} causes @code{g77} -to generate code that will probably be incompatible with code -generated by future versions of @code{g77} when the same option -is in force. -You should make sure you are always able to recompile complete -programs from source code when upgrading to new versions of @code{g77} -or @code{f2c}, especially when using options such as @samp{-fno-f2c}. - -Therefore, if you are using @code{g77} to compile libraries and other -object files for possible future use and you don't want to require -recompilation for future use with subsequent versions of @code{g77}, -you might want to stick with @code{f2c} compatibility for now, and -carefully watch for any announcements about changes to the -@code{f2c}/@code{libf2c} interface that might affect existing programs -(thus requiring recompilation). - -It is probable that a future version of @code{g77} will not, -by default, generate object files compatible with @code{f2c}, -and that version probably would no longer use @code{libf2c}. -If you expect to depend on this compatibility in the -long term, use the options @samp{-ff2c -ff2c-library} when compiling -all of the applicable code. -This should cause future versions of @code{g77} either to produce -compatible code (at the expense of the availability of some features and -performance), or at the very least, to produce diagnostics. - -(The library @code{g77} produces will no longer be named @file{libg2c} -when it is no longer generally compatible with @file{libf2c}. -It will likely be referred to, and, if installed as a distinct -library, named @code{libg77}, or some other as-yet-unused name.) - -@node Compilers Other Than f2c -@section Compilers Other Than @code{f2c} - -On systems with Fortran compilers other than @code{f2c} and @code{g77}, -code compiled by @code{g77} is not expected to work -well with code compiled by the native compiler. -(This is true for @code{f2c}-compiled objects as well.) -Libraries compiled with the native compiler probably will have -to be recompiled with @code{g77} to be used with @code{g77}-compiled code. - -Reasons for such incompatibilities include: - -@itemize @bullet -@item -There might be differences in the way names of Fortran procedures -are translated for use in the system's object-file format. -For example, the statement @samp{CALL FOO} might be compiled -by @code{g77} to call a procedure the linker @code{ld} sees -given the name @samp{_foo_}, while the apparently corresponding -statement @samp{SUBROUTINE FOO} might be compiled by the -native compiler to define the linker-visible name @samp{_foo}, -or @samp{_FOO_}, and so on. - -@item -There might be subtle type mismatches which cause subroutine arguments -and function return values to get corrupted. - -This is why simply getting @code{g77} to -transform procedure names the same way a native -compiler does is not usually a good idea---unless -some effort has been made to ensure that, aside -from the way the two compilers transform procedure -names, everything else about the way they generate -code for procedure interfaces is identical. - -@item -Native compilers -use libraries of private I/O routines which will not be available -at link time unless you have the native compiler---and you would -have to explicitly ask for them. - -For example, on the Sun you -would have to add @samp{-L/usr/lang/SCx.x -lF77 -lV77} to the link -command. -@end itemize - -@node Other Languages -@chapter Other Languages - -@emph{Note: This portion of the documentation definitely needs a lot -of work!} - -@menu -* Interoperating with C and C++:: -@end menu - -@node Interoperating with C and C++ -@section Tools and advice for interoperating with C and C++ - -@cindex C, linking with -@cindex C++, linking with -@cindex linking with C -The following discussion assumes that you are running @code{g77} in @code{f2c} -compatibility mode, i.e.@: not using @samp{-fno-f2c}. -It provides some -advice about quick and simple techniques for linking Fortran and C (or -C++), the most common requirement. -For the full story consult the -description of code generation. -@xref{Debugging and Interfacing}. - -When linking Fortran and C, it's usually best to use @code{g77} to do -the linking so that the correct libraries are included (including the -maths one). -If you're linking with C++ you will want to add -@samp{-lstdc++}, @samp{-lg++} or whatever. -If you need to use another -driver program (or @code{ld} directly), -you can find out what linkage -options @code{g77} passes by running @samp{g77 -v}. - -@menu -* C Interfacing Tools:: -* C Access to Type Information:: -* f2c Skeletons and Prototypes:: -* C++ Considerations:: -* Startup Code:: -@end menu - -@node C Interfacing Tools -@subsection C Interfacing Tools -@pindex f2c -@cindex cfortran.h -@cindex Netlib -Even if you don't actually use it as a compiler, @code{f2c} from -@uref{ftp://ftp.netlib.org/f2c/src}, can be a useful tool when you're -interfacing (linking) Fortran and C@. -@xref{f2c Skeletons and Prototypes,,Generating Skeletons and Prototypes with @code{f2c}}. - -To use @code{f2c} for this purpose you only need retrieve and -build the @file{src} directory from the distribution, consult the -@file{README} instructions there for machine-specifics, and install the -@code{f2c} program on your path. - -Something else that might be useful is @samp{cfortran.h} from -@uref{ftp://zebra/desy.de/cfortran}. -This is a fairly general tool which -can be used to generate interfaces for calling in both directions -between Fortran and C@. -It can be used in @code{f2c} mode with -@code{g77}---consult its documentation for details. - -@node C Access to Type Information -@subsection Accessing Type Information in C - -@cindex types, Fortran/C -Generally, C code written to link with -@code{g77} code---calling and/or being -called from Fortran---should @samp{#include <g2c.h>} to define the C -versions of the Fortran types. -Don't assume Fortran @code{INTEGER} types -correspond to C @code{int}s, for instance; instead, declare them as -@code{integer}, a type defined by @file{g2c.h}. -@file{g2c.h} is installed where @code{gcc} will find it by -default, assuming you use a copy of @code{gcc} compatible with -@code{g77}, probably built at the same time as @code{g77}. - -@node f2c Skeletons and Prototypes -@subsection Generating Skeletons and Prototypes with @code{f2c} - -@pindex f2c -@cindex -fno-second-underscore -A simple and foolproof way to write @code{g77}-callable C routines---e.g.@: to -interface with an existing library---is to write a file (named, for -example, @file{fred.f}) of dummy Fortran -skeletons comprising just the declaration of the routine(s) and dummy -arguments plus @code{END} statements. -Then run @code{f2c} on file @file{fred.f} to produce @file{fred.c} -into which you can edit -useful code, confident the calling sequence is correct, at least. -(There are some errors otherwise commonly made in generating C -interfaces with @code{f2c} conventions, -such as not using @code{doublereal} -as the return type of a @code{REAL} @code{FUNCTION}.) - -@pindex ftnchek -@code{f2c} also can help with calling Fortran from C, using its -@samp{-P} option to generate C prototypes appropriate for calling the -Fortran.@footnote{The files generated like this can also be used for -inter-unit consistency checking of dummy and actual arguments, although -the @code{ftnchek} tool from @uref{ftp://ftp.netlib.org/fortran} -or @uref{ftp://ftp.dsm.fordham.edu} is -probably better for this purpose.} -If the Fortran code containing any -routines to be called from C is in file @file{joe.f}, use the command -@kbd{f2c -P joe.f} to generate the file @file{joe.P} containing -prototype information. -@code{#include} this in the C which has to call -the Fortran routines to make sure you get it right. - -@xref{Arrays,,Arrays (DIMENSION)}, for information on the differences -between the way Fortran (including compilers like @code{g77}) and -C handle arrays. - -@node C++ Considerations -@subsection C++ Considerations - -@cindex C++ -@code{f2c} can be used to generate suitable code for compilation with a -C++ system using the @samp{-C++} option. -The important thing about linking @code{g77}-compiled -code with C++ is that the prototypes for the @code{g77} -routines must specify C linkage to avoid name mangling. -So, use an @samp{extern "C"} declaration. -@code{f2c}'s @samp{-C++} option will take care -of this when generating skeletons or prototype files as above, and also -avoid clashes with C++ reserved words in addition to those in C@. - -@node Startup Code -@subsection Startup Code - -@cindex startup code -@cindex run-time, initialization -@cindex initialization, run-time -Unlike with some runtime systems, -it shouldn't be necessary -(unless there are bugs) -to use a Fortran main program unit to ensure the -runtime---specifically the I/O system---is initialized. - -However, to use the @code{g77} intrinsics @code{GETARG} and @code{IARGC}, -either the @code{main} routine from the @file{libg2c} library must be used, -or the @code{f_setarg} routine -(new as of @code{egcs} version 1.1 and @code{g77} version 0.5.23) -must be called with the appropriate @code{argc} and @code{argv} arguments -prior to the program calling @code{GETARG} or @code{IARGC}. - -To provide more flexibility for mixed-language programming -involving @code{g77} while allowing for shared libraries, -as of @code{egcs} version 1.1 and @code{g77} version 0.5.23, -@code{g77}'s @code{main} routine in @code{libg2c} -does the following, in order: - -@enumerate -@item -Calls @code{f_setarg} -with the incoming @code{argc} and @code{argv} arguments, -in the same order as for @code{main} itself. - -This sets up the command-line environment -for @code{GETARG} and @code{IARGC}. - -@item -Calls @code{f_setsig} (with no arguments). - -This sets up the signaling and exception environment. - -@item -Calls @code{f_init} (with no arguments). - -This initializes the I/O environment, -though that should not be necessary, -as all I/O functions in @code{libf2c} -are believed to call @code{f_init} automatically, -if necessary. - -(A future version of @code{g77} might skip this explicit step, -to speed up normal exit of a program.) - -@item -Arranges for @code{f_exit} to be called (with no arguments) -when the program exits. - -This ensures that the I/O environment is properly shut down -before the program exits normally. -Otherwise, output buffers might not be fully flushed, -scratch files might not be deleted, and so on. - -The simple way @code{main} does this is -to call @code{f_exit} itself after calling -@code{MAIN__} (in the next step). - -However, this does not catch the cases where the program -might call @code{exit} directly, -instead of using the @code{EXIT} intrinsic -(implemented as @code{exit_} in @code{libf2c}). - -So, @code{main} attempts to use -the operating environment's @code{onexit} or @code{atexit} -facility, if available, -to cause @code{f_exit} to be called automatically -upon any invocation of @code{exit}. - -@item -Calls @code{MAIN__} (with no arguments). - -This starts executing the Fortran main program unit for -the application. -(Both @code{g77} and @code{f2c} currently compile a main -program unit so that its global name is @code{MAIN__}.) - -@item -If no @code{onexit} or @code{atexit} is provided by the system, -calls @code{f_exit}. - -@item -Calls @code{exit} with a zero argument, -to signal a successful program termination. - -@item -Returns a zero value to the caller, -to signal a successful program termination, -in case @code{exit} doesn't exit on the system. -@end enumerate - -All of the above names are C @code{extern} names, -i.e.@: not mangled. - -When using the @code{main} procedure provided by @code{g77} -without a Fortran main program unit, -you need to provide @code{MAIN__} -as the entry point for your C code. -(Make sure you link the object file that defines that -entry point with the rest of your program.) - -To provide your own @code{main} procedure -in place of @code{g77}'s, -make sure you specify the object file defining that procedure -@emph{before} @samp{-lg2c} on the @code{g77} command line. -Since the @samp{-lg2c} option is implicitly provided, -this is usually straightforward. -(Use the @samp{--verbose} option to see how and where -@code{g77} implicitly adds @samp{-lg2c} in a command line -that will link the program. -Feel free to specify @samp{-lg2c} explicitly, -as appropriate.) - -However, when providing your own @code{main}, -make sure you perform the appropriate tasks in the -appropriate order. -For example, if your @code{main} does not call @code{f_setarg}, -make sure the rest of your application does not call -@code{GETARG} or @code{IARGC}. - -And, if your @code{main} fails to ensure that @code{f_exit} -is called upon program exit, -some files might end up incompletely written, -some scratch files might be left lying around, -and some existing files being written might be left -with old data not properly truncated at the end. - -Note that, generally, the @code{g77} operating environment -does not depend on a procedure named @code{MAIN__} actually -being called prior to any other @code{g77}-compiled code. -That is, @code{MAIN__} does not, itself, -set up any important operating-environment characteristics -upon which other code might depend. -This might change in future versions of @code{g77}, -with appropriate notification in the release notes. - -For more information, consult the source code for the above routines. -These are in @file{@value{path-libf2c}/libF77/}, named @file{main.c}, -@file{setarg.c}, @file{setsig.c}, @file{getarg_.c}, and @file{iargc_.c}. - -Also, the file @file{@value{path-g77}/com.c} contains the code @code{g77} -uses to open-code (inline) references to @code{IARGC}. - -@include g77install.texi - -@node Debugging and Interfacing -@chapter Debugging and Interfacing -@cindex debugging -@cindex interfacing -@cindex calling C routines -@cindex C routines calling Fortran -@cindex f2c compatibility - -GNU Fortran currently generates code that is object-compatible with -the @code{f2c} converter. -Also, it avoids limitations in the current GBE, such as the -inability to generate a procedure with -multiple entry points, by generating code that is structured -differently (in terms of procedure names, scopes, arguments, and -so on) than might be expected. - -As a result, writing code in other languages that calls on, is -called by, or shares in-memory data with @code{g77}-compiled code generally -requires some understanding of the way @code{g77} compiles code for -various constructs. - -Similarly, using a debugger to debug @code{g77}-compiled -code, even if that debugger supports native Fortran debugging, generally -requires this sort of information. - -This section describes some of the basic information on how -@code{g77} compiles code for constructs involving interfaces to other -languages and to debuggers. - -@emph{Caution:} Much or all of this information pertains to only the current -release of @code{g77}, sometimes even to using certain compiler options -with @code{g77} (such as @samp{-fno-f2c}). -Do not write code that depends on this -information without clearly marking said code as nonportable and -subject to review for every new release of @code{g77}. -This information -is provided primarily to make debugging of code generated by this -particular release of @code{g77} easier for the user, and partly to make -writing (generally nonportable) interface code easier. -Both of these -activities require tracking changes in new version of @code{g77} as they -are installed, because new versions can change the behaviors -described in this section. - -@menu -* Main Program Unit:: How @code{g77} compiles a main program unit. -* Procedures:: How @code{g77} constructs parameter lists - for procedures. -* Functions:: Functions returning floating-point or character data. -* Names:: Naming of user-defined variables, procedures, etc. -* Common Blocks:: Accessing common variables while debugging. -* Local Equivalence Areas:: Accessing @code{EQUIVALENCE} while debugging. -* Complex Variables:: How @code{g77} performs complex arithmetic. -* Arrays:: Dealing with (possibly multi-dimensional) arrays. -* Adjustable Arrays:: Special consideration for adjustable arrays. -* Alternate Entry Points:: How @code{g77} implements alternate @code{ENTRY}. -* Alternate Returns:: How @code{g77} handles alternate returns. -* Assigned Statement Labels:: How @code{g77} handles @code{ASSIGN}. -* Run-time Library Errors:: Meanings of some @code{IOSTAT=} values. -@end menu - -@node Main Program Unit -@section Main Program Unit (PROGRAM) -@cindex PROGRAM statement -@cindex statements, PROGRAM - -When @code{g77} compiles a main program unit, it gives it the public -procedure name @code{MAIN__}. -The @code{libg2c} library has the actual @code{main()} procedure -as is typical of C-based environments, and -it is this procedure that performs some initial start-up -activity and then calls @code{MAIN__}. - -Generally, @code{g77} and @code{libg2c} are designed so that you need not -include a main program unit written in Fortran in your program---it -can be written in C or some other language. -Especially for I/O handling, this is the case, although @code{g77} version 0.5.16 -includes a bug fix for @code{libg2c} that solved a problem with using the -@code{OPEN} statement as the first Fortran I/O activity in a program -without a Fortran main program unit. - -However, if you don't intend to use @code{g77} (or @code{f2c}) to compile -your main program unit---that is, if you intend to compile a @code{main()} -procedure using some other language---you should carefully -examine the code for @code{main()} in @code{libg2c}, found in the source -file @file{@value{path-libf2c}/libF77/main.c}, to see what kinds of things -might need to be done by your @code{main()} in order to provide the -Fortran environment your Fortran code is expecting. - -@cindex @code{IArgC} intrinsic -@cindex intrinsics, @code{IArgC} -@cindex @code{GetArg} intrinsic -@cindex intrinsics, @code{GetArg} -For example, @code{libg2c}'s @code{main()} sets up the information used by -the @code{IARGC} and @code{GETARG} intrinsics. -Bypassing @code{libg2c}'s @code{main()} -without providing a substitute for this activity would mean -that invoking @code{IARGC} and @code{GETARG} would produce undefined -results. - -@cindex debugging -@cindex main program unit, debugging -@cindex main() -@cindex MAIN__() -@cindex .gdbinit -When debugging, one implication of the fact that @code{main()}, which -is the place where the debugged program ``starts'' from the -debugger's point of view, is in @code{libg2c} is that you won't be -starting your Fortran program at a point you recognize as your -Fortran code. - -The standard way to get around this problem is to set a break -point (a one-time, or temporary, break point will do) at -the entrance to @code{MAIN__}, and then run the program. -A convenient way to do so is to add the @code{gdb} command - -@example -tbreak MAIN__ -@end example - -@noindent -to the file @file{.gdbinit} in the directory in which you're debugging -(using @code{gdb}). - -After doing this, the debugger will see the current execution -point of the program as at the beginning of the main program -unit of your program. - -Of course, if you really want to set a break point at some -other place in your program and just start the program -running, without first breaking at @code{MAIN__}, -that should work fine. - -@node Procedures -@section Procedures (SUBROUTINE and FUNCTION) -@cindex procedures -@cindex SUBROUTINE statement -@cindex statements, SUBROUTINE -@cindex FUNCTION statement -@cindex statements, FUNCTION -@cindex signature of procedures - -Currently, @code{g77} passes arguments via reference---specifically, -by passing a pointer to the location in memory of a variable, array, -array element, a temporary location that holds the result of evaluating an -expression, or a temporary or permanent location that holds the value -of a constant. - -Procedures that accept @code{CHARACTER} arguments are implemented by -@code{g77} so that each @code{CHARACTER} argument has two actual arguments. - -The first argument occupies the expected position in the -argument list and has the user-specified name. -This argument -is a pointer to an array of characters, passed by the caller. - -The second argument is appended to the end of the user-specified -calling sequence and is named @samp{__g77_length_@var{x}}, where @var{x} -is the user-specified name. -This argument is of the C type @code{ftnlen} -(see @file{@value{path-libf2c}/g2c.h.in} for information on that type) and -is the number of characters the caller has allocated in the -array pointed to by the first argument. - -A procedure will ignore the length argument if @samp{X} is not declared -@code{CHARACTER*(*)}, because for other declarations, it knows the -length. -Not all callers necessarily ``know'' this, however, which -is why they all pass the extra argument. - -The contents of the @code{CHARACTER} argument are specified by the -address passed in the first argument (named after it). -The procedure can read or write these contents as appropriate. - -When more than one @code{CHARACTER} argument is present in the argument -list, the length arguments are appended in the order -the original arguments appear. -So @samp{CALL FOO('HI','THERE')} is implemented in -C as @samp{foo("hi","there",2,5);}, ignoring the fact that @code{g77} -does not provide the trailing null bytes on the constant -strings (@code{f2c} does provide them, but they are unnecessary in -a Fortran environment, and you should not expect them to be -there). - -Note that the above information applies to @code{CHARACTER} variables and -arrays @strong{only}. -It does @strong{not} apply to external @code{CHARACTER} -functions or to intrinsic @code{CHARACTER} functions. -That is, no second length argument is passed to @samp{FOO} in this case: - -@example -CHARACTER X -EXTERNAL X -CALL FOO(X) -@end example - -@noindent -Nor does @samp{FOO} expect such an argument in this case: - -@example -SUBROUTINE FOO(X) -CHARACTER X -EXTERNAL X -@end example - -Because of this implementation detail, if a program has a bug -such that there is disagreement as to whether an argument is -a procedure, and the type of the argument is @code{CHARACTER}, subtle -symptoms might appear. - -@node Functions -@section Functions (FUNCTION and RETURN) -@cindex functions -@cindex FUNCTION statement -@cindex statements, FUNCTION -@cindex RETURN statement -@cindex statements, RETURN -@cindex return type of functions - -@code{g77} handles in a special way functions that return the following -types: - -@itemize @bullet -@item -@code{CHARACTER} -@item -@code{COMPLEX} -@item -@code{REAL(KIND=1)} -@end itemize - -For @code{CHARACTER}, @code{g77} implements a subroutine (a C function -returning @code{void}) -with two arguments prepended: @samp{__g77_result}, which the caller passes -as a pointer to a @code{char} array expected to hold the return value, -and @samp{__g77_length}, which the caller passes as an @code{ftnlen} value -specifying the length of the return value as declared in the calling -program. -For @code{CHARACTER*(*)}, the called function uses @samp{__g77_length} -to determine the size of the array that @samp{__g77_result} points to; -otherwise, it ignores that argument. - -For @code{COMPLEX}, when @samp{-ff2c} is in -force, @code{g77} implements -a subroutine with one argument prepended: @samp{__g77_result}, which the -caller passes as a pointer to a variable of the type of the function. -The called function writes the return value into this variable instead -of returning it as a function value. -When @samp{-fno-f2c} is in force, -@code{g77} implements a @code{COMPLEX} function as @code{gcc}'s -@samp{__complex__ float} or @samp{__complex__ double} function -(or an emulation thereof, when @samp{-femulate-complex} is in effect), -returning the result of the function in the same way as @code{gcc} would. - -For @code{REAL(KIND=1)}, when @samp{-ff2c} is in force, @code{g77} implements -a function that actually returns @code{REAL(KIND=2)} (typically -C's @code{double} type). -When @samp{-fno-f2c} is in force, @code{REAL(KIND=1)} -functions return @code{float}. - -@node Names -@section Names -@cindex symbol names -@cindex transforming symbol names - -Fortran permits each implementation to decide how to represent -names as far as how they're seen in other contexts, such as debuggers -and when interfacing to other languages, and especially as far -as how casing is handled. - -External names---names of entities that are public, or ``accessible'', -to all modules in a program---normally have an underscore (@samp{_}) -appended by @code{g77}, -to generate code that is compatible with @code{f2c}. -External names include names of Fortran things like common blocks, -external procedures (subroutines and functions, but not including -statement functions, which are internal procedures), and entry point -names. - -However, use of the @samp{-fno-underscoring} option -disables this kind of transformation of external names (though inhibiting -the transformation certainly improves the chances of colliding with -incompatible externals written in other languages---but that -might be intentional. - -@cindex -fno-underscoring option -@cindex options, -fno-underscoring -@cindex -fno-second-underscore option -@cindex options, -fno-underscoring -When @samp{-funderscoring} is in force, any name (external or local) -that already has at least one underscore in it is -implemented by @code{g77} by appending two underscores. -(This second underscore can be disabled via the -@samp{-fno-second-underscore} option.) -External names are changed this way for @code{f2c} compatibility. -Local names are changed this way to avoid collisions with external names -that are different in the source code---@code{f2c} does the same thing, but -there's no compatibility issue there except for user expectations while -debugging. - -For example: - -@example -Max_Cost = 0 -@end example - -@cindex debugging -@noindent -Here, a user would, in the debugger, refer to this variable using the -name @samp{max_cost__} (or @samp{MAX_COST__} or @samp{Max_Cost__}, -as described below). -(We hope to improve @code{g77} in this regard in the future---don't -write scripts depending on this behavior! -Also, consider experimenting with the @samp{-fno-underscoring} -option to try out debugging without having to massage names by -hand like this.) - -@code{g77} provides a number of command-line options that allow the user -to control how case mapping is handled for source files. -The default is the traditional UNIX model for Fortran compilers---names -are mapped to lower case. -Other command-line options can be specified to map names to upper -case, or to leave them exactly as written in the source file. - -For example: - -@example -Foo = 9.436 -@end example - -@noindent -Here, it is normally the case that the variable assigned will be named -@samp{foo}. -This would be the name to enter when using a debugger to -access the variable. - -However, depending on the command-line options specified, the -name implemented by @code{g77} might instead be @samp{FOO} or even -@samp{Foo}, thus affecting how debugging is done. - -Also: - -@example -Call Foo -@end example - -@noindent -This would normally call a procedure that, if it were in a separate C program, -be defined starting with the line: - -@example -void foo_() -@end example - -@noindent -However, @code{g77} command-line options could be used to change the casing -of names, resulting in the name @samp{FOO_} or @samp{Foo_} being given to the -procedure instead of @samp{foo_}, and the @samp{-fno-underscoring} option -could be used to inhibit the appending of the underscore to the name. - -@node Common Blocks -@section Common Blocks (COMMON) -@cindex common blocks -@cindex @code{COMMON} statement -@cindex statements, @code{COMMON} - -@code{g77} names and lays out @code{COMMON} areas -the same way @code{f2c} does, -for compatibility with @code{f2c}. - -Currently, @code{g77} does not emit ``true'' debugging information for -members of a @code{COMMON} area, due to an apparent bug in the GBE. - -(As of Version 0.5.19, @code{g77} emits debugging information for such -members in the form of a constant string specifying the base name of -the aggregate area and the offset of the member in bytes from the start -of the area. -Use the @samp{-fdebug-kludge} option to enable this behavior. -In @code{gdb}, use @samp{set language c} before printing the value -of the member, then @samp{set language fortran} to restore the default -language, since @code{gdb} doesn't provide a way to print a readable -version of a character string in Fortran language mode. - -This kludge will be removed in a future version of @code{g77} that, -in conjunction with a contemporary version of @code{gdb}, -properly supports Fortran-language debugging, including access -to members of @code{COMMON} areas.) - -@xref{Code Gen Options,,Options for Code Generation Conventions}, -for information on the @samp{-fdebug-kludge} option. - -Moreover, @code{g77} currently implements a @code{COMMON} area such that its -type is an array of the C @code{char} data type. - -So, when debugging, you must know the offset into a @code{COMMON} area -for a particular item in that area, and you have to take into -account the appropriate multiplier for the respective sizes -of the types (as declared in your code) for the items preceding -the item in question as compared to the size of the @code{char} type. - -For example, using default implicit typing, the statement - -@example -COMMON I(15), R(20), T -@end example - -@noindent -results in a public 144-byte @code{char} array named @samp{_BLNK__} -with @samp{I} placed at @samp{_BLNK__[0]}, @samp{R} at @samp{_BLNK__[60]}, -and @samp{T} at @samp{_BLNK__[140]}. -(This is assuming that the target machine for -the compilation has 4-byte @code{INTEGER(KIND=1)} and @code{REAL(KIND=1)} -types.) - -@node Local Equivalence Areas -@section Local Equivalence Areas (EQUIVALENCE) -@cindex equivalence areas -@cindex local equivalence areas -@cindex EQUIVALENCE statement -@cindex statements, EQUIVALENCE - -@code{g77} treats storage-associated areas involving a @code{COMMON} -block as explained in the section on common blocks. - -A local @code{EQUIVALENCE} area is a collection of variables and arrays -connected to each other in any way via @code{EQUIVALENCE}, none of which are -listed in a @code{COMMON} statement. - -Currently, @code{g77} does not emit ``true'' debugging information for -members in a local @code{EQUIVALENCE} area, due to an apparent bug in the GBE. - -(As of Version 0.5.19, @code{g77} does emit debugging information for such -members in the form of a constant string specifying the base name of -the aggregate area and the offset of the member in bytes from the start -of the area. -Use the @samp{-fdebug-kludge} option to enable this behavior. -In @code{gdb}, use @samp{set language c} before printing the value -of the member, then @samp{set language fortran} to restore the default -language, since @code{gdb} doesn't provide a way to print a readable -version of a character string in Fortran language mode. - -This kludge will be removed in a future version of @code{g77} that, -in conjunction with a contemporary version of @code{gdb}, -properly supports Fortran-language debugging, including access -to members of @code{EQUIVALENCE} areas.) - -@xref{Code Gen Options,,Options for Code Generation Conventions}, -for information on the @samp{-fdebug-kludge} option. - -Moreover, @code{g77} implements a local @code{EQUIVALENCE} area such that its -type is an array of the C @code{char} data type. - -The name @code{g77} gives this array of @code{char} type is @samp{__g77_equiv_@var{x}}, -where @var{x} is the name of the item that is placed at the beginning (offset 0) -of this array. -If more than one such item is placed at the beginning, @var{x} is -the name that sorts to the top in an alphabetical sort of the list of -such items. - -When debugging, you must therefore access members of @code{EQUIVALENCE} -areas by specifying the appropriate @samp{__g77_equiv_@var{x}} -array section with the appropriate offset. -See the explanation of debugging @code{COMMON} blocks -for info applicable to debugging local @code{EQUIVALENCE} areas. - -(@emph{Note:} @code{g77} version 0.5.18 and earlier chose the name -for @var{x} using a different method when more than one name was -in the list of names of entities placed at the beginning of the -array. -Though the documentation specified that the first name listed in -the @code{EQUIVALENCE} statements was chosen for @var{x}, @code{g77} -in fact chose the name using a method that was so complicated, -it seemed easier to change it to an alphabetical sort than to describe the -previous method in the documentation.) - -@node Complex Variables -@section Complex Variables (COMPLEX) -@cindex complex variables -@cindex imaginary part -@cindex COMPLEX statement -@cindex statements, COMPLEX - -As of 0.5.20, @code{g77} defaults to handling @code{COMPLEX} types -(and related intrinsics, constants, functions, and so on) -in a manner that -makes direct debugging involving these types in Fortran -language mode difficult. - -Essentially, @code{g77} implements these types using an -internal construct similar to C's @code{struct}, at least -as seen by the @code{gcc} back end. - -Currently, the back end, when outputting debugging info with -the compiled code for the assembler to digest, does not detect -these @code{struct} types as being substitutes for Fortran -complex. -As a result, the Fortran language modes of debuggers such as -@code{gdb} see these types as C @code{struct} types, which -they might or might not support. - -Until this is fixed, switch to C language mode to work with -entities of @code{COMPLEX} type and then switch back to Fortran language -mode afterward. -(In @code{gdb}, this is accomplished via @samp{set lang c} and -either @samp{set lang fortran} or @samp{set lang auto}.) - -@node Arrays -@section Arrays (DIMENSION) -@cindex DIMENSION statement -@cindex statements, DIMENSION -@cindex array ordering -@cindex ordering, array -@cindex column-major ordering -@cindex row-major ordering -@cindex arrays - -Fortran uses ``column-major ordering'' in its arrays. -This differs from other languages, such as C, which use ``row-major ordering''. -The difference is that, with Fortran, array elements adjacent to -each other in memory differ in the @emph{first} subscript instead of -the last; @samp{A(5,10,20)} immediately follows @samp{A(4,10,20)}, -whereas with row-major ordering it would follow @samp{A(5,10,19)}. - -This consideration -affects not only interfacing with and debugging Fortran code, -it can greatly affect how code is designed and written, especially -when code speed and size is a concern. - -Fortran also differs from C, a popular language for interfacing and -to support directly in debuggers, in the way arrays are treated. -In C, arrays are single-dimensional and have interesting relationships -to pointers, neither of which is true for Fortran. -As a result, dealing with Fortran arrays from within -an environment limited to C concepts can be challenging. - -For example, accessing the array element @samp{A(5,10,20)} is easy enough -in Fortran (use @samp{A(5,10,20)}), but in C some difficult machinations -are needed. -First, C would treat the A array as a single-dimension array. -Second, C does not understand low bounds for arrays as does Fortran. -Third, C assumes a low bound of zero (0), while Fortran defaults to a -low bound of one (1) and can supports an arbitrary low bound. -Therefore, calculations must be done -to determine what the C equivalent of @samp{A(5,10,20)} would be, and these -calculations require knowing the dimensions of @samp{A}. - -For @samp{DIMENSION A(2:11,21,0:29)}, the calculation of the offset of -@samp{A(5,10,20)} would be: - -@example - (5-2) -+ (10-1)*(11-2+1) -+ (20-0)*(11-2+1)*(21-1+1) -= 4293 -@end example - -@noindent -So the C equivalent in this case would be @samp{a[4293]}. - -When using a debugger directly on Fortran code, the C equivalent -might not work, because some debuggers cannot understand the notion -of low bounds other than zero. However, unlike @code{f2c}, @code{g77} -does inform the GBE that a multi-dimensional array (like @samp{A} -in the above example) is really multi-dimensional, rather than a -single-dimensional array, so at least the dimensionality of the array -is preserved. - -Debuggers that understand Fortran should have no trouble with -non-zero low bounds, but for non-Fortran debuggers, especially -C debuggers, the above example might have a C equivalent of -@samp{a[4305]}. -This calculation is arrived at by eliminating the subtraction -of the lower bound in the first parenthesized expression on each -line---that is, for @samp{(5-2)} substitute @samp{(5)}, for @samp{(10-1)} -substitute @samp{(10)}, and for @samp{(20-0)} substitute @samp{(20)}. -Actually, the implication of -this can be that the expression @samp{*(&a[2][1][0] + 4293)} works fine, -but that @samp{a[20][10][5]} produces the equivalent of -@samp{*(&a[0][0][0] + 4305)} because of the missing lower bounds. - -Come to think of it, perhaps -the behavior is due to the debugger internally compensating for -the lower bounds by offsetting the base address of @samp{a}, leaving -@samp{&a} set lower, in this case, than @samp{&a[2][1][0]} (the address of -its first element as identified by subscripts equal to the -corresponding lower bounds). - -You know, maybe nobody really needs to use arrays. - -@node Adjustable Arrays -@section Adjustable Arrays (DIMENSION) -@cindex arrays, adjustable -@cindex adjustable arrays -@cindex arrays, automatic -@cindex automatic arrays -@cindex DIMENSION statement -@cindex statements, DIMENSION -@cindex dimensioning arrays -@cindex arrays, dimensioning - -Adjustable and automatic arrays in Fortran require the implementation -(in this -case, the @code{g77} compiler) to ``memorize'' the expressions that -dimension the arrays each time the procedure is invoked. -This is so that subsequent changes to variables used in those -expressions, made during execution of the procedure, do not -have any effect on the dimensions of those arrays. - -For example: - -@example -REAL ARRAY(5) -DATA ARRAY/5*2/ -CALL X(ARRAY, 5) -END -SUBROUTINE X(A, N) -DIMENSION A(N) -N = 20 -PRINT *, N, A -END -@end example - -@noindent -Here, the implementation should, when running the program, print something -like: - -@example -20 2. 2. 2. 2. 2. -@end example - -@noindent -Note that this shows that while the value of @samp{N} was successfully -changed, the size of the @samp{A} array remained at 5 elements. - -To support this, @code{g77} generates code that executes before any user -code (and before the internally generated computed @code{GOTO} to handle -alternate entry points, as described below) that evaluates each -(nonconstant) expression in the list of subscripts for an -array, and saves the result of each such evaluation to be used when -determining the size of the array (instead of re-evaluating the -expressions). - -So, in the above example, when @samp{X} is first invoked, code is -executed that copies the value of @samp{N} to a temporary. -And that same temporary serves as the actual high bound for the single -dimension of the @samp{A} array (the low bound being the constant 1). -Since the user program cannot (legitimately) change the value -of the temporary during execution of the procedure, the size -of the array remains constant during each invocation. - -For alternate entry points, the code @code{g77} generates takes into -account the possibility that a dummy adjustable array is not actually -passed to the actual entry point being invoked at that time. -In that case, the public procedure implementing the entry point -passes to the master private procedure implementing all the -code for the entry points a @code{NULL} pointer where a pointer to that -adjustable array would be expected. -The @code{g77}-generated code -doesn't attempt to evaluate any of the expressions in the subscripts -for an array if the pointer to that array is @code{NULL} at run time in -such cases. -(Don't depend on this particular implementation -by writing code that purposely passes @code{NULL} pointers where the -callee expects adjustable arrays, even if you know the callee -won't reference the arrays---nor should you pass @code{NULL} pointers -for any dummy arguments used in calculating the bounds of such -arrays or leave undefined any values used for that purpose in -COMMON---because the way @code{g77} implements these things might -change in the future!) - -@node Alternate Entry Points -@section Alternate Entry Points (ENTRY) -@cindex alternate entry points -@cindex entry points -@cindex ENTRY statement -@cindex statements, ENTRY - -The GBE does not understand the general concept of -alternate entry points as Fortran provides via the ENTRY statement. -@code{g77} gets around this by using an approach to compiling procedures -having at least one @code{ENTRY} statement that is almost identical to the -approach used by @code{f2c}. -(An alternate approach could be used that -would probably generate faster, but larger, code that would also -be a bit easier to debug.) - -Information on how @code{g77} implements @code{ENTRY} is provided for those -trying to debug such code. -The choice of implementation seems -unlikely to affect code (compiled in other languages) that interfaces -to such code. - -@code{g77} compiles exactly one public procedure for the primary entry -point of a procedure plus each @code{ENTRY} point it specifies, as usual. -That is, in terms of the public interface, there is no difference -between - -@example -SUBROUTINE X -END -SUBROUTINE Y -END -@end example - -@noindent -and: - -@example -SUBROUTINE X -ENTRY Y -END -@end example - -The difference between the above two cases lies in the code compiled -for the @samp{X} and @samp{Y} procedures themselves, plus the fact that, -for the second case, an extra internal procedure is compiled. - -For every Fortran procedure with at least one @code{ENTRY} -statement, @code{g77} compiles an extra procedure -named @samp{__g77_masterfun_@var{x}}, where @var{x} is -the name of the primary entry point (which, in the above case, -using the standard compiler options, would be @samp{x_} in C). - -This extra procedure is compiled as a private procedure---that is, -a procedure not accessible by name to separately compiled modules. -It contains all the code in the program unit, including the code -for the primary entry point plus for every entry point. -(The code for each public procedure is quite short, and explained later.) - -The extra procedure has some other interesting characteristics. - -The argument list for this procedure is invented by @code{g77}. -It contains -a single integer argument named @samp{__g77_which_entrypoint}, -passed by value (as in Fortran's @samp{%VAL()} intrinsic), specifying the -entry point index---0 for the primary entry point, 1 for the -first entry point (the first @code{ENTRY} statement encountered), 2 for -the second entry point, and so on. - -It also contains, for functions returning @code{CHARACTER} and -(when @samp{-ff2c} is in effect) @code{COMPLEX} functions, -and for functions returning different types among the -@code{ENTRY} statements (e.g. @samp{REAL FUNCTION R()} -containing @samp{ENTRY I()}), an argument named @samp{__g77_result} that -is expected at run time to contain a pointer to where to store -the result of the entry point. -For @code{CHARACTER} functions, this -storage area is an array of the appropriate number of characters; -for @code{COMPLEX} functions, it is the appropriate area for the return -type; for multiple-return-type functions, it is a union of all the supported return -types (which cannot include @code{CHARACTER}, since combining @code{CHARACTER} -and non-@code{CHARACTER} return types via @code{ENTRY} in a single function -is not supported by @code{g77}). - -For @code{CHARACTER} functions, the @samp{__g77_result} argument is followed -by yet another argument named @samp{__g77_length} that, at run time, -specifies the caller's expected length of the returned value. -Note that only @code{CHARACTER*(*)} functions and entry points actually -make use of this argument, even though it is always passed by -all callers of public @code{CHARACTER} functions (since the caller does not -generally know whether such a function is @code{CHARACTER*(*)} or whether -there are any other callers that don't have that information). - -The rest of the argument list is the union of all the arguments -specified for all the entry points (in their usual forms, e.g. -@code{CHARACTER} arguments have extra length arguments, all appended at -the end of this list). -This is considered the ``master list'' of -arguments. - -The code for this procedure has, before the code for the first -executable statement, code much like that for the following Fortran -statement: - -@smallexample - GOTO (100000,100001,100002), __g77_which_entrypoint -100000 @dots{}code for primary entry point@dots{} -100001 @dots{}code immediately following first ENTRY statement@dots{} -100002 @dots{}code immediately following second ENTRY statement@dots{} -@end smallexample - -@noindent -(Note that invalid Fortran statement labels and variable names -are used in the above example to highlight the fact that it -represents code generated by the @code{g77} internals, not code to be -written by the user.) - -It is this code that, when the procedure is called, picks which -entry point to start executing. - -Getting back to the public procedures (@samp{x} and @samp{Y} in the original -example), those procedures are fairly simple. -Their interfaces -are just like they would be if they were self-contained procedures -(without @code{ENTRY}), of course, since that is what the callers -expect. -Their code consists of simply calling the private -procedure, described above, with the appropriate extra arguments -(the entry point index, and perhaps a pointer to a multiple-type- -return variable, local to the public procedure, that contains -all the supported returnable non-character types). -For arguments -that are not listed for a given entry point that are listed for -other entry points, and therefore that are in the ``master list'' -for the private procedure, null pointers (in C, the @code{NULL} macro) -are passed. -Also, for entry points that are part of a multiple-type- -returning function, code is compiled after the call of the private -procedure to extract from the multi-type union the appropriate result, -depending on the type of the entry point in question, returning -that result to the original caller. - -When debugging a procedure containing alternate entry points, you -can either set a break point on the public procedure itself (e.g. -a break point on @samp{X} or @samp{Y}) or on the private procedure that -contains most of the pertinent code (e.g. @samp{__g77_masterfun_@var{x}}). -If you do the former, you should use the debugger's command to -``step into'' the called procedure to get to the actual code; with -the latter approach, the break point leaves you right at the -actual code, skipping over the public entry point and its call -to the private procedure (unless you have set a break point there -as well, of course). - -Further, the list of dummy arguments that is visible when the -private procedure is active is going to be the expanded version -of the list for whichever particular entry point is active, -as explained above, and the way in which return values are -handled might well be different from how they would be handled -for an equivalent single-entry function. - -@node Alternate Returns -@section Alternate Returns (SUBROUTINE and RETURN) -@cindex subroutines -@cindex alternate returns -@cindex SUBROUTINE statement -@cindex statements, SUBROUTINE -@cindex RETURN statement -@cindex statements, RETURN - -Subroutines with alternate returns (e.g. @samp{SUBROUTINE X(*)} and -@samp{CALL X(*50)}) are implemented by @code{g77} as functions returning -the C @code{int} type. -The actual alternate-return arguments are omitted from the calling sequence. -Instead, the caller uses -the return value to do a rough equivalent of the Fortran -computed-@code{GOTO} statement, as in @samp{GOTO (50), X()} in the -example above (where @samp{X} is quietly declared as an @code{INTEGER(KIND=1)} -function), and the callee just returns whatever integer -is specified in the @code{RETURN} statement for the subroutine -For example, @samp{RETURN 1} is implemented as @samp{X = 1} followed -by @samp{RETURN} -in C, and @samp{RETURN} by itself is @samp{X = 0} and @samp{RETURN}). - -@node Assigned Statement Labels -@section Assigned Statement Labels (ASSIGN and GOTO) -@cindex assigned statement labels -@cindex statement labels, assigned -@cindex ASSIGN statement -@cindex statements, ASSIGN -@cindex GOTO statement -@cindex statements, GOTO - -For portability to machines where a pointer (such as to a label, -which is how @code{g77} implements @code{ASSIGN} and its relatives, -the assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O statements) -is wider (bitwise) than an @code{INTEGER(KIND=1)}, @code{g77} -uses a different memory location to hold the @code{ASSIGN}ed value of a variable -than it does the numerical value in that variable, unless the -variable is wide enough (can hold enough bits). - -In particular, while @code{g77} implements - -@example -I = 10 -@end example - -@noindent -as, in C notation, @samp{i = 10;}, it implements - -@example -ASSIGN 10 TO I -@end example - -@noindent -as, in GNU's extended C notation (for the label syntax), -@samp{__g77_ASSIGN_I = &&L10;} (where @samp{L10} is just a massaging -of the Fortran label @samp{10} to make the syntax C-like; @code{g77} doesn't -actually generate the name @samp{L10} or any other name like that, -since debuggers cannot access labels anyway). - -While this currently means that an @code{ASSIGN} statement does not -overwrite the numeric contents of its target variable, @emph{do not} -write any code depending on this feature. -@code{g77} has already changed this implementation across -versions and might do so in the future. -This information is provided only to make debugging Fortran programs -compiled with the current version of @code{g77} somewhat easier. -If there's no debugger-visible variable named @samp{__g77_ASSIGN_I} -in a program unit that does @samp{ASSIGN 10 TO I}, that probably -means @code{g77} has decided it can store the pointer to the label directly -into @samp{I} itself. - -@xref{Ugly Assigned Labels}, for information on a command-line option -to force @code{g77} to use the same storage for both normal and -assigned-label uses of a variable. - -@node Run-time Library Errors -@section Run-time Library Errors -@cindex IOSTAT= -@cindex error values -@cindex error messages -@cindex messages, run-time -@cindex I/O, errors - -The @code{libg2c} library currently has the following table to relate -error code numbers, returned in @code{IOSTAT=} variables, to messages. -This information should, in future versions of this document, be -expanded upon to include detailed descriptions of each message. - -In line with good coding practices, any of the numbers in the -list below should @emph{not} be directly written into Fortran -code you write. -Instead, make a separate @code{INCLUDE} file that defines -@code{PARAMETER} names for them, and use those in your code, -so you can more easily change the actual numbers in the future. - -The information below is culled from the definition -of @code{F_err} in @file{f/runtime/libI77/err.c} in the -@code{g77} source tree. - -@smallexample -100: "error in format" -101: "illegal unit number" -102: "formatted io not allowed" -103: "unformatted io not allowed" -104: "direct io not allowed" -105: "sequential io not allowed" -106: "can't backspace file" -107: "null file name" -108: "can't stat file" -109: "unit not connected" -110: "off end of record" -111: "truncation failed in endfile" -112: "incomprehensible list input" -113: "out of free space" -114: "unit not connected" -115: "read unexpected character" -116: "bad logical input field" -117: "bad variable type" -118: "bad namelist name" -119: "variable not in namelist" -120: "no end record" -121: "variable count incorrect" -122: "subscript for scalar variable" -123: "invalid array section" -124: "substring out of bounds" -125: "subscript out of bounds" -126: "can't read file" -127: "can't write file" -128: "'new' file exists" -129: "can't append to file" -130: "non-positive record number" -131: "I/O started while already doing I/O" -@end smallexample - -@node Collected Fortran Wisdom -@chapter Collected Fortran Wisdom -@cindex wisdom -@cindex legacy code -@cindex code, legacy -@cindex writing code -@cindex code, writing - -Most users of @code{g77} can be divided into two camps: - -@itemize @bullet -@item -Those writing new Fortran code to be compiled by @code{g77}. - -@item -Those using @code{g77} to compile existing, ``legacy'' code. -@end itemize - -Users writing new code generally understand most of the necessary -aspects of Fortran to write ``mainstream'' code, but often need -help deciding how to handle problems, such as the construction -of libraries containing @code{BLOCK DATA}. - -Users dealing with ``legacy'' code sometimes don't have much -experience with Fortran, but believe that the code they're compiling -already works when compiled by other compilers (and might -not understand why, as is sometimes the case, it doesn't work -when compiled by @code{g77}). - -The following information is designed to help users do a better job -coping with existing, ``legacy'' Fortran code, and with writing -new code as well. - -@menu -* Advantages Over f2c:: If @code{f2c} is so great, why @code{g77}? -* Block Data and Libraries:: How @code{g77} solves a common problem. -* Loops:: Fortran @code{DO} loops surprise many people. -* Working Programs:: Getting programs to work should be done first. -* Overly Convenient Options:: Temptations to avoid, habits to not form. -* Faster Programs:: Everybody wants these, but at what cost? -@end menu - -@node Advantages Over f2c -@section Advantages Over f2c - -Without @code{f2c}, @code{g77} would have taken much longer to -do and probably not been as good for quite a while. -Sometimes people who notice how much @code{g77} depends on, and -documents encouragement to use, @code{f2c} ask why @code{g77} -was created if @code{f2c} already existed. - -This section gives some basic answers to these questions, though it -is not intended to be comprehensive. - -@menu -* Language Extensions:: Features used by Fortran code. -* Diagnostic Abilities:: Abilities to spot problems early. -* Compiler Options:: Features helpful to accommodate legacy code, etc. -* Compiler Speed:: Speed of the compilation process. -* Program Speed:: Speed of the generated, optimized code. -* Ease of Debugging:: Debugging ease-of-use at the source level. -* Character and Hollerith Constants:: A byte saved is a byte earned. -@end menu - -@node Language Extensions -@subsection Language Extensions - -@code{g77} offers several extensions to FORTRAN 77 language that @code{f2c} -doesn't: - -@itemize @bullet -@item -Automatic arrays - -@item -@code{CYCLE} and @code{EXIT} - -@item -Construct names - -@item -@code{SELECT CASE} - -@item -@code{KIND=} and @code{LEN=} notation - -@item -Semicolon as statement separator - -@item -Constant expressions in @code{FORMAT} statements -(such as @samp{FORMAT(I<J>)}, -where @samp{J} is a @code{PARAMETER} named constant) - -@item -@code{MvBits} intrinsic - -@item -@code{libU77} (Unix-compatibility) library, -with routines known to compiler as intrinsics -(so they work even when compiler options are used -to change the interfaces used by Fortran routines) -@end itemize - -@code{g77} also implements iterative @code{DO} loops -so that they work even in the presence of certain ``extreme'' inputs, -unlike @code{f2c}. -@xref{Loops}. - -However, @code{f2c} offers a few that @code{g77} doesn't, such as: - -@itemize @bullet -@item -Intrinsics in @code{PARAMETER} statements - -@item -Array bounds expressions (such as @samp{REAL M(N(2))}) - -@item -@code{AUTOMATIC} statement -@end itemize - -It is expected that @code{g77} will offer some or all of these missing -features at some time in the future. - -@node Diagnostic Abilities -@subsection Diagnostic Abilities - -@code{g77} offers better diagnosis of problems in @code{FORMAT} statements. -@code{f2c} doesn't, for example, emit any diagnostic for -@samp{FORMAT(XZFAJG10324)}, -leaving that to be diagnosed, at run time, by -the @code{libf2c} run-time library. - -@node Compiler Options -@subsection Compiler Options - -@code{g77} offers compiler options that @code{f2c} doesn't, -most of which are designed to more easily accommodate -legacy code: - -@itemize @bullet -@item -Two that control the automatic appending of extra -underscores to external names - -@item -One that allows dollar signs (@samp{$}) in symbol names - -@item -A variety that control acceptance of various -``ugly'' constructs - -@item -Several that specify acceptable use of upper and lower case -in the source code - -@item -Many that enable, disable, delete, or hide -groups of intrinsics - -@item -One to specify the length of fixed-form source lines -(normally 72) - -@item -One to specify the the source code is written in -Fortran-90-style free-form -@end itemize - -However, @code{f2c} offers a few that @code{g77} doesn't, -like an option to have @code{REAL} default to @code{REAL*8}. -It is expected that @code{g77} will offer all of the -missing options pertinent to being a Fortran compiler -at some time in the future. - -@node Compiler Speed -@subsection Compiler Speed - -Saving the steps of writing and then rereading C code is a big reason -why @code{g77} should be able to compile code much faster than using -@code{f2c} in conjunction with the equivalent invocation of @code{gcc}. - -However, due to @code{g77}'s youth, lots of self-checking is still being -performed. -As a result, this improvement is as yet unrealized -(though the potential seems to be there for quite a big speedup -in the future). -It is possible that, as of version 0.5.18, @code{g77} -is noticeably faster compiling many Fortran source files than using -@code{f2c} in conjunction with @code{gcc}. - -@node Program Speed -@subsection Program Speed - -@code{g77} has the potential to better optimize code than @code{f2c}, -even when @code{gcc} is used to compile the output of @code{f2c}, -because @code{f2c} must necessarily -translate Fortran into a somewhat lower-level language (C) that cannot -preserve all the information that is potentially useful for optimization, -while @code{g77} can gather, preserve, and transmit that information directly -to the GBE. - -For example, @code{g77} implements @code{ASSIGN} and assigned -@code{GOTO} using direct assignment of pointers to labels and direct -jumps to labels, whereas @code{f2c} maps the assigned labels to -integer values and then uses a C @code{switch} statement to encode -the assigned @code{GOTO} statements. - -However, as is typical, theory and reality don't quite match, at least -not in all cases, so it is still the case that @code{f2c} plus @code{gcc} -can generate code that is faster than @code{g77}. - -Version 0.5.18 of @code{g77} offered default -settings and options, via patches to the @code{gcc} -back end, that allow for better program speed, though -some of these improvements also affected the performance -of programs translated by @code{f2c} and then compiled -by @code{g77}'s version of @code{gcc}. - -Version 0.5.20 of @code{g77} offers further performance -improvements, at least one of which (alias analysis) is -not generally applicable to @code{f2c} (though @code{f2c} -could presumably be changed to also take advantage of -this new capability of the @code{gcc} back end, assuming -this is made available in an upcoming release of @code{gcc}). - -@node Ease of Debugging -@subsection Ease of Debugging - -Because @code{g77} compiles directly to assembler code like @code{gcc}, -instead of translating to an intermediate language (C) as does @code{f2c}, -support for debugging can be better for @code{g77} than @code{f2c}. - -However, although @code{g77} might be somewhat more ``native'' in terms of -debugging support than @code{f2c} plus @code{gcc}, there still are a lot -of things ``not quite right''. -Many of the important ones should be resolved in the near future. - -For example, @code{g77} doesn't have to worry about reserved names -like @code{f2c} does. -Given @samp{FOR = WHILE}, @code{f2c} must necessarily -translate this to something @emph{other} than -@samp{for = while;}, because C reserves those words. - -However, @code{g77} does still uses things like an extra level of indirection -for @code{ENTRY}-laden procedures---in this case, because the back end doesn't -yet support multiple entry points. - -Another example is that, given - -@smallexample -COMMON A, B -EQUIVALENCE (B, C) -@end smallexample - -@noindent -the @code{g77} user should be able to access the variables directly, by name, -without having to traverse C-like structures and unions, while @code{f2c} -is unlikely to ever offer this ability (due to limitations in the -C language). - -However, due to apparent bugs in the back end, @code{g77} currently doesn't -take advantage of this facility at all---it doesn't emit any debugging -information for @code{COMMON} and @code{EQUIVALENCE} areas, -other than information -on the array of @code{char} it creates (and, in the case -of local @code{EQUIVALENCE}, names) for each such area. - -Yet another example is arrays. -@code{g77} represents them to the debugger -using the same ``dimensionality'' as in the source code, while @code{f2c} -must necessarily convert them all to one-dimensional arrays to fit -into the confines of the C language. -However, the level of support -offered by debuggers for interactive Fortran-style access to arrays -as compiled by @code{g77} can vary widely. -In some cases, it can actually -be an advantage that @code{f2c} converts everything to widely supported -C semantics. - -In fairness, @code{g77} could do many of the things @code{f2c} does -to get things working at least as well as @code{f2c}---for now, -the developers prefer making @code{g77} work the -way they think it is supposed to, and finding help improving the -other products (the back end of @code{gcc}; @code{gdb}; and so on) -to get things working properly. - -@node Character and Hollerith Constants -@subsection Character and Hollerith Constants -@cindex character constants -@cindex constants, character -@cindex Hollerith constants -@cindex constants, Hollerith -@cindex trailing null byte -@cindex null byte, trailing -@cindex zero byte, trailing - -To avoid the extensive hassle that would be needed to avoid this, -@code{f2c} uses C character constants to encode character and Hollerith -constants. -That means a constant like @samp{'HELLO'} is translated to -@samp{"hello"} in C, which further means that an extra null byte is -present at the end of the constant. -This null byte is superfluous. - -@code{g77} does not generate such null bytes. -This represents significant -savings of resources, such as on systems where @file{/dev/null} or -@file{/dev/zero} represent bottlenecks in the systems' performance, -because @code{g77} simply asks for fewer zeros from the operating -system than @code{f2c}. -(Avoiding spurious use of zero bytes, each byte typically have -eight zero bits, also reduces the liabilities in case -Microsoft's rumored patent on the digits 0 and 1 is upheld.) - -@node Block Data and Libraries -@section Block Data and Libraries -@cindex block data and libraries -@cindex BLOCK DATA statement -@cindex statements, BLOCK DATA -@cindex libraries, containing BLOCK DATA -@cindex f2c compatibility -@cindex compatibility, f2c - -To ensure that block data program units are linked, especially a concern -when they are put into libraries, give each one a name (as in -@samp{BLOCK DATA FOO}) and make sure there is an @samp{EXTERNAL FOO} -statement in every program unit that uses any common block -initialized by the corresponding @code{BLOCK DATA}. -@code{g77} currently compiles a @code{BLOCK DATA} as if it were a -@code{SUBROUTINE}, -that is, it generates an actual procedure having the appropriate name. -The procedure does nothing but return immediately if it happens to be -called. -For @samp{EXTERNAL FOO}, where @samp{FOO} is not otherwise referenced in the -same program unit, @code{g77} assumes there exists a @samp{BLOCK DATA FOO} -in the program and ensures that by generating a -reference to it so the linker will make sure it is present. -(Specifically, @code{g77} outputs in the data section a static pointer to the -external name @samp{FOO}.) - -The implementation @code{g77} currently uses to make this work is -one of the few things not compatible with @code{f2c} as currently -shipped. -@code{f2c} currently does nothing with @samp{EXTERNAL FOO} except -issue a warning that @samp{FOO} is not otherwise referenced, -and, for @samp{BLOCK DATA FOO}, -@code{f2c} doesn't generate a dummy procedure with the name @samp{FOO}. -The upshot is that you shouldn't mix @code{f2c} and @code{g77} in -this particular case. -If you use @code{f2c} to compile @samp{BLOCK DATA FOO}, -then any @code{g77}-compiled program unit that says @samp{EXTERNAL FOO} -will result in an unresolved reference when linked. -If you do the -opposite, then @samp{FOO} might not be linked in under various -circumstances (such as when @samp{FOO} is in a library, or you're -using a ``clever'' linker---so clever, it produces a broken program -with little or no warning by omitting initializations of global data -because they are contained in unreferenced procedures). - -The changes you make to your code to make @code{g77} handle this situation, -however, appear to be a widely portable way to handle it. -That is, many systems permit it (as they should, since the -FORTRAN 77 standard permits @samp{EXTERNAL FOO} when @samp{FOO} -is a block data program unit), and of the ones -that might not link @samp{BLOCK DATA FOO} under some circumstances, most of -them appear to do so once @samp{EXTERNAL FOO} is present in the appropriate -program units. - -Here is the recommended approach to modifying a program containing -a program unit such as the following: - -@smallexample -BLOCK DATA FOO -COMMON /VARS/ X, Y, Z -DATA X, Y, Z / 3., 4., 5. / -END -@end smallexample - -@noindent -If the above program unit might be placed in a library module, then -ensure that every program unit in every program that references that -particular @code{COMMON} area uses the @code{EXTERNAL} statement -to force the area to be initialized. - -For example, change a program unit that starts with - -@smallexample -INTEGER FUNCTION CURX() -COMMON /VARS/ X, Y, Z -CURX = X -END -@end smallexample - -@noindent -so that it uses the @code{EXTERNAL} statement, as in: - -@smallexample -INTEGER FUNCTION CURX() -COMMON /VARS/ X, Y, Z -EXTERNAL FOO -CURX = X -END -@end smallexample - -@noindent -That way, @samp{CURX} is compiled by @code{g77} (and many other -compilers) so that the linker knows it must include @samp{FOO}, -the @code{BLOCK DATA} program unit that sets the initial values -for the variables in @samp{VAR}, in the executable program. - -@node Loops -@section Loops -@cindex DO statement -@cindex statements, DO -@cindex trips, number of -@cindex number of trips - -The meaning of a @code{DO} loop in Fortran is precisely specified -in the Fortran standard@dots{}and is quite different from what -many programmers might expect. - -In particular, Fortran iterative @code{DO} loops are implemented as if -the number of trips through the loop is calculated @emph{before} -the loop is entered. - -The number of trips for a loop is calculated from the @var{start}, -@var{end}, and @var{increment} values specified in a statement such as: - -@smallexample -DO @var{iter} = @var{start}, @var{end}, @var{increment} -@end smallexample - -@noindent -The trip count is evaluated using a fairly simple formula -based on the three values following the @samp{=} in the -statement, and it is that trip count that is effectively -decremented during each iteration of the loop. -If, at the beginning of an iteration of the loop, the -trip count is zero or negative, the loop terminates. -The per-loop-iteration modifications to @var{iter} are not -related to determining whether to terminate the loop. - -There are two important things to remember about the trip -count: - -@itemize @bullet -@item -It can be @emph{negative}, in which case it is -treated as if it was zero---meaning the loop is -not executed at all. - -@item -The type used to @emph{calculate} the trip count -is the same type as @var{iter}, but the final -calculation, and thus the type of the trip -count itself, always is @code{INTEGER(KIND=1)}. -@end itemize - -These two items mean that there are loops that cannot -be written in straightforward fashion using the Fortran @code{DO}. - -For example, on a system with the canonical 32-bit two's-complement -implementation of @code{INTEGER(KIND=1)}, the following loop will not work: - -@smallexample -DO I = -2000000000, 2000000000 -@end smallexample - -@noindent -Although the @var{start} and @var{end} values are well within -the range of @code{INTEGER(KIND=1)}, the @emph{trip count} is not. -The expected trip count is 40000000001, which is outside -the range of @code{INTEGER(KIND=1)} on many systems. - -Instead, the above loop should be constructed this way: - -@smallexample -I = -2000000000 -DO - IF (I .GT. 2000000000) EXIT - @dots{} - I = I + 1 -END DO -@end smallexample - -@noindent -The simple @code{DO} construct and the @code{EXIT} statement -(used to leave the innermost loop) -are F90 features that @code{g77} supports. - -Some Fortran compilers have buggy implementations of @code{DO}, -in that they don't follow the standard. -They implement @code{DO} as a straightforward translation -to what, in C, would be a @code{for} statement. -Instead of creating a temporary variable to hold the trip count -as calculated at run time, these compilers -use the iteration variable @var{iter} to control -whether the loop continues at each iteration. - -The bug in such an implementation shows up when the -trip count is within the range of the type of @var{iter}, -but the magnitude of @samp{ABS(@var{end}) + ABS(@var{incr})} -exceeds that range. For example: - -@smallexample -DO I = 2147483600, 2147483647 -@end smallexample - -@noindent -A loop started by the above statement will work as implemented -by @code{g77}, but the use, by some compilers, of a -more C-like implementation akin to - -@smallexample -for (i = 2147483600; i <= 2147483647; ++i) -@end smallexample - -@noindent -produces a loop that does not terminate, because @samp{i} -can never be greater than 2147483647, since incrementing it -beyond that value overflows @samp{i}, setting it to -2147483648. -This is a large, negative number that still is less than 2147483647. - -Another example of unexpected behavior of @code{DO} involves -using a nonintegral iteration variable @var{iter}, that is, -a @code{REAL} variable. -Consider the following program: - -@smallexample - DATA BEGIN, END, STEP /.1, .31, .007/ - DO 10 R = BEGIN, END, STEP - IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!' - PRINT *,R -10 CONTINUE - PRINT *,'LAST = ',R - IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!' - END -@end smallexample - -@noindent -A C-like view of @code{DO} would hold that the two ``exclamatory'' -@code{PRINT} statements are never executed. -However, this is the output of running the above program -as compiled by @code{g77} on a GNU/Linux ix86 system: - -@smallexample - .100000001 - .107000001 - .114 - .120999999 - @dots{} - .289000005 - .296000004 - .303000003 -LAST = .310000002 - .310000002 .LE. .310000002!! -@end smallexample - -Note that one of the two checks in the program turned up -an apparent violation of the programmer's expectation---yet, -the loop is correctly implemented by @code{g77}, in that -it has 30 iterations. -This trip count of 30 is correct when evaluated using -the floating-point representations for the @var{begin}, -@var{end}, and @var{incr} values (.1, .31, .007) on GNU/Linux -ix86 are used. -On other systems, an apparently more accurate trip count -of 31 might result, but, nevertheless, @code{g77} is -faithfully following the Fortran standard, and the result -is not what the author of the sample program above -apparently expected. -(Such other systems might, for different values in the @code{DATA} -statement, violate the other programmer's expectation, -for example.) - -Due to this combination of imprecise representation -of floating-point values and the often-misunderstood -interpretation of @code{DO} by standard-conforming -compilers such as @code{g77}, use of @code{DO} loops -with @code{REAL} iteration -variables is not recommended. -Such use can be caught by specifying @samp{-Wsurprising}. -@xref{Warning Options}, for more information on this -option. - -@node Working Programs -@section Working Programs - -Getting Fortran programs to work in the first place can be -quite a challenge---even when the programs already work on -other systems, or when using other compilers. - -@code{g77} offers some facilities that might be useful for -tracking down bugs in such programs. - -@menu -* Not My Type:: -* Variables Assumed To Be Zero:: -* Variables Assumed To Be Saved:: -* Unwanted Variables:: -* Unused Arguments:: -* Surprising Interpretations of Code:: -* Aliasing Assumed To Work:: -* Output Assumed To Flush:: -* Large File Unit Numbers:: -* Floating-point precision:: -* Inconsistent Calling Sequences:: -@end menu - -@node Not My Type -@subsection Not My Type -@cindex mistyped variables -@cindex variables, mistyped -@cindex mistyped functions -@cindex functions, mistyped -@cindex implicit typing - -A fruitful source of bugs in Fortran source code is use, or -mis-use, of Fortran's implicit-typing feature, whereby the -type of a variable, array, or function is determined by the -first character of its name. - -Simple cases of this include statements like @samp{LOGX=9.227}, -without a statement such as @samp{REAL LOGX}. -In this case, @samp{LOGX} is implicitly given @code{INTEGER(KIND=1)} -type, with the result of the assignment being that it is given -the value @samp{9}. - -More involved cases include a function that is defined starting -with a statement like @samp{DOUBLE PRECISION FUNCTION IPS(@dots{})}. -Any caller of this function that does not also declare @samp{IPS} -as type @code{DOUBLE PRECISION} (or, in GNU Fortran, @code{REAL(KIND=2)}) -is likely to assume it returns -@code{INTEGER}, or some other type, leading to invalid results -or even program crashes. - -The @samp{-Wimplicit} option might catch failures to -properly specify the types of -variables, arrays, and functions in the code. - -However, in code that makes heavy use of Fortran's -implicit-typing facility, this option might produce so -many warnings about cases that are working, it would be -hard to find the one or two that represent bugs. -This is why so many experienced Fortran programmers strongly -recommend widespread use of the @code{IMPLICIT NONE} statement, -despite it not being standard FORTRAN 77, to completely turn -off implicit typing. -(@code{g77} supports @code{IMPLICIT NONE}, as do almost all -FORTRAN 77 compilers.) - -Note that @samp{-Wimplicit} catches only implicit typing of -@emph{names}. -It does not catch implicit typing of expressions such -as @samp{X**(2/3)}. -Such expressions can be buggy as well---in fact, @samp{X**(2/3)} -is equivalent to @samp{X**0}, due to the way Fortran expressions -are given types and then evaluated. -(In this particular case, the programmer probably wanted -@samp{X**(2./3.)}.) - -@node Variables Assumed To Be Zero -@subsection Variables Assumed To Be Zero -@cindex zero-initialized variables -@cindex variables, assumed to be zero -@cindex uninitialized variables - -Many Fortran programs were developed on systems that provided -automatic initialization of all, or some, variables and arrays -to zero. -As a result, many of these programs depend, sometimes -inadvertently, on this behavior, though to do so violates -the Fortran standards. - -You can ask @code{g77} for this behavior by specifying the -@samp{-finit-local-zero} option when compiling Fortran code. -(You might want to specify @samp{-fno-automatic} as well, -to avoid code-size inflation for non-optimized compilations.) - -Note that a program that works better when compiled with the -@samp{-finit-local-zero} option -is almost certainly depending on a particular system's, -or compiler's, tendency to initialize some variables to zero. -It might be worthwhile finding such cases and fixing them, -using techniques such as compiling with the @samp{-O -Wuninitialized} -options using @code{g77}. - -@node Variables Assumed To Be Saved -@subsection Variables Assumed To Be Saved -@cindex variables, retaining values across calls -@cindex saved variables -@cindex static variables - -Many Fortran programs were developed on systems that -saved the values of all, or some, variables and arrays -across procedure calls. -As a result, many of these programs depend, sometimes -inadvertently, on being able to assign a value to a -variable, perform a @code{RETURN} to a calling procedure, -and, upon subsequent invocation, reference the previously -assigned variable to obtain the value. - -They expect this despite not using the @code{SAVE} statement -to specify that the value in a variable is expected to survive -procedure returns and calls. -Depending on variables and arrays to retain values across -procedure calls without using @code{SAVE} to require it violates -the Fortran standards. - -You can ask @code{g77} to assume @code{SAVE} is specified for all -relevant (local) variables and arrays by using the -@samp{-fno-automatic} option. - -Note that a program that works better when compiled with the -@samp{-fno-automatic} option -is almost certainly depending on not having to use -the @code{SAVE} statement as required by the Fortran standard. -It might be worthwhile finding such cases and fixing them, -using techniques such as compiling with the @samp{-O -Wuninitialized} -options using @code{g77}. - -@node Unwanted Variables -@subsection Unwanted Variables - -The @samp{-Wunused} option can find bugs involving -implicit typing, sometimes -more easily than using @samp{-Wimplicit} in code that makes -heavy use of implicit typing. -An unused variable or array might indicate that the -spelling for its declaration is different from that of -its intended uses. - -Other than cases involving typos, unused variables rarely -indicate actual bugs in a program. -However, investigating such cases thoroughly has, on occasion, -led to the discovery of code that had not been completely -written---where the programmer wrote declarations as needed -for the whole algorithm, wrote some or even most of the code -for that algorithm, then got distracted and forgot that the -job was not complete. - -@node Unused Arguments -@subsection Unused Arguments -@cindex unused arguments -@cindex arguments, unused - -As with unused variables, It is possible that unused arguments -to a procedure might indicate a bug. -Compile with @samp{-W -Wunused} option to catch cases of -unused arguments. - -Note that @samp{-W} also enables warnings regarding overflow -of floating-point constants under certain circumstances. - -@node Surprising Interpretations of Code -@subsection Surprising Interpretations of Code - -The @samp{-Wsurprising} option can help find bugs involving -expression evaluation or in -the way @code{DO} loops with non-integral iteration variables -are handled. -Cases found by this option might indicate a difference of -interpretation between the author of the code involved, and -a standard-conforming compiler such as @code{g77}. -Such a difference might produce actual bugs. - -In any case, changing the code to explicitly do what the -programmer might have expected it to do, so @code{g77} and -other compilers are more likely to follow the programmer's -expectations, might be worthwhile, especially if such changes -make the program work better. - -@node Aliasing Assumed To Work -@subsection Aliasing Assumed To Work -@cindex -falias-check option -@cindex options, -falias-check -@cindex -fargument-alias option -@cindex options, -fargument-alias -@cindex -fargument-noalias option -@cindex options, -fargument-noalias -@cindex -fno-argument-noalias-global option -@cindex options, -fno-argument-noalias-global -@cindex aliasing -@cindex anti-aliasing -@cindex overlapping arguments -@cindex overlays -@cindex association, storage -@cindex storage association -@cindex scheduling of reads and writes -@cindex reads and writes, scheduling - -The @samp{-falias-check}, @samp{-fargument-alias}, -@samp{-fargument-noalias}, -and @samp{-fno-argument-noalias-global} options, -introduced in version 0.5.20 and -@code{g77}'s version 2.7.2.2.f.2 of @code{gcc}, -were withdrawn as of @code{g77} version 0.5.23 -due to their not being supported by @code{gcc} version 2.8. - -These options, which control the assumptions regarding aliasing -(overlapping) of writes and reads to main memory (core) made -by the @code{gcc} back end, -might well be added back (in some form) in a future version -of @code{gcc}. - -However, these options @emph{are} supported by @code{egcs}. - -The information below still is useful, but applies to -only those versions of @code{g77} that support the -alias analysis implied by support for these options. - -These options are effective only when compiling with @samp{-O} -(specifying any level other than @samp{-O0}) -or with @samp{-falias-check}. - -The default for Fortran code is @samp{-fargument-noalias-global}. -(The default for C code and code written in other C-based languages -is @samp{-fargument-alias}. -These defaults apply regardless of whether you use @code{g77} or -@code{gcc} to compile your code.) - -Note that, on some systems, compiling with @samp{-fforce-addr} in -effect can produce more optimal code when the default aliasing -options are in effect (and when optimization is enabled). - -If your program is not working when compiled with optimization, -it is possible it is violating the Fortran standards (77 and 90) -by relying on the ability to ``safely'' modify variables and -arrays that are aliased, via procedure calls, to other variables -and arrays, without using @code{EQUIVALENCE} to explicitly -set up this kind of aliasing. - -(The FORTRAN 77 standard's prohibition of this sort of -overlap, generally referred to therein as ``storage -assocation'', appears in Sections 15.9.3.6. -This prohibition allows implementations, such as @code{g77}, -to, for example, implement the passing of procedures and -even values in @code{COMMON} via copy operations into local, -perhaps more efficiently accessed temporaries at entry to a -procedure, and, where appropriate, via copy operations back -out to their original locations in memory at exit from that -procedure, without having to take into consideration the -order in which the local copies are updated by the code, -among other things.) - -To test this hypothesis, try compiling your program with -the @samp{-fargument-alias} option, which causes the -compiler to revert to assumptions essentially the same as -made by versions of @code{g77} prior to 0.5.20. - -If the program works using this option, that strongly suggests -that the bug is in your program. -Finding and fixing the bug(s) should result in a program that -is more standard-conforming and that can be compiled by @code{g77} -in a way that results in a faster executable. - -(You might want to try compiling with @samp{-fargument-noalias}, -a kind of half-way point, to see if the problem is limited to -aliasing between dummy arguments and @code{COMMON} variables---this -option assumes that such aliasing is not done, while still allowing -aliasing among dummy arguments.) - -An example of aliasing that is invalid according to the standards -is shown in the following program, which might @emph{not} produce -the expected results when executed: - -@smallexample -I = 1 -CALL FOO(I, I) -PRINT *, I -END - -SUBROUTINE FOO(J, K) -J = J + K -K = J * K -PRINT *, J, K -END -@end smallexample - -The above program attempts to use the temporary aliasing of the -@samp{J} and @samp{K} arguments in @samp{FOO} to effect a -pathological behavior---the simultaneous changing of the values -of @emph{both} @samp{J} and @samp{K} when either one of them -is written. - -The programmer likely expects the program to print these values: - -@example -2 4 -4 -@end example - -However, since the program is not standard-conforming, an -implementation's behavior when running it is undefined, because -subroutine @samp{FOO} modifies at least one of the arguments, -and they are aliased with each other. -(Even if one of the assignment statements was deleted, the -program would still violate these rules. -This kind of on-the-fly aliasing is permitted by the standard -only when none of the aliased items are defined, or written, -while the aliasing is in effect.) - -As a practical example, an optimizing compiler might schedule -the @samp{J =} part of the second line of @samp{FOO} @emph{after} -the reading of @samp{J} and @samp{K} for the @samp{J * K} expression, -resulting in the following output: - -@example -2 2 -2 -@end example - -Essentially, compilers are promised (by the standard and, therefore, -by programmers who write code they claim to be standard-conforming) -that if they cannot detect aliasing via static analysis of a single -program unit's @code{EQUIVALENCE} and @code{COMMON} statements, no -such aliasing exists. -In such cases, compilers are free to assume that an assignment to -one variable will not change the value of another variable, allowing -it to avoid generating code to re-read the value of the other -variable, to re-schedule reads and writes, and so on, to produce -a faster executable. - -The same promise holds true for arrays (as seen by the called -procedure)---an element of one dummy array cannot be aliased -with, or overlap, any element of another dummy array or be -in a @code{COMMON} area known to the procedure. - -(These restrictions apply only when the procedure defines, or -writes to, one of the aliased variables or arrays.) - -Unfortunately, there is no way to find @emph{all} possible cases of -violations of the prohibitions against aliasing in Fortran code. -Static analysis is certainly imperfect, as is run-time analysis, -since neither can catch all violations. -(Static analysis can catch all likely violations, and some that -might never actually happen, while run-time analysis can catch -only those violations that actually happen during a particular run. -Neither approach can cope with programs mixing Fortran code with -routines written in other languages, however.) - -Currently, @code{g77} provides neither static nor run-time facilities -to detect any cases of this problem, although other products might. -Run-time facilities are more likely to be offered by future -versions of @code{g77}, though patches improving @code{g77} so that -it provides either form of detection are welcome. - -@node Output Assumed To Flush -@subsection Output Assumed To Flush -@cindex ALWAYS_FLUSH -@cindex synchronous write errors -@cindex disk full -@cindex flushing output -@cindex fflush() -@cindex I/O, flushing -@cindex output, flushing -@cindex writes, flushing -@cindex NFS -@cindex network file system - -For several versions prior to 0.5.20, @code{g77} configured its -version of the @code{libf2c} run-time library so that one of -its configuration macros, @code{ALWAYS_FLUSH}, was defined. - -This was done as a result of a belief that many programs expected -output to be flushed to the operating system (under UNIX, via -the @code{fflush()} library call) with the result that errors, -such as disk full, would be immediately flagged via the -relevant @code{ERR=} and @code{IOSTAT=} mechanism. - -Because of the adverse effects this approach had on the performance -of many programs, @code{g77} no longer configures @code{libf2c} -(now named @code{libg2c} in its @code{g77} incarnation) -to always flush output. - -If your program depends on this behavior, either insert the -appropriate @samp{CALL FLUSH} statements, or modify the sources -to the @code{libg2c}, rebuild and reinstall @code{g77}, and -relink your programs with the modified library. - -(Ideally, @code{libg2c} would offer the choice at run-time, so -that a compile-time option to @code{g77} or @code{f2c} could -result in generating the appropriate calls to flushing or -non-flushing library routines.) - -@xref{Always Flush Output}, for information on how to modify -the @code{g77} source tree so that a version of @code{libg2c} -can be built and installed with the @code{ALWAYS_FLUSH} macro defined. - -@node Large File Unit Numbers -@subsection Large File Unit Numbers -@cindex MXUNIT -@cindex unit numbers -@cindex maximum unit number -@cindex illegal unit number -@cindex increasing maximum unit number - -If your program crashes at run time with a message including -the text @samp{illegal unit number}, that probably is -a message from the run-time library, @code{libg2c}. - -The message means that your program has attempted to use a -file unit number that is out of the range accepted by -@code{libg2c}. -Normally, this range is 0 through 99, and the high end -of the range is controlled by a @code{libg2c} source-file -macro named @code{MXUNIT}. - -If you can easily change your program to use unit numbers -in the range 0 through 99, you should do so. - -Otherwise, see @ref{Larger File Unit Numbers}, for information on how -to change @code{MXUNIT} in @code{libg2c} so you can build and -install a new version of @code{libg2c} that supports the larger -unit numbers you need. - -@emph{Note:} While @code{libg2c} places a limit on the range -of Fortran file-unit numbers, the underlying library and operating -system might impose different kinds of limits. -For example, some systems limit the number of files simultaneously -open by a running program. -Information on how to increase these limits should be found -in your system's documentation. - -@node Floating-point precision -@subsection Floating-point precision - -@cindex IEEE 754 conformance -@cindex conformance, IEEE 754 -@cindex floating-point, precision -@cindex ix86 floating-point -@cindex x86 floating-point -If your program depends on exact IEEE 754 floating-point handling it may -help on some systems---specifically x86 or m68k hardware---to use -the @samp{-ffloat-store} option or to reset the precision flag on the -floating-point unit. -@xref{Optimize Options}. - -However, it might be better simply to put the FPU into double precision -mode and not take the performance hit of @samp{-ffloat-store}. On x86 -and m68k GNU systems you can do this with a technique similar to that -for turning on floating-point exceptions -(@pxref{Floating-point Exception Handling}). -The control word could be set to double precision by -replacing the @code{__setfpucw} call with one like this: -@smallexample - __setfpucw ((_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE); -@end smallexample -(It is not clear whether this has any effect on the operation of the GNU -maths library, but we have no evidence of it causing trouble.) - -Some targets (such as the Alpha) may need special options for full IEEE -conformance. -@xref{Submodel Options,,Hardware Models and Configurations,gcc,Using and Porting GNU CC}. - -@node Inconsistent Calling Sequences -@subsection Inconsistent Calling Sequences - -@pindex ftnchek -@cindex floating-point, errors -@cindex ix86 FPU stack -@cindex x86 FPU stack -Code containing inconsistent calling sequences in the same file is -normally rejected---see @ref{GLOBALS}. -(Use, say, @code{ftnchek} to ensure -consistency across source files. -@xref{f2c Skeletons and Prototypes,, -Generating Skeletons and Prototypes with @code{f2c}}.) - -Mysterious errors, which may appear to be code generation problems, can -appear specifically on the x86 architecture with some such -inconsistencies. On x86 hardware, floating-point return values of -functions are placed on the floating-point unit's register stack, not -the normal stack. Thus calling a @code{REAL} or @code{DOUBLE PRECISION} -@code{FUNCTION} as some other sort of procedure, or vice versa, -scrambles the floating-point stack. This may break unrelated code -executed later. Similarly if, say, external C routines are written -incorrectly. - -@node Overly Convenient Options -@section Overly Convenient Command-line Options -@cindex overly convenient options -@cindex options, overly convenient - -These options should be used only as a quick-and-dirty way to determine -how well your program will run under different compilation models -without having to change the source. -Some are more problematic -than others, depending on how portable and maintainable you want the -program to be (and, of course, whether you are allowed to change it -at all is crucial). - -You should not continue to use these command-line options to compile -a given program, but rather should make changes to the source code: - -@table @code -@cindex -finit-local-zero option -@cindex options, -finit-local-zero -@item -finit-local-zero -(This option specifies that any uninitialized local variables -and arrays have default initialization to binary zeros.) - -Many other compilers do this automatically, which means lots of -Fortran code developed with those compilers depends on it. - -It is safer (and probably -would produce a faster program) to find the variables and arrays that -need such initialization and provide it explicitly via @code{DATA}, so that -@samp{-finit-local-zero} is not needed. - -Consider using @samp{-Wuninitialized} (which requires @samp{-O}) to -find likely candidates, but -do not specify @samp{-finit-local-zero} or @samp{-fno-automatic}, -or this technique won't work. - -@cindex -fno-automatic option -@cindex options, -fno-automatic -@item -fno-automatic -(This option specifies that all local variables and arrays -are to be treated as if they were named in @code{SAVE} statements.) - -Many other compilers do this automatically, which means lots of -Fortran code developed with those compilers depends on it. - -The effect of this is that all non-automatic variables and arrays -are made static, that is, not placed on the stack or in heap storage. -This might cause a buggy program to appear to work better. -If so, rather than relying on this command-line option (and hoping all -compilers provide the equivalent one), add @code{SAVE} -statements to some or all program unit sources, as appropriate. -Consider using @samp{-Wuninitialized} (which requires @samp{-O}) -to find likely candidates, but -do not specify @samp{-finit-local-zero} or @samp{-fno-automatic}, -or this technique won't work. - -The default is @samp{-fautomatic}, which tells @code{g77} to try -and put variables and arrays on the stack (or in fast registers) -where possible and reasonable. -This tends to make programs faster. - -@cindex automatic arrays -@cindex arrays, automatic -@emph{Note:} Automatic variables and arrays are not affected -by this option. -These are variables and arrays that are @emph{necessarily} automatic, -either due to explicit statements, or due to the way they are -declared. -Examples include local variables and arrays not given the -@code{SAVE} attribute in procedures declared @code{RECURSIVE}, -and local arrays declared with non-constant bounds (automatic -arrays). -Currently, @code{g77} supports only automatic arrays, not -@code{RECURSIVE} procedures or other means of explicitly -specifying that variables or arrays are automatic. - -@cindex -f@var{group}-intrinsics-hide option -@cindex options, -f@var{group}-intrinsics-hide -@item -f@var{group}-intrinsics-hide -Change the source code to use @code{EXTERNAL} for any external procedure -that might be the name of an intrinsic. -It is easy to find these using @samp{-f@var{group}-intrinsics-disable}. -@end table - -@node Faster Programs -@section Faster Programs -@cindex speed, of programs -@cindex programs, speeding up - -Aside from the usual @code{gcc} options, such as @samp{-O}, -@samp{-ffast-math}, and so on, consider trying some of the -following approaches to speed up your program (once you get -it working). - -@menu -* Aligned Data:: -* Prefer Automatic Uninitialized Variables:: -* Avoid f2c Compatibility:: -* Use Submodel Options:: -@end menu - -@node Aligned Data -@subsection Aligned Data -@cindex alignment -@cindex data, aligned -@cindex stack, aligned -@cindex aligned data -@cindex aligned stack -@cindex Pentium optimizations -@cindex optimization, for Pentium - -On some systems, such as those with Pentium Pro CPUs, programs -that make heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) -might run much slower -than possible due to the compiler not aligning these 64-bit -values to 64-bit boundaries in memory. -(The effect also is present, though -to a lesser extent, on the 586 (Pentium) architecture.) - -The Intel x86 architecture generally ensures that these programs will -work on all its implementations, -but particular implementations (such as Pentium Pro) -perform better with more strict alignment. -(Such behavior isn't unique to the Intel x86 architecture.) -Other architectures might @emph{demand} 64-bit alignment -of 64-bit data. - -There are a variety of approaches to use to address this problem: - -@itemize @bullet -@item -@cindex @code{COMMON} layout -@cindex layout of @code{COMMON} blocks -Order your @code{COMMON} and @code{EQUIVALENCE} areas such -that the variables and arrays with the widest alignment -guidelines come first. - -For example, on most systems, this would mean placing -@code{COMPLEX(KIND=2)}, @code{REAL(KIND=2)}, and -@code{INTEGER(KIND=2)} entities first, followed by @code{REAL(KIND=1)}, -@code{INTEGER(KIND=1)}, and @code{LOGICAL(KIND=1)} entities, then -@code{INTEGER(KIND=6)} entities, and finally @code{CHARACTER} -and @code{INTEGER(KIND=3)} entities. - -The reason to use such placement is it makes it more likely -that your data will be aligned properly, without requiring -you to do detailed analysis of each aggregate (@code{COMMON} -and @code{EQUIVALENCE}) area. - -Specifically, on systems where the above guidelines are -appropriate, placing @code{CHARACTER} entities before -@code{REAL(KIND=2)} entities can work just as well, -but only if the number of bytes occupied by the @code{CHARACTER} -entities is divisible by the recommended alignment for -@code{REAL(KIND=2)}. - -By ordering the placement of entities in aggregate -areas according to the simple guidelines above, you -avoid having to carefully count the number of bytes -occupied by each entity to determine whether the -actual alignment of each subsequent entity meets the -alignment guidelines for the type of that entity. - -If you don't ensure correct alignment of @code{COMMON} elements, the -compiler may be forced by some systems to violate the Fortran semantics by -adding padding to get @code{DOUBLE PRECISION} data properly aligned. -If the unfortunate practice is employed of overlaying different types of -data in the @code{COMMON} block, the different variants -of this block may become misaligned with respect to each other. -Even if your platform doesn't require strict alignment, -@code{COMMON} should be laid out as above for portability. -(Unfortunately the FORTRAN 77 standard didn't anticipate this -possible requirement, which is compiler-independent on a given platform.) - -@item -@cindex -malign-double option -@cindex options, -malign-double -Use the (x86-specific) @samp{-malign-double} option when compiling -programs for the Pentium and Pentium Pro architectures (called 586 -and 686 in the @code{gcc} configuration subsystem). -The warning about this in the @code{gcc} manual isn't -generally relevant to Fortran, -but using it will force @code{COMMON} to be padded if necessary to align -@code{DOUBLE PRECISION} data. - -When @code{DOUBLE PRECISION} data is forcibly aligned -in @code{COMMON} by @code{g77} due to specifying @samp{-malign-double}, -@code{g77} issues a warning about the need to -insert padding. - -In this case, each and every program unit that uses -the same @code{COMMON} area -must specify the same layout of variables and their types -for that area -and be compiled with @samp{-malign-double} as well. -@code{g77} will issue warnings in each case, -but as long as every program unit using that area -is compiled with the same warnings, -the resulting object files should work when linked together -unless the program makes additional assumptions about -@code{COMMON} area layouts that are outside the scope -of the FORTRAN 77 standard, -or uses @code{EQUIVALENCE} or different layouts -in ways that assume no padding is ever inserted by the compiler. - -@item -Ensure that @file{crt0.o} or @file{crt1.o} -on your system guarantees a 64-bit -aligned stack for @code{main()}. -The recent one from GNU (@code{glibc2}) will do this on x86 systems, -but we don't know of any other x86 setups where it will be right. -Read your system's documentation to determine if -it is appropriate to upgrade to a more recent version -to obtain the optimal alignment. -@end itemize - -Progress is being made on making this work -``out of the box'' on future versions of @code{g77}, -@code{gcc}, and some of the relevant operating systems -(such as GNU/Linux). - -@cindex alignment testing -@cindex testing alignment -A package that tests the degree to which a Fortran compiler -(such as @code{g77}) -aligns 64-bit floating-point variables and arrays -is available at @uref{ftp://alpha.gnu.org/gnu/g77/align/}. - -@node Prefer Automatic Uninitialized Variables -@subsection Prefer Automatic Uninitialized Variables - -If you're using @samp{-fno-automatic} already, you probably -should change your code to allow compilation with @samp{-fautomatic} -(the default), to allow the program to run faster. - -Similarly, you should be able to use @samp{-fno-init-local-zero} -(the default) instead of @samp{-finit-local-zero}. -This is because it is rare that every variable affected by these -options in a given program actually needs to -be so affected. - -For example, @samp{-fno-automatic}, which effectively @code{SAVE}s -every local non-automatic variable and array, affects even things like -@code{DO} iteration -variables, which rarely need to be @code{SAVE}d, and this often reduces -run-time performances. -Similarly, @samp{-fno-init-local-zero} forces such -variables to be initialized to zero---when @code{SAVE}d (such as when -@samp{-fno-automatic}), this by itself generally affects only -startup time for a program, but when not @code{SAVE}d, -it can slow down the procedure every time it is called. - -@xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, -for information on the @samp{-fno-automatic} and -@samp{-finit-local-zero} options and how to convert -their use into selective changes in your own code. - -@node Avoid f2c Compatibility -@subsection Avoid f2c Compatibility -@cindex -fno-f2c option -@cindex options, -fno-f2c -@cindex @code{f2c} compatibility -@cindex compatibility, @code{f2c} - -If you aren't linking with any code compiled using -@code{f2c}, try using the @samp{-fno-f2c} option when -compiling @emph{all} the code in your program. -(Note that @code{libf2c} is @emph{not} an example of code -that is compiled using @code{f2c}---it is compiled by a C -compiler, typically @code{gcc}.) - -@node Use Submodel Options -@subsection Use Submodel Options -@cindex submodels - -Using an appropriate @samp{-m} option to generate specific code for your -CPU may be worthwhile, though it may mean the executable won't run on -other versions of the CPU that don't support the same instruction set. -@xref{Submodel Options,,Hardware Models and Configurations,gcc,Using and -Porting GNU CC}. For instance on an x86 system the compiler might have -been built---as shown by @samp{g77 -v}---for the target -@samp{i386-pc-linux-gnu}, i.e.@: an @samp{i386} CPU@. In that case to -generate code best optimized for a Pentium you could use the option -@samp{-march=pentium}. - -For recent CPUs that don't have explicit support in the released version -of @code{gcc}, it @emph{might} still be possible to get improvements -with certain @samp{-m} options. - -@samp{-fomit-frame-pointer} can help performance on x86 systems and -others. It will, however, inhibit debugging on the systems on which it -is not turned on anyway by @samp{-O}. - -@node Trouble -@chapter Known Causes of Trouble with GNU Fortran -@cindex bugs, known -@cindex installation trouble -@cindex known causes of trouble - -This section describes known problems that affect users of GNU Fortran. -Most of these are not GNU Fortran bugs per se---if they were, we would -fix them. -But the result for a user might be like the result of a bug. - -Some of these problems are due to bugs in other software, some are -missing features that are too much work to add, and some are places -where people's opinions differ as to what is best. - -Information on bugs that show up when configuring, porting, building, -or installing @code{g77} is not provided here. -@xref{Problems Installing}. - -To find out about major bugs discovered in the current release and -possible workarounds for them, see -@uref{ftp://alpha.gnu.org/g77.plan}. - -(Note that some of this portion of the manual is lifted -directly from the @code{gcc} manual, with minor modifications -to tailor it to users of @code{g77}. -Anytime a bug seems to have more to do with the @code{gcc} -portion of @code{g77}, see -@ref{Trouble,,Known Causes of Trouble with GNU CC, -gcc,Using and Porting GNU CC}.) - -@menu -* But-bugs:: Bugs really in other programs or elsewhere. -* Known Bugs:: Bugs known to be in this version of @code{g77}. -* Missing Features:: Features we already know we want to add later. -* Disappointments:: Regrettable things we can't change. -* Non-bugs:: Things we think are right, but some others disagree. -* Warnings and Errors:: Which problems in your code get warnings, - and which get errors. -@end menu - -@node But-bugs -@section Bugs Not In GNU Fortran -@cindex but-bugs - -These are bugs to which the maintainers often have to reply, -``but that isn't a bug in @code{g77}@dots{}''. -Some of these already are fixed in new versions of other -software; some still need to be fixed; some are problems -with how @code{g77} is installed or is being used; -some are the result of bad hardware that causes software -to misbehave in sometimes bizarre ways; -some just cannot be addressed at this time until more -is known about the problem. - -Please don't re-report these bugs to the @code{g77} maintainers---if -you must remind someone how important it is to you that the problem -be fixed, talk to the people responsible for the other products -identified below, but preferably only after you've tried the -latest versions of those products. -The @code{g77} maintainers have their hands full working on -just fixing and improving @code{g77}, without serving as a -clearinghouse for all bugs that happen to affect @code{g77} -users. - -@xref{Collected Fortran Wisdom}, for information on behavior -of Fortran programs, and the programs that compile them, that -might be @emph{thought} to indicate bugs. - -@menu -* Signal 11 and Friends:: Strange behavior by any software. -* Cannot Link Fortran Programs:: Unresolved references. -* Large Common Blocks:: Problems on older GNU/Linux systems. -* Debugger Problems:: When the debugger crashes. -* NeXTStep Problems:: Misbehaving executables. -* Stack Overflow:: More misbehaving executables. -* Nothing Happens:: Less behaving executables. -* Strange Behavior at Run Time:: Executables misbehaving due to - bugs in your program. -* Floating-point Errors:: The results look wrong, but@dots{}. -@end menu - -@node Signal 11 and Friends -@subsection Signal 11 and Friends -@cindex signal 11 -@cindex hardware errors - -A whole variety of strange behaviors can occur when the -software, or the way you are using the software, -stresses the hardware in a way that triggers hardware bugs. -This might seem hard to believe, but it happens frequently -enough that there exist documents explaining in detail -what the various causes of the problems are, what -typical symptoms look like, and so on. - -Generally these problems are referred to in this document -as ``signal 11'' crashes, because the Linux kernel, running -on the most popular hardware (the Intel x86 line), often -stresses the hardware more than other popular operating -systems. -When hardware problems do occur under GNU/Linux on x86 -systems, these often manifest themselves as ``signal 11'' -problems, as illustrated by the following diagnostic: - -@smallexample -sh# @kbd{g77 myprog.f} -gcc: Internal compiler error: program f771 got fatal signal 11 -sh# -@end smallexample - -It is @emph{very} important to remember that the above -message is @emph{not} the only one that indicates a -hardware problem, nor does it always indicate a hardware -problem. - -In particular, on systems other than those running the Linux -kernel, the message might appear somewhat or very different, -as it will if the error manifests itself while running a -program other than the @code{g77} compiler. -For example, -it will appear somewhat different when running your program, -when running Emacs, and so on. - -How to cope with such problems is well beyond the scope -of this manual. - -However, users of Linux-based systems (such as GNU/Linux) -should review @uref{http://www.bitwizard.nl/sig11/}, a source -of detailed information on diagnosing hardware problems, -by recognizing their common symptoms. - -Users of other operating systems and hardware might -find this reference useful as well. -If you know of similar material for another hardware/software -combination, please let us know so we can consider including -a reference to it in future versions of this manual. - -@node Cannot Link Fortran Programs -@subsection Cannot Link Fortran Programs -@cindex unresolved reference (various) -@cindex linking error for user code -@cindex code, user -@cindex @code{ld}, error linking user code -@cindex @code{ld}, can't find strange names -On some systems, perhaps just those with out-of-date (shared?) -libraries, unresolved-reference errors happen when linking @code{g77}-compiled -programs (which should be done using @code{g77}). - -If this happens to you, try appending @samp{-lc} to the command you -use to link the program, e.g. @samp{g77 foo.f -lc}. -@code{g77} already specifies @samp{-lg2c -lm} when it calls the linker, -but it cannot also specify @samp{-lc} because not all systems have a -file named @file{libc.a}. - -It is unclear at this point whether there are legitimately installed -systems where @samp{-lg2c -lm} is insufficient to resolve code produced -by @code{g77}. - -@cindex undefined reference (_main) -@cindex linking error, user code -@cindex @code{ld}, error linking user code -@cindex code, user -@cindex @code{ld}, can't find @samp{_main} -If your program doesn't link due to unresolved references to names -like @samp{_main}, make sure you're using the @code{g77} command to do the -link, since this command ensures that the necessary libraries are -loaded by specifying @samp{-lg2c -lm} when it invokes the @code{gcc} -command to do the actual link. -(Use the @samp{-v} option to discover -more about what actually happens when you use the @code{g77} and @code{gcc} -commands.) - -Also, try specifying @samp{-lc} as the last item on the @code{g77} -command line, in case that helps. - -@node Large Common Blocks -@subsection Large Common Blocks -@cindex common blocks, large -@cindex large common blocks -@cindex linking, errors -@cindex @code{ld}, errors -@cindex errors, linker -On some older GNU/Linux systems, programs with common blocks larger -than 16MB cannot be linked without some kind of error -message being produced. - -This is a bug in older versions of @code{ld}, fixed in -more recent versions of @code{binutils}, such as version 2.6. - -@node Debugger Problems -@subsection Debugger Problems -@cindex @code{gdb}, support -@cindex support, @code{gdb} -There are some known problems when using @code{gdb} on code -compiled by @code{g77}. -Inadequate investigation as of the release of 0.5.16 results in not -knowing which products are the culprit, but @file{gdb-4.14} definitely -crashes when, for example, an attempt is made to print the contents -of a @code{COMPLEX(KIND=2)} dummy array, on at least some GNU/Linux -machines, plus some others. -Attempts to access assumed-size arrays are -also known to crash recent versions of @code{gdb}. -(@code{gdb}'s Fortran support was done for a different compiler -and isn't properly compatible with @code{g77}.) - -@node NeXTStep Problems -@subsection NeXTStep Problems -@cindex NeXTStep problems -@cindex bus error -@cindex segmentation violation -Developers of Fortran code on NeXTStep (all architectures) have to -watch out for the following problem when writing programs with -large, statically allocated (i.e. non-stack based) data structures -(common blocks, saved arrays). - -Due to the way the native loader (@file{/bin/ld}) lays out -data structures in virtual memory, it is very easy to create an -executable wherein the @samp{__DATA} segment overlaps (has addresses in -common) with the @samp{UNIX STACK} segment. - -This leads to all sorts of trouble, from the executable simply not -executing, to bus errors. -The NeXTStep command line tool @code{ebadexec} points to -the problem as follows: - -@smallexample -% @kbd{/bin/ebadexec a.out} -/bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000 -rounded size = 0x2a000) of executable file: a.out overlaps with UNIX -STACK segment (truncated address = 0x400000 rounded size = -0x3c00000) of executable file: a.out -@end smallexample - -(In the above case, it is the @samp{__LINKEDIT} segment that overlaps the -stack segment.) - -This can be cured by assigning the @samp{__DATA} segment -(virtual) addresses beyond the stack segment. -A conservative -estimate for this is from address 6000000 (hexadecimal) onwards---this -has always worked for me [Toon Moene]: - -@smallexample -% @kbd{g77 -segaddr __DATA 6000000 test.f} -% @kbd{ebadexec a.out} -ebadexec: file: a.out appears to be executable -% -@end smallexample - -Browsing through @file{@value{path-g77}/Makefile.in}, -you will find that the @code{f771} program itself also has to be -linked with these flags---it has large statically allocated -data structures. -(Version 0.5.18 reduces this somewhat, but probably -not enough.) - -(The above item was contributed by Toon Moene -(@email{toon@@moene.indiv.nluug.nl}).) - -@node Stack Overflow -@subsection Stack Overflow -@cindex stack, overflow -@cindex segmentation violation -@code{g77} code might fail at runtime (probably with a ``segmentation -violation'') due to overflowing the stack. -This happens most often on systems with an environment -that provides substantially more heap space (for use -when arbitrarily allocating and freeing memory) than stack -space. - -Often this can be cured by -increasing or removing your shell's limit on stack usage, typically -using @kbd{limit stacksize} (in @code{csh} and derivatives) or -@kbd{ulimit -s} (in @code{sh} and derivatives). - -Increasing the allowed stack size might, however, require -changing some operating system or system configuration parameters. - -You might be able to work around the problem by compiling with the -@samp{-fno-automatic} option to reduce stack usage, probably at the -expense of speed. - -@xref{Maximum Stackable Size}, for information on patching -@code{g77} to use different criteria for placing local -non-automatic variables and arrays on the stack. - -@cindex automatic arrays -@cindex arrays, automatic -However, if your program uses large automatic arrays -(for example, has declarations like @samp{REAL A(N)} where -@samp{A} is a local array and @samp{N} is a dummy or -@code{COMMON} variable that can have a large value), -neither use of @samp{-fno-automatic}, -nor changing the cut-off point for @code{g77} for using the stack, -will solve the problem by changing the placement of these -large arrays, as they are @emph{necessarily} automatic. - -@code{g77} currently provides no means to specify that -automatic arrays are to be allocated on the heap instead -of the stack. -So, other than increasing the stack size, your best bet is to -change your source code to avoid large automatic arrays. -Methods for doing this currently are outside the scope of -this document. - -(@emph{Note:} If your system puts stack and heap space in the -same memory area, such that they are effectively combined, then -a stack overflow probably indicates a program that is either -simply too large for the system, or buggy.) - -@node Nothing Happens -@subsection Nothing Happens -@cindex nothing happens -@cindex naming programs -@cindex @code{test} programs -@cindex programs, @code{test} -It is occasionally reported that a ``simple'' program, -such as a ``Hello, World!'' program, does nothing when -it is run, even though the compiler reported no errors, -despite the program containing nothing other than a -simple @code{PRINT} statement. - -This most often happens because the program has been -compiled and linked on a UNIX system and named @code{test}, -though other names can lead to similarly unexpected -run-time behavior on various systems. - -Essentially this problem boils down to giving -your program a name that is already known to -the shell you are using to identify some other program, -which the shell continues to execute instead of your -program when you invoke it via, for example: - -@smallexample -sh# @kbd{test} -sh# -@end smallexample - -Under UNIX and many other system, a simple command name -invokes a searching mechanism that might well not choose -the program located in the current working directory if -there is another alternative (such as the @code{test} -command commonly installed on UNIX systems). - -The reliable way to invoke a program you just linked in -the current directory under UNIX is to specify it using -an explicit pathname, as in: - -@smallexample -sh# @kbd{./test} - Hello, World! -sh# -@end smallexample - -Users who encounter this problem should take the time to -read up on how their shell searches for commands, how to -set their search path, and so on. -The relevant UNIX commands to learn about include -@code{man}, @code{info} (on GNU systems), @code{setenv} (or -@code{set} and @code{env}), @code{which}, and @code{find}. - -@node Strange Behavior at Run Time -@subsection Strange Behavior at Run Time -@cindex segmentation violation -@cindex bus error -@cindex overwritten data -@cindex data, overwritten -@code{g77} code might fail at runtime with ``segmentation violation'', -``bus error'', or even something as subtle as a procedure call -overwriting a variable or array element that it is not supposed -to touch. - -These can be symptoms of a wide variety of actual bugs that -occurred earlier during the program's run, but manifested -themselves as @emph{visible} problems some time later. - -Overflowing the bounds of an array---usually by writing beyond -the end of it---is one of two kinds of bug that often occurs -in Fortran code. -(Compile your code with the @samp{-fbounds-check} option -to catch many of these kinds of errors at program run time.) - -The other kind of bug is a mismatch between the actual arguments -passed to a procedure and the dummy arguments as declared by that -procedure. - -Both of these kinds of bugs, and some others as well, can be -difficult to track down, because the bug can change its behavior, -or even appear to not occur, when using a debugger. - -That is, these bugs can be quite sensitive to data, including -data representing the placement of other data in memory (that is, -pointers, such as the placement of stack frames in memory). - -@code{g77} now offers the -ability to catch and report some of these problems at compile, link, or -run time, such as by generating code to detect references to -beyond the bounds of most arrays (except assumed-size arrays), -and checking for agreement between calling and called procedures. -Future improvements are likely to be made in the procedure-mismatch area, -at least. - -In the meantime, finding and fixing the programming -bugs that lead to these behaviors is, ultimately, the user's -responsibility, as difficult as that task can sometimes be. - -@cindex infinite spaces printed -@cindex space, endless printing of -@cindex libc, non-ANSI or non-default -@cindex C library -@cindex linking against non-standard library -@cindex Solaris -One runtime problem that has been observed might have a simple solution. -If a formatted @code{WRITE} produces an endless stream of spaces, check -that your program is linked against the correct version of the C library. -The configuration process takes care to account for your -system's normal @file{libc} not being ANSI-standard, which will -otherwise cause this behaviour. -If your system's default library is -ANSI-standard and you subsequently link against a non-ANSI one, there -might be problems such as this one. - -Specifically, on Solaris2 systems, -avoid picking up the @code{BSD} library from @file{/usr/ucblib}. - -@node Floating-point Errors -@subsection Floating-point Errors -@cindex floating-point errors -@cindex rounding errors -@cindex inconsistent floating-point results -@cindex results, inconsistent -Some programs appear to produce inconsistent floating-point -results compiled by @code{g77} versus by other compilers. - -Often the reason for this behavior is the fact that floating-point -values are represented on almost all Fortran systems by -@emph{approximations}, and these approximations are inexact -even for apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6, -0.7, 0.8, 0.9, 1.1, and so on. -Most Fortran systems, including all current ports of @code{g77}, -use binary arithmetic to represent these approximations. - -Therefore, the exact value of any floating-point approximation -as manipulated by @code{g77}-compiled code is representable by -adding some combination of the values 1.0, 0.5, 0.25, 0.125, and -so on (just keep dividing by two) through the precision of the -fraction (typically around 23 bits for @code{REAL(KIND=1)}, 52 for -@code{REAL(KIND=2)}), then multiplying the sum by a integral -power of two (in Fortran, by @samp{2**N}) that typically is between --127 and +128 for @code{REAL(KIND=1)} and -1023 and +1024 for -@code{REAL(KIND=2)}, then multiplying by -1 if the number -is negative. - -So, a value like 0.2 is exactly represented in decimal---since -it is a fraction, @samp{2/10}, with a denominator that is compatible -with the base of the number system (base 10). -However, @samp{2/10} cannot be represented by any finite number -of sums of any of 1.0, 0.5, 0.25, and so on, so 0.2 cannot -be exactly represented in binary notation. - -(On the other hand, decimal notation can represent any binary -number in a finite number of digits. -Decimal notation cannot do so with ternary, or base-3, -notation, which would represent floating-point numbers as -sums of any of @samp{1/1}, @samp{1/3}, @samp{1/9}, and so on. -After all, no finite number of decimal digits can exactly -represent @samp{1/3}. -Fortunately, few systems use ternary notation.) - -Moreover, differences in the way run-time I/O libraries convert -between these approximations and the decimal representation often -used by programmers and the programs they write can result in -apparent differences between results that do not actually exist, -or exist to such a small degree that they usually are not worth -worrying about. - -For example, consider the following program: - -@smallexample -PRINT *, 0.2 -END -@end smallexample - -When compiled by @code{g77}, the above program might output -@samp{0.20000003}, while another compiler might produce a -executable that outputs @samp{0.2}. - -This particular difference is due to the fact that, currently, -conversion of floating-point values by the @code{libg2c} library, -used by @code{g77}, handles only double-precision values. - -Since @samp{0.2} in the program is a single-precision value, it -is converted to double precision (still in binary notation) -before being converted back to decimal. -The conversion to binary appends @emph{binary} zero digits to the -original value---which, again, is an inexact approximation of -0.2---resulting in an approximation that is much less exact -than is connoted by the use of double precision. - -(The appending of binary zero digits has essentially the same -effect as taking a particular decimal approximation of -@samp{1/3}, such as @samp{0.3333333}, and appending decimal -zeros to it, producing @samp{0.33333330000000000}. -Treating the resulting decimal approximation as if it really -had 18 or so digits of valid precision would make it seem -a very poor approximation of @samp{1/3}.) - -As a result of converting the single-precision approximation -to double precision by appending binary zeros, the conversion -of the resulting double-precision -value to decimal produces what looks like an incorrect -result, when in fact the result is @emph{inexact}, and -is probably no less inaccurate or imprecise an approximation -of 0.2 than is produced by other compilers that happen to output -the converted value as ``exactly'' @samp{0.2}. -(Some compilers behave in a way that can make them appear -to retain more accuracy across a conversion of a single-precision -constant to double precision. -@xref{Context-Sensitive Constants}, to see why -this practice is illusory and even dangerous.) - -Note that a more exact approximation of the constant is -computed when the program is changed to specify a -double-precision constant: - -@smallexample -PRINT *, 0.2D0 -END -@end smallexample - -Future versions of @code{g77} and/or @code{libg2c} might convert -single-precision values directly to decimal, -instead of converting them to double precision first. -This would tend to result in output that is more consistent -with that produced by some other Fortran implementations. - -A useful source of information on floating-point computation is David -Goldberg, `What Every Computer Scientist Should Know About -Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp.@: -5-48. -An online version is available at -@uref{http://docs.sun.com/}, -and there is a supplemented version, in PostScript form, at -@uref{http://www.validgh.com/goldberg/paper.ps}. - -Information related to the IEEE 754 -floating-point standard by a leading light can be found at -@uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/}; -see also slides from the short course referenced from -@uref{http://http.cs.berkeley.edu/%7Efateman/}. -@uref{http://www.linuxsupportline.com/%7Ebillm/} has a brief -guide to IEEE 754, a somewhat x86-GNU/Linux-specific FAQ, -and library code for GNU/Linux x86 systems. - -The supplement to the PostScript-formatted Goldberg document, -referenced above, is available in HTML format. -See `Differences Among IEEE 754 Implementations' by Doug Priest, -available online at -@uref{http://www.validgh.com/goldberg/addendum.html}. -This document explores some of the issues surrounding computing -of extended (80-bit) results on processors such as the x86, -especially when those results are arbitrarily truncated -to 32-bit or 64-bit values by the compiler -as ``spills''. - -@cindex spills of floating-point results -@cindex 80-bit spills -@cindex truncation, of floating-point values -(@emph{Note:} @code{g77} specifically, and @code{gcc} generally, -does arbitrarily truncate 80-bit results during spills -as of this writing. -It is not yet clear whether a future version of -the GNU compiler suite will offer 80-bit spills -as an option, or perhaps even as the default behavior.) - -@c xref would be different between editions: -The GNU C library provides routines for controlling the FPU, and other -documentation about this. - -@xref{Floating-point precision}, regarding IEEE 754 conformance. - -@include bugs.texi - -@node Missing Features -@section Missing Features - -This section lists features we know are missing from @code{g77}, -and which we want to add someday. -(There is no priority implied in the ordering below.) - -@menu -GNU Fortran language: -* Better Source Model:: -* Fortran 90 Support:: -* Intrinsics in PARAMETER Statements:: -* Arbitrary Concatenation:: -* SELECT CASE on CHARACTER Type:: -* RECURSIVE Keyword:: -* Popular Non-standard Types:: -* Full Support for Compiler Types:: -* Array Bounds Expressions:: -* POINTER Statements:: -* Sensible Non-standard Constructs:: -* READONLY Keyword:: -* FLUSH Statement:: -* Expressions in FORMAT Statements:: -* Explicit Assembler Code:: -* Q Edit Descriptor:: - -GNU Fortran dialects: -* Old-style PARAMETER Statements:: -* TYPE and ACCEPT I/O Statements:: -* STRUCTURE UNION RECORD MAP:: -* OPEN CLOSE and INQUIRE Keywords:: -* ENCODE and DECODE:: -* AUTOMATIC Statement:: -* Suppressing Space Padding:: -* Fortran Preprocessor:: -* Bit Operations on Floating-point Data:: -* Really Ugly Character Assignments:: - -New facilities: -* POSIX Standard:: -* Floating-point Exception Handling:: -* Nonportable Conversions:: -* Large Automatic Arrays:: -* Support for Threads:: -* Increasing Precision/Range:: -* Enabling Debug Lines:: - -Better diagnostics: -* Better Warnings:: -* Gracefully Handle Sensible Bad Code:: -* Non-standard Conversions:: -* Non-standard Intrinsics:: -* Modifying DO Variable:: -* Better Pedantic Compilation:: -* Warn About Implicit Conversions:: -* Invalid Use of Hollerith Constant:: -* Dummy Array Without Dimensioning Dummy:: -* Invalid FORMAT Specifiers:: -* Ambiguous Dialects:: -* Unused Labels:: -* Informational Messages:: - -Run-time facilities: -* Uninitialized Variables at Run Time:: -* Portable Unformatted Files:: -* Better List-directed I/O:: -* Default to Console I/O:: - -Debugging: -* Labels Visible to Debugger:: -@end menu - -@node Better Source Model -@subsection Better Source Model - -@code{g77} needs to provide, as the default source-line model, -a ``pure visual'' mode, where -the interpretation of a source program in this mode can be accurately -determined by a user looking at a traditionally displayed rendition -of the program (assuming the user knows whether the program is fixed -or free form). - -The design should assume the user cannot tell tabs from spaces -and cannot see trailing spaces on lines, but has canonical tab stops -and, for fixed-form source, has the ability to always know exactly -where column 72 is (since the Fortran standard itself requires -this for fixed-form source). - -This would change the default treatment of fixed-form source -to not treat lines with tabs as if they were infinitely long---instead, -they would end at column 72 just as if the tabs were replaced -by spaces in the canonical way. - -As part of this, provide common alternate models (Digital, @code{f2c}, -and so on) via command-line options. -This includes allowing arbitrarily long -lines for free-form source as well as fixed-form source and providing -various limits and diagnostics as appropriate. - -@cindex sequence numbers -@cindex columns 73 through 80 -Also, @code{g77} should offer, perhaps even default to, warnings -when characters beyond the last valid column are anything other -than spaces. -This would mean code with ``sequence numbers'' in columns 73 through 80 -would be rejected, and there's a lot of that kind of code around, -but one of the most frequent bugs encountered by new users is -accidentally writing fixed-form source code into and beyond -column 73. -So, maybe the users of old code would be able to more easily handle -having to specify, say, a @samp{-Wno-col73to80} option. - -@node Fortran 90 Support -@subsection Fortran 90 Support -@cindex Fortran 90, support -@cindex support, Fortran 90 - -@code{g77} does not support many of the features that -distinguish Fortran 90 (and, now, Fortran 95) from -ANSI FORTRAN 77. - -Some Fortran 90 features are supported, because they -make sense to offer even to die-hard users of F77. -For example, many of them codify various ways F77 has -been extended to meet users' needs during its tenure, -so @code{g77} might as well offer them as the primary -way to meet those same needs, even if it offers compatibility -with one or more of the ways those needs were met -by other F77 compilers in the industry. - -Still, many important F90 features are not supported, -because no attempt has been made to research each and -every feature and assess its viability in @code{g77}. -In the meantime, users who need those features must -use Fortran 90 compilers anyway, and the best approach -to adding some F90 features to GNU Fortran might well be -to fund a comprehensive project to create GNU Fortran 95. - -@node Intrinsics in PARAMETER Statements -@subsection Intrinsics in @code{PARAMETER} Statements -@cindex PARAMETER statement -@cindex statements, PARAMETER - -@code{g77} doesn't allow intrinsics in @code{PARAMETER} statements. -This feature is considered to be absolutely vital, even though it -is not standard-conforming, and is scheduled for version 0.6. - -Related to this, @code{g77} doesn't allow non-integral -exponentiation in @code{PARAMETER} statements, such as -@samp{PARAMETER (R=2**.25)}. -It is unlikely @code{g77} will ever support this feature, -as doing it properly requires complete emulation of -a target computer's floating-point facilities when -building @code{g77} as a cross-compiler. -But, if the @code{gcc} back end is enhanced to provide -such a facility, @code{g77} will likely use that facility -in implementing this feature soon afterwards. - -@node Arbitrary Concatenation -@subsection Arbitrary Concatenation -@cindex concatenation -@cindex CHARACTER*(*) -@cindex run-time, dynamic allocation - -@code{g77} doesn't support arbitrary operands for concatenation -in contexts where run-time allocation is required. -For example: - -@smallexample -SUBROUTINE X(A) -CHARACTER*(*) A -CALL FOO(A // 'suffix') -@end smallexample - -@node SELECT CASE on CHARACTER Type -@subsection @code{SELECT CASE} on @code{CHARACTER} Type - -Character-type selector/cases for @code{SELECT CASE} currently -are not supported. - -@node RECURSIVE Keyword -@subsection @code{RECURSIVE} Keyword -@cindex RECURSIVE keyword -@cindex keywords, RECURSIVE -@cindex recursion, lack of -@cindex lack of recursion - -@code{g77} doesn't support the @code{RECURSIVE} keyword that -F90 compilers do. -Nor does it provide any means for compiling procedures -designed to do recursion. - -All recursive code can be rewritten to not use recursion, -but the result is not pretty. - -@node Increasing Precision/Range -@subsection Increasing Precision/Range -@cindex -r8 -@cindex -qrealsize=8 -@cindex -i8 -@cindex f2c -@cindex increasing precision -@cindex precision, increasing -@cindex increasing range -@cindex range, increasing -@cindex Toolpack -@cindex Netlib - -Some compilers, such as @code{f2c}, have an option (@samp{-r8}, -@samp{-qrealsize=8} or -similar) that provides automatic treatment of @code{REAL} -entities such that they have twice the storage size, and -a corresponding increase in the range and precision, of what -would normally be the @code{REAL(KIND=1)} (default @code{REAL}) type. -(This affects @code{COMPLEX} the same way.) - -They also typically offer another option (@samp{-i8}) to increase -@code{INTEGER} entities so they are twice as large -(with roughly twice as much range). - -(There are potential pitfalls in using these options.) - -@code{g77} does not yet offer any option that performs these -kinds of transformations. -Part of the problem is the lack of detailed specifications regarding -exactly how these options affect the interpretation of constants, -intrinsics, and so on. - -Until @code{g77} addresses this need, programmers could improve -the portability of their code by modifying it to not require -compile-time options to produce correct results. -Some free tools are available which may help, specifically -in Toolpack (which one would expect to be sound) and the @file{fortran} -section of the Netlib repository. - -Use of preprocessors can provide a fairly portable means -to work around the lack of widely portable methods in the Fortran -language itself (though increasing acceptance of Fortran 90 would -alleviate this problem). - -@node Popular Non-standard Types -@subsection Popular Non-standard Types -@cindex @code{INTEGER*2} support -@cindex types, @code{INTEGER*2} -@cindex @code{LOGICAL*1} support -@cindex types, @code{LOGICAL*1} - -@code{g77} doesn't fully support @code{INTEGER*2}, @code{LOGICAL*1}, -and similar. -Version 0.6 will provide full support for this very -popular set of features. -In the meantime, version 0.5.18 provides rudimentary support -for them. - -@node Full Support for Compiler Types -@subsection Full Support for Compiler Types - -@cindex @code{REAL*16} support -@cindex types, @code{REAL*16} -@cindex @code{INTEGER*8} support -@cindex types, @code{INTEGER*8} -@code{g77} doesn't support @code{INTEGER}, @code{REAL}, and @code{COMPLEX} equivalents -for @emph{all} applicable back-end-supported types (@code{char}, @code{short int}, -@code{int}, @code{long int}, @code{long long int}, and @code{long double}). -This means providing intrinsic support, and maybe constant -support (using F90 syntax) as well, and, for most -machines will result in automatic support of @code{INTEGER*1}, -@code{INTEGER*2}, @code{INTEGER*8}, maybe even @code{REAL*16}, -and so on. -This is scheduled for version 0.6. - -@node Array Bounds Expressions -@subsection Array Bounds Expressions -@cindex array elements, in adjustable array bounds -@cindex function references, in adjustable array bounds -@cindex array bounds, adjustable -@cindex @code{DIMENSION} statement -@cindex statements, @code{DIMENSION} - -@code{g77} doesn't support more general expressions to dimension -arrays, such as array element references, function -references, etc. - -For example, @code{g77} currently does not accept the following: - -@smallexample -SUBROUTINE X(M, N) -INTEGER N(10), M(N(2), N(1)) -@end smallexample - -@node POINTER Statements -@subsection POINTER Statements -@cindex POINTER statement -@cindex statements, POINTER -@cindex Cray pointers - -@code{g77} doesn't support pointers or allocatable objects -(other than automatic arrays). -This set of features is -probably considered just behind intrinsics -in @code{PARAMETER} statements on the list of large, -important things to add to @code{g77}. - -In the meantime, consider using the @code{INTEGER(KIND=7)} -declaration to specify that a variable must be -able to hold a pointer. -This construct is not portable to other non-GNU compilers, -but it is portable to all machines GNU Fortran supports -when @code{g77} is used. - -@xref{Functions and Subroutines}, for information on -@code{%VAL()}, @code{%REF()}, and @code{%DESCR()} -constructs, which are useful for passing pointers to -procedures written in languages other than Fortran. - -@node Sensible Non-standard Constructs -@subsection Sensible Non-standard Constructs - -@code{g77} rejects things other compilers accept, -like @samp{INTRINSIC SQRT,SQRT}. -As time permits in the future, some of these things that are easy for -humans to read and write and unlikely to be intended to mean something -else will be accepted by @code{g77} (though @samp{-fpedantic} should -trigger warnings about such non-standard constructs). - -Until @code{g77} no longer gratuitously rejects sensible code, -you might as well fix your code -to be more standard-conforming and portable. - -The kind of case that is important to except from the -recommendation to change your code is one where following -good coding rules would force you to write non-standard -code that nevertheless has a clear meaning. - -For example, when writing an @code{INCLUDE} file that -defines a common block, it might be appropriate to -include a @code{SAVE} statement for the common block -(such as @samp{SAVE /CBLOCK/}), so that variables -defined in the common block retain their values even -when all procedures declaring the common block become -inactive (return to their callers). - -However, putting @code{SAVE} statements in an @code{INCLUDE} -file would prevent otherwise standard-conforming code -from also specifying the @code{SAVE} statement, by itself, -to indicate that all local variables and arrays are to -have the @code{SAVE} attribute. - -For this reason, @code{g77} already has been changed to -allow this combination, because although the general -problem of gratuitously rejecting unambiguous and -``safe'' constructs still exists in @code{g77}, this -particular construct was deemed useful enough that -it was worth fixing @code{g77} for just this case. - -So, while there is no need to change your code -to avoid using this particular construct, there -might be other, equally appropriate but non-standard -constructs, that you shouldn't have to stop using -just because @code{g77} (or any other compiler) -gratuitously rejects it. - -Until the general problem is solved, if you have -any such construct you believe is worthwhile -using (e.g. not just an arbitrary, redundant -specification of an attribute), please submit a -bug report with an explanation, so we can consider -fixing @code{g77} just for cases like yours. - -@node READONLY Keyword -@subsection @code{READONLY} Keyword -@cindex READONLY - -Support for @code{READONLY}, in @code{OPEN} statements, -requires @code{libg2c} support, -to make sure that @samp{CLOSE(@dots{},STATUS='DELETE')} -does not delete a file opened on a unit -with the @code{READONLY} keyword, -and perhaps to trigger a fatal diagnostic -if a @code{WRITE} or @code{PRINT} -to such a unit is attempted. - -@emph{Note:} It is not sufficient for @code{g77} and @code{libg2c} -(its version of @code{libf2c}) -to assume that @code{READONLY} does not need some kind of explicit support -at run time, -due to UNIX systems not (generally) needing it. -@code{g77} is not just a UNIX-based compiler! - -Further, mounting of non-UNIX filesystems on UNIX systems -(such as via NFS) -might require proper @code{READONLY} support. - -@cindex SHARED -(Similar issues might be involved with supporting the @code{SHARED} -keyword.) - -@node FLUSH Statement -@subsection @code{FLUSH} Statement - -@code{g77} could perhaps use a @code{FLUSH} statement that -does what @samp{CALL FLUSH} does, -but that supports @samp{*} as the unit designator (same unit as for -@code{PRINT}) and accepts @code{ERR=} and/or @code{IOSTAT=} -specifiers. - -@node Expressions in FORMAT Statements -@subsection Expressions in @code{FORMAT} Statements -@cindex FORMAT statement -@cindex statements, FORMAT - -@code{g77} doesn't support @samp{FORMAT(I<J>)} and the like. -Supporting this requires a significant redesign or replacement -of @code{libg2c}. - -However, @code{g77} does support -this construct when the expression is constant -(as of version 0.5.22). -For example: - -@smallexample - PARAMETER (IWIDTH = 12) -10 FORMAT (I<IWIDTH>) -@end smallexample - -Otherwise, at least for output (@code{PRINT} and -@code{WRITE}), Fortran code making use of this feature can -be rewritten to avoid it by constructing the @code{FORMAT} -string in a @code{CHARACTER} variable or array, then -using that variable or array in place of the @code{FORMAT} -statement label to do the original @code{PRINT} or @code{WRITE}. - -Many uses of this feature on input can be rewritten this way -as well, but not all can. -For example, this can be rewritten: - -@smallexample - READ 20, I -20 FORMAT (I<J>) -@end smallexample - -However, this cannot, in general, be rewritten, especially -when @code{ERR=} and @code{END=} constructs are employed: - -@smallexample - READ 30, J, I -30 FORMAT (I<J>) -@end smallexample - -@node Explicit Assembler Code -@subsection Explicit Assembler Code - -@code{g77} needs to provide some way, a la @code{gcc}, for @code{g77} -code to specify explicit assembler code. - -@node Q Edit Descriptor -@subsection Q Edit Descriptor -@cindex FORMAT statement -@cindex Q edit descriptor -@cindex edit descriptor, Q - -The @code{Q} edit descriptor in @code{FORMAT}s isn't supported. -(This is meant to get the number of characters remaining in an input record.) -Supporting this requires a significant redesign or replacement -of @code{libg2c}. - -A workaround might be using internal I/O or the stream-based intrinsics. -@xref{FGetC Intrinsic (subroutine)}. - -@node Old-style PARAMETER Statements -@subsection Old-style PARAMETER Statements -@cindex PARAMETER statement -@cindex statements, PARAMETER - -@code{g77} doesn't accept @samp{PARAMETER I=1}. -Supporting this obsolete form of -the @code{PARAMETER} statement would not be particularly hard, as most of the -parsing code is already in place and working. - -Until time/money is -spent implementing it, you might as well fix your code to use the -standard form, @samp{PARAMETER (I=1)} (possibly needing -@samp{INTEGER I} preceding the @code{PARAMETER} statement as well, -otherwise, in the obsolete form of @code{PARAMETER}, the -type of the variable is set from the type of the constant being -assigned to it). - -@node TYPE and ACCEPT I/O Statements -@subsection @code{TYPE} and @code{ACCEPT} I/O Statements -@cindex TYPE statement -@cindex statements, TYPE -@cindex ACCEPT statement -@cindex statements, ACCEPT - -@code{g77} doesn't support the I/O statements @code{TYPE} and -@code{ACCEPT}. -These are common extensions that should be easy to support, -but also are fairly easy to work around in user code. - -Generally, any @samp{TYPE fmt,list} I/O statement can be replaced -by @samp{PRINT fmt,list}. -And, any @samp{ACCEPT fmt,list} statement can be -replaced by @samp{READ fmt,list}. - -@node STRUCTURE UNION RECORD MAP -@subsection @code{STRUCTURE}, @code{UNION}, @code{RECORD}, @code{MAP} -@cindex STRUCTURE statement -@cindex statements, STRUCTURE -@cindex UNION statement -@cindex statements, UNION -@cindex RECORD statement -@cindex statements, RECORD -@cindex MAP statement -@cindex statements, MAP - -@code{g77} doesn't support @code{STRUCTURE}, @code{UNION}, @code{RECORD}, -@code{MAP}. -This set of extensions is quite a bit -lower on the list of large, important things to add to @code{g77}, partly -because it requires a great deal of work either upgrading or -replacing @code{libg2c}. - -@node OPEN CLOSE and INQUIRE Keywords -@subsection @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} Keywords -@cindex disposition of files -@cindex OPEN statement -@cindex statements, OPEN -@cindex CLOSE statement -@cindex statements, CLOSE -@cindex INQUIRE statement -@cindex statements, INQUIRE - -@code{g77} doesn't have support for keywords such as @code{DISP='DELETE'} in -the @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} statements. -These extensions are easy to add to @code{g77} itself, but -require much more work on @code{libg2c}. - -@cindex FORM='PRINT' -@cindex ANS carriage control -@cindex carriage control -@pindex asa -@pindex fpr -@code{g77} doesn't support @code{FORM='PRINT'} or an equivalent to -translate the traditional `carriage control' characters in column 1 of -output to use backspaces, carriage returns and the like. However -programs exist to translate them in output files (or standard output). -These are typically called either @code{fpr} or @code{asa}. You can get -a version of @code{asa} from -@uref{ftp://sunsite.unc.edu/pub/Linux/devel/lang/fortran} for GNU -systems which will probably build easily on other systems. -Alternatively, @code{fpr} is in BSD distributions in various archive -sites. - -@c (Can both programs can be used in a pipeline, -@c with a named input file, -@c and/or with a named output file???) - -@node ENCODE and DECODE -@subsection @code{ENCODE} and @code{DECODE} -@cindex ENCODE statement -@cindex statements, ENCODE -@cindex DECODE statement -@cindex statements, DECODE - -@code{g77} doesn't support @code{ENCODE} or @code{DECODE}. - -These statements are best replaced by READ and WRITE statements -involving internal files (CHARACTER variables and arrays). - -For example, replace a code fragment like - -@smallexample - INTEGER*1 LINE(80) -@dots{} - DECODE (80, 9000, LINE) A, B, C -@dots{} -9000 FORMAT (1X, 3(F10.5)) -@end smallexample - -@noindent -with: - -@smallexample - CHARACTER*80 LINE -@dots{} - READ (UNIT=LINE, FMT=9000) A, B, C -@dots{} -9000 FORMAT (1X, 3(F10.5)) -@end smallexample - -Similarly, replace a code fragment like - -@smallexample - INTEGER*1 LINE(80) -@dots{} - ENCODE (80, 9000, LINE) A, B, C -@dots{} -9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) -@end smallexample - -@noindent -with: - -@smallexample - CHARACTER*80 LINE -@dots{} - WRITE (UNIT=LINE, FMT=9000) A, B, C -@dots{} -9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) -@end smallexample - -It is entirely possible that @code{ENCODE} and @code{DECODE} will -be supported by a future version of @code{g77}. - -@node AUTOMATIC Statement -@subsection @code{AUTOMATIC} Statement -@cindex @code{AUTOMATIC} statement -@cindex statements, @code{AUTOMATIC} -@cindex automatic variables -@cindex variables, automatic - -@code{g77} doesn't support the @code{AUTOMATIC} statement that -@code{f2c} does. - -@code{AUTOMATIC} would identify a variable or array -as not being @code{SAVE}'d, which is normally the default, -but which would be especially useful for code that, @emph{generally}, -needed to be compiled with the @samp{-fno-automatic} option. - -@code{AUTOMATIC} also would serve as a hint to the compiler that placing -the variable or array---even a very large array--on the stack is acceptable. - -@code{AUTOMATIC} would not, by itself, designate the containing procedure -as recursive. - -@code{AUTOMATIC} should work syntactically like @code{SAVE}, -in that @code{AUTOMATIC} with no variables listed should apply to -all pertinent variables and arrays -(which would not include common blocks or their members). - -Variables and arrays denoted as @code{AUTOMATIC} -would not be permitted to be initialized via @code{DATA} -or other specification of any initial values, -requiring explicit initialization, -such as via assignment statements. - -@cindex UNSAVE -@cindex STATIC -Perhaps @code{UNSAVE} and @code{STATIC}, -as strict semantic opposites to @code{SAVE} and @code{AUTOMATIC}, -should be provided as well. - -@node Suppressing Space Padding -@subsection Suppressing Space Padding of Source Lines - -@code{g77} should offer VXT-Fortran-style suppression of virtual -spaces at the end of a source line -if an appropriate command-line option is specified. - -This affects cases where -a character constant is continued onto the next line in a fixed-form -source file, as in the following example: - -@smallexample -10 PRINT *,'HOW MANY - 1 SPACES?' -@end smallexample - -@noindent -@code{g77}, and many other compilers, virtually extend -the continued line through column 72 with spaces that become part -of the character constant, but Digital Fortran normally didn't, -leaving only one space between @samp{MANY} and @samp{SPACES?} -in the output of the above statement. - -Fairly recently, at least one version of Digital Fortran -was enhanced to provide the other behavior when a -command-line option is specified, apparently due to demand -from readers of the USENET group @file{comp.lang.fortran} -to offer conformance to this widespread practice in the -industry. -@code{g77} should return the favor by offering conformance -to Digital's approach to handling the above example. - -@node Fortran Preprocessor -@subsection Fortran Preprocessor - -@code{g77} should offer a preprocessor designed specifically -for Fortran to replace @samp{cpp -traditional}. -There are several out there worth evaluating, at least. - -Such a preprocessor would recognize Hollerith constants, -properly parse comments and character constants, and so on. -It might also recognize, process, and thus preprocess -files included via the @code{INCLUDE} directive. - -@node Bit Operations on Floating-point Data -@subsection Bit Operations on Floating-point Data -@cindex @code{And} intrinsic -@cindex intrinsics, @code{And} -@cindex @code{Or} intrinsic -@cindex intrinsics, @code{Or} -@cindex @code{Shift} intrinsic -@cindex intrinsics, @code{Shift} - -@code{g77} does not allow @code{REAL} and other non-integral types for -arguments to intrinsics like @code{And}, @code{Or}, and @code{Shift}. - -For example, this program is rejected by @code{g77}, because -the intrinsic @code{Iand} does not accept @code{REAL} arguments: - -@smallexample -DATA A/7.54/, B/9.112/ -PRINT *, IAND(A, B) -END -@end smallexample - -@node Really Ugly Character Assignments -@subsection Really Ugly Character Assignments - -An option such as @samp{-fugly-char} should be provided -to allow - -@smallexample -REAL*8 A1 -DATA A1 / '12345678' / -@end smallexample - -and: - -@smallexample -REAL*8 A1 -A1 = 'ABCDEFGH' -@end smallexample - -@node POSIX Standard -@subsection @code{POSIX} Standard - -@code{g77} should support the POSIX standard for Fortran. - -@node Floating-point Exception Handling -@subsection Floating-point Exception Handling -@cindex floating-point, exceptions -@cindex exceptions, floating-point -@cindex FPE handling -@cindex NaN values - -The @code{gcc} backend and, consequently, @code{g77}, currently provides no -general control over whether or not floating-point exceptions are trapped or -ignored. -(Ignoring them typically results in NaN values being -propagated in systems that conform to IEEE 754.) -The behaviour is normally inherited from the system-dependent startup -code, though some targets, such as the Alpha, have code generation -options which change the behaviour. - -Most systems provide some C-callable mechanism to change this; this can -be invoked at startup using @code{gcc}'s @code{constructor} attribute. -For example, just compiling and linking the following C code with your -program will turn on exception trapping for the ``common'' exceptions -on an x86-based GNU system: - -@smallexample -#include <fpu_control.h> -static void __attribute__ ((constructor)) -trapfpe () -@{ - __setfpucw (_FPU_DEFAULT & - ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM)); -@} -@end smallexample - -A convenient trick is to compile this something like: -@smallexample -gcc -o libtrapfpe.a trapfpe.c -@end smallexample -and then use it by adding @samp{-trapfpe} to the @code{g77} command line -when linking. - -@node Nonportable Conversions -@subsection Nonportable Conversions -@cindex nonportable conversions -@cindex conversions, nonportable - -@code{g77} doesn't accept some particularly nonportable, -silent data-type conversions such as @code{LOGICAL} -to @code{REAL} (as in @samp{A=.FALSE.}, where @samp{A} -is type @code{REAL}), that other compilers might -quietly accept. - -Some of these conversions are accepted by @code{g77} -when the @samp{-fugly-logint} option is specified. -Perhaps it should accept more or all of them. - -@node Large Automatic Arrays -@subsection Large Automatic Arrays -@cindex automatic arrays -@cindex arrays, automatic - -Currently, automatic arrays always are allocated on the stack. -For situations where the stack cannot be made large enough, -@code{g77} should offer a compiler option that specifies -allocation of automatic arrays in heap storage. - -@node Support for Threads -@subsection Support for Threads -@cindex threads -@cindex parallel processing - -Neither the code produced by @code{g77} nor the @code{libg2c} library -are thread-safe, nor does @code{g77} have support for parallel processing -(other than the instruction-level parallelism available on some -processors). -A package such as PVM might help here. - -@node Enabling Debug Lines -@subsection Enabling Debug Lines -@cindex debug line -@cindex comment line, debug - -An option such as @samp{-fdebug-lines} should be provided -to turn fixed-form lines beginning with @samp{D} -to be treated as if they began with a space, -instead of as if they began with a @samp{C} -(as comment lines). - -@node Better Warnings -@subsection Better Warnings - -Because of how @code{g77} generates code via the back end, -it doesn't always provide warnings the user wants. -Consider: - -@smallexample -PROGRAM X -PRINT *, A -END -@end smallexample - -Currently, the above is not flagged as a case of -using an uninitialized variable, -because @code{g77} generates a run-time library call that looks, -to the GBE, like it might actually @emph{modify} @samp{A} at run time. -(And, in fact, depending on the previous run-time library call, -it would!) - -Fixing this requires one of the following: - -@itemize @bullet -@item -Switch to new library, @code{libg77}, that provides -a more ``clean'' interface, -vis-a-vis input, output, and modified arguments, -so the GBE can tell what's going on. - -This would provide a pretty big performance improvement, -at least theoretically, and, ultimately, in practice, -for some types of code. - -@item -Have @code{g77} pass a pointer to a temporary -containing a copy of @samp{A}, -instead of to @samp{A} itself. -The GBE would then complain about the copy operation -involving a potentially uninitialized variable. - -This might also provide a performance boost for some code, -because @samp{A} might then end up living in a register, -which could help with inner loops. - -@item -Have @code{g77} use a GBE construct similar to @code{ADDR_EXPR} -but with extra information on the fact that the -item pointed to won't be modified -(a la @code{const} in C). - -Probably the best solution for now, but not quite trivial -to implement in the general case. -Worth considering after @code{g77} 0.6 is considered -pretty solid. -@end itemize - -@node Gracefully Handle Sensible Bad Code -@subsection Gracefully Handle Sensible Bad Code - -@code{g77} generally should continue processing for -warnings and recoverable (user) errors whenever possible---that -is, it shouldn't gratuitously make bad or useless code. - -For example: - -@smallexample -INTRINSIC ZABS -CALL FOO(ZABS) -END -@end smallexample - -@noindent -When compiling the above with @samp{-ff2c-intrinsics-disable}, -@code{g77} should indeed complain about passing @code{ZABS}, -but it still should compile, instead of rejecting -the entire @code{CALL} statement. -(Some of this is related to improving -the compiler internals to improve how statements are analyzed.) - -@node Non-standard Conversions -@subsection Non-standard Conversions - -@samp{-Wconversion} and related should flag places where non-standard -conversions are found. -Perhaps much of this would be part of @samp{-Wugly*}. - -@node Non-standard Intrinsics -@subsection Non-standard Intrinsics - -@code{g77} needs a new option, like @samp{-Wintrinsics}, to warn about use of -non-standard intrinsics without explicit @code{INTRINSIC} statements for them. -This would help find code that might fail silently when ported to another -compiler. - -@node Modifying DO Variable -@subsection Modifying @code{DO} Variable - -@code{g77} should warn about modifying @code{DO} variables -via @code{EQUIVALENCE}. -(The internal information gathered to produce this warning -might also be useful in setting the -internal ``doiter'' flag for a variable or even array -reference within a loop, since that might produce faster code someday.) - -For example, this code is invalid, so @code{g77} should warn about -the invalid assignment to @samp{NOTHER}: - -@smallexample -EQUIVALENCE (I, NOTHER) -DO I = 1, 100 - IF (I.EQ. 10) NOTHER = 20 -END DO -@end smallexample - -@node Better Pedantic Compilation -@subsection Better Pedantic Compilation - -@code{g77} needs to support @samp{-fpedantic} more thoroughly, -and use it only to generate -warnings instead of rejecting constructs outright. -Have it warn: -if a variable that dimensions an array is not a dummy or placed -explicitly in @code{COMMON} (F77 does not allow it to be -placed in @code{COMMON} via @code{EQUIVALENCE}); if specification statements -follow statement-function-definition statements; about all sorts of -syntactic extensions. - -@node Warn About Implicit Conversions -@subsection Warn About Implicit Conversions - -@code{g77} needs a @samp{-Wpromotions} option to warn if source code appears -to expect automatic, silent, and -somewhat dangerous compiler-assisted conversion of @code{REAL(KIND=1)} -constants to @code{REAL(KIND=2)} based on context. - -For example, it would warn about cases like this: - -@smallexample -DOUBLE PRECISION FOO -PARAMETER (TZPHI = 9.435784839284958) -FOO = TZPHI * 3D0 -@end smallexample - -@node Invalid Use of Hollerith Constant -@subsection Invalid Use of Hollerith Constant - -@code{g77} should disallow statements like @samp{RETURN 2HAB}, -which are invalid in both source forms -(unlike @samp{RETURN (2HAB)}, -which probably still makes no sense but at least can -be reliably parsed). -Fixed-form processing rejects it, but not free-form, except -in a way that is a bit difficult to understand. - -@node Dummy Array Without Dimensioning Dummy -@subsection Dummy Array Without Dimensioning Dummy - -@code{g77} should complain when a list of dummy arguments containing an -adjustable dummy array does -not also contain every variable listed in the dimension list of the -adjustable array. - -Currently, @code{g77} does complain about a variable that -dimensions an array but doesn't appear in any dummy list or @code{COMMON} -area, but this needs to be extended to catch cases where it doesn't appear in -every dummy list that also lists any arrays it dimensions. - -For example, @code{g77} should warn about the entry point @samp{ALT} -below, since it includes @samp{ARRAY} but not @samp{ISIZE} in its -list of arguments: - -@smallexample -SUBROUTINE PRIMARY(ARRAY, ISIZE) -REAL ARRAY(ISIZE) -ENTRY ALT(ARRAY) -@end smallexample - -@node Invalid FORMAT Specifiers -@subsection Invalid FORMAT Specifiers - -@code{g77} should check @code{FORMAT} specifiers for validity -as it does @code{FORMAT} statements. - -For example, a diagnostic would be produced for: - -@smallexample -PRINT 'HI THERE!' !User meant PRINT *, 'HI THERE!' -@end smallexample - -@node Ambiguous Dialects -@subsection Ambiguous Dialects - -@code{g77} needs a set of options such as @samp{-Wugly*}, @samp{-Wautomatic}, -@samp{-Wvxt}, @samp{-Wf90}, and so on. -These would warn about places in the user's source where ambiguities -are found, helpful in resolving ambiguities in the program's -dialect or dialects. - -@node Unused Labels -@subsection Unused Labels - -@code{g77} should warn about unused labels when @samp{-Wunused} is in effect. - -@node Informational Messages -@subsection Informational Messages - -@code{g77} needs an option to suppress information messages (notes). -@samp{-w} does this but also suppresses warnings. -The default should be to suppress info messages. - -Perhaps info messages should simply be eliminated. - -@node Uninitialized Variables at Run Time -@subsection Uninitialized Variables at Run Time - -@code{g77} needs an option to initialize everything (not otherwise -explicitly initialized) to ``weird'' -(machine-dependent) values, e.g. NaNs, bad (non-@code{NULL}) pointers, and -largest-magnitude integers, would help track down references to -some kinds of uninitialized variables at run time. - -Note that use of the options @samp{-O -Wuninitialized} can catch -many such bugs at compile time. - -@node Portable Unformatted Files -@subsection Portable Unformatted Files - -@cindex unformatted files -@cindex file formats -@cindex binary data -@cindex byte ordering -@code{g77} has no facility for exchanging unformatted files with systems -using different number formats---even differing only in endianness (byte -order)---or written by other compilers. Some compilers provide -facilities at least for doing byte-swapping during unformatted I/O. - -It is unrealistic to expect to cope with exchanging unformatted files -with arbitrary other compiler runtimes, but the @code{g77} runtime -should at least be able to read files written by @code{g77} on systems -with different number formats, particularly if they differ only in byte -order. - -In case you do need to write a program to translate to or from -@code{g77} (@code{libf2c}) unformatted files, they are written as -follows: -@table @asis -@item Sequential -Unformatted sequential records consist of -@enumerate -@item -A number giving the length of the record contents; -@item -the length of record contents again (for backspace). -@end enumerate - -The record length is of C type -@code{long}; this means that it is 8 bytes on 64-bit systems such as -Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux. -Consequently such files cannot be exchanged between 64-bit and 32-bit -systems, even with the same basic number format. -@item Direct access -Unformatted direct access files form a byte stream of length -@var{records}*@var{recl} bytes, where @var{records} is the maximum -record number (@code{REC=@var{records}}) written and @var{recl} is the -record length in bytes specified in the @code{OPEN} statement -(@code{RECL=@var{recl}}). Data appear in the records as determined by -the relevant @code{WRITE} statement. Dummy records with arbitrary -contents appear in the file in place of records which haven't been -written. -@end table - -Thus for exchanging a sequential or direct access unformatted file -between big- and little-endian 32-bit systems using IEEE 754 floating -point it would be sufficient to reverse the bytes in consecutive words -in the file if, and @emph{only} if, only @code{REAL*4}, @code{COMPLEX}, -@code{INTEGER*4} and/or @code{LOGICAL*4} data have been written to it by -@code{g77}. - -If necessary, it is possible to do byte-oriented i/o with @code{g77}'s -@code{FGETC} and @code{FPUTC} intrinsics. Byte-swapping can be done in -Fortran by equivalencing larger sized variables to an @code{INTEGER*1} -array or a set of scalars. - -@cindex HDF -@cindex PDB -If you need to exchange binary data between arbitrary system and -compiler variations, we recommend using a portable binary format with -Fortran bindings, such as NCSA's HDF (@uref{http://hdf.ncsa.uiuc.edu/}) -or PACT's PDB@footnote{No, not @emph{that} one.} -(@uref{http://www.llnl.gov/def_sci/pact/pact_homepage.html}). (Unlike, -say, CDF or XDR, HDF-like systems write in the native number formats and -only incur overhead when they are read on a system with a different -format.) A future @code{g77} runtime library should use such -techniques. - -@node Better List-directed I/O -@subsection Better List-directed I/O - -Values output using list-directed I/O -(@samp{PRINT *, R, D}) -should be written with a field width, precision, and so on -appropriate for the type (precision) of each value. - -(Currently, no distinction is made between single-precision -and double-precision values -by @code{libf2c}.) - -It is likely this item will require the @code{libg77} project -to be undertaken. - -In the meantime, use of formatted I/O is recommended. -While it might be of little consolation, -@code{g77} does support @samp{FORMAT(F<WIDTH>.4)}, for example, -as long as @samp{WIDTH} is defined as a named constant -(via @code{PARAMETER}). -That at least allows some compile-time specification -of the precision of a data type, -perhaps controlled by preprocessing directives. - -@node Default to Console I/O -@subsection Default to Console I/O - -The default I/O units, -specified by @samp{READ @var{fmt}}, -@samp{READ (UNIT=*)}, -@samp{WRITE (UNIT=*)}, and -@samp{PRINT @var{fmt}}, -should not be units 5 (input) and 6 (output), -but, rather, unit numbers not normally available -for use in statements such as @code{OPEN} and @code{CLOSE}. - -Changing this would allow a program to connect units 5 and 6 -to files via @code{OPEN}, -but still use @samp{READ (UNIT=*)} and @samp{PRINT} -to do I/O to the ``console''. - -This change probably requires the @code{libg77} project. - -@node Labels Visible to Debugger -@subsection Labels Visible to Debugger - -@code{g77} should output debugging information for statements labels, -for use by debuggers that know how to support them. -Same with weirder things like construct names. -It is not yet known if any debug formats or debuggers support these. - -@node Disappointments -@section Disappointments and Misunderstandings - -These problems are perhaps regrettable, but we don't know any practical -way around them for now. - -@menu -* Mangling of Names:: @samp{SUBROUTINE FOO} is given - external name @samp{foo_}. -* Multiple Definitions of External Names:: No doing both @samp{COMMON /FOO/} - and @samp{SUBROUTINE FOO}. -* Limitation on Implicit Declarations:: No @samp{IMPLICIT CHARACTER*(*)}. -@end menu - -@node Mangling of Names -@subsection Mangling of Names in Source Code -@cindex naming issues -@cindex external names -@cindex common blocks -@cindex name space -@cindex underscore - -The current external-interface design, which includes naming of -external procedures, COMMON blocks, and the library interface, -has various usability problems, including things like adding -underscores where not really necessary (and preventing easier -inter-language operability) and yet not providing complete -namespace freedom for user C code linked with Fortran apps (due -to the naming of functions in the library, among other things). - -Project GNU should at least get all this ``right'' for systems -it fully controls, such as the Hurd, and provide defaults and -options for compatibility with existing systems and interoperability -with popular existing compilers. - -@node Multiple Definitions of External Names -@subsection Multiple Definitions of External Names -@cindex block data -@cindex BLOCK DATA statement -@cindex statements, BLOCK DATA -@cindex @code{COMMON} statement -@cindex statements, @code{COMMON} -@cindex naming conflicts - -@code{g77} doesn't allow a common block and an external procedure or -@code{BLOCK DATA} to have the same name. -Some systems allow this, but @code{g77} does not, -to be compatible with @code{f2c}. - -@code{g77} could special-case the way it handles -@code{BLOCK DATA}, since it is not compatible with @code{f2c} in this -particular area (necessarily, since @code{g77} offers an -important feature here), but -it is likely that such special-casing would be very annoying to people -with programs that use @samp{EXTERNAL FOO}, with no other mention of -@samp{FOO} in the same program unit, to refer to external procedures, since -the result would be that @code{g77} would treat these references as requests to -force-load BLOCK DATA program units. - -In that case, if @code{g77} modified -names of @code{BLOCK DATA} so they could have the same names as -@code{COMMON}, users -would find that their programs wouldn't link because the @samp{FOO} procedure -didn't have its name translated the same way. - -(Strictly speaking, -@code{g77} could emit a null-but-externally-satisfying definition of -@samp{FOO} with its name transformed as if it had been a -@code{BLOCK DATA}, but that probably invites more trouble than it's -worth.) - -@node Limitation on Implicit Declarations -@subsection Limitation on Implicit Declarations -@cindex IMPLICIT CHARACTER*(*) statement -@cindex statements, IMPLICIT CHARACTER*(*) - -@code{g77} disallows @code{IMPLICIT CHARACTER*(*)}. -This is not standard-conforming. - -@node Non-bugs -@section Certain Changes We Don't Want to Make - -This section lists changes that people frequently request, but which -we do not make because we think GNU Fortran is better without them. - -@menu -* Backslash in Constants:: Why @samp{'\\'} is a constant that - is one, not two, characters long. -* Initializing Before Specifying:: Why @samp{DATA VAR/1/} can't precede - @samp{COMMON VAR}. -* Context-Sensitive Intrinsicness:: Why @samp{CALL SQRT} won't work. -* Context-Sensitive Constants:: Why @samp{9.435784839284958} is a - single-precision constant, - and might be interpreted as - @samp{9.435785} or similar. -* Equivalence Versus Equality:: Why @samp{.TRUE. .EQ. .TRUE.} won't work. -* Order of Side Effects:: Why @samp{J = IFUNC() - IFUNC()} might - not behave as expected. -@end menu - -@node Backslash in Constants -@subsection Backslash in Constants -@cindex backslash -@cindex @code{f77} support -@cindex support, @code{f77} - -In the opinion of many experienced Fortran users, -@samp{-fno-backslash} should be the default, not @samp{-fbackslash}, -as currently set by @code{g77}. - -First of all, you can always specify -@samp{-fno-backslash} to turn off this processing. - -Despite not being within the spirit (though apparently within the -letter) of the ANSI FORTRAN 77 standard, @code{g77} defaults to -@samp{-fbackslash} because that is what most UNIX @code{f77} commands -default to, and apparently lots of code depends on this feature. - -This is a particularly troubling issue. -The use of a C construct in the midst of Fortran code -is bad enough, worse when it makes existing Fortran -programs stop working (as happens when programs written -for non-UNIX systems are ported to UNIX systems with -compilers that provide the @samp{-fbackslash} feature -as the default---sometimes with no option to turn it off). - -The author of GNU Fortran wished, for reasons of linguistic -purity, to make @samp{-fno-backslash} the default for GNU -Fortran and thus require users of UNIX @code{f77} and @code{f2c} -to specify @samp{-fbackslash} to get the UNIX behavior. - -However, the realization that @code{g77} is intended as -a replacement for @emph{UNIX} @code{f77}, caused the author -to choose to make @code{g77} as compatible with -@code{f77} as feasible, which meant making @samp{-fbackslash} -the default. - -The primary focus on compatibility is at the source-code -level, and the question became ``What will users expect -a replacement for @code{f77} to do, by default?'' -Although at least one UNIX @code{f77} does not provide -@samp{-fbackslash} as a default, it appears that -the majority of them do, which suggests that -the majority of code that is compiled by UNIX @code{f77} -compilers expects @samp{-fbackslash} to be the default. - -It is probably the case that more code exists -that would @emph{not} work with @samp{-fbackslash} -in force than code that requires it be in force. - -However, most of @emph{that} code is not being compiled -with @code{f77}, -and when it is, new build procedures (shell scripts, -makefiles, and so on) must be set up anyway so that -they work under UNIX. -That makes a much more natural and safe opportunity for -non-UNIX users to adapt their build procedures for -@code{g77}'s default of @samp{-fbackslash} than would -exist for the majority of UNIX @code{f77} users who -would have to modify existing, working build procedures -to explicitly specify @samp{-fbackslash} if that was -not the default. - -One suggestion has been to configure the default for -@samp{-fbackslash} (and perhaps other options as well) -based on the configuration of @code{g77}. - -This is technically quite straightforward, but will be avoided -even in cases where not configuring defaults to be -dependent on a particular configuration greatly inconveniences -some users of legacy code. - -Many users appreciate the GNU compilers because they provide an -environment that is uniform across machines. -These users would be -inconvenienced if the compiler treated things like the -format of the source code differently on certain machines. - -Occasionally users write programs intended only for a particular machine -type. -On these occasions, the users would benefit if the GNU Fortran compiler -were to support by default the same dialect as the other compilers on -that machine. -But such applications are rare. -And users writing a -program to run on more than one type of machine cannot possibly benefit -from this kind of compatibility. -(This is consistent with the design goals for @code{gcc}. -To change them for @code{g77}, you must first change them -for @code{gcc}. -Do not ask the maintainers of @code{g77} to do this for you, -or to disassociate @code{g77} from the widely understood, if -not widely agreed-upon, goals for GNU compilers in general.) - -This is why GNU Fortran does and will treat backslashes in the same -fashion on all types of machines (by default). -@xref{Direction of Language Development}, for more information on -this overall philosophy guiding the development of the GNU Fortran -language. - -Of course, users strongly concerned about portability should indicate -explicitly in their build procedures which options are expected -by their source code, or write source code that has as few such -expectations as possible. - -For example, avoid writing code that depends on backslash (@samp{\}) -being interpreted either way in particular, such as by -starting a program unit with: - -@smallexample -CHARACTER BACKSL -PARAMETER (BACKSL = '\\') -@end smallexample - -@noindent -Then, use concatenation of @samp{BACKSL} anyplace a backslash -is desired. -In this way, users can write programs which have the same meaning -in many Fortran dialects. - -(However, this technique does not work for Hollerith constants---which -is just as well, since the only generally portable uses for Hollerith -constants are in places where character constants can and should -be used instead, for readability.) - -@node Initializing Before Specifying -@subsection Initializing Before Specifying -@cindex initialization, statement placement -@cindex placing initialization statements - -@code{g77} does not allow @samp{DATA VAR/1/} to appear in the -source code before @samp{COMMON VAR}, -@samp{DIMENSION VAR(10)}, @samp{INTEGER VAR}, and so on. -In general, @code{g77} requires initialization of a variable -or array to be specified @emph{after} all other specifications -of attributes (type, size, placement, and so on) of that variable -or array are specified (though @emph{confirmation} of data type is -permitted). - -It is @emph{possible} @code{g77} will someday allow all of this, -even though it is not allowed by the FORTRAN 77 standard. - -Then again, maybe it is better to have -@code{g77} always require placement of @code{DATA} -so that it can possibly immediately write constants -to the output file, thus saving time and space. - -That is, @samp{DATA A/1000000*1/} should perhaps always -be immediately writable to canonical assembler, unless it's already known -to be in a @code{COMMON} area following as-yet-uninitialized stuff, -and to do this it cannot be followed by @samp{COMMON A}. - -@node Context-Sensitive Intrinsicness -@subsection Context-Sensitive Intrinsicness -@cindex intrinsics, context-sensitive -@cindex context-sensitive intrinsics - -@code{g77} treats procedure references to @emph{possible} intrinsic -names as always enabling their intrinsic nature, regardless of -whether the @emph{form} of the reference is valid for that -intrinsic. - -For example, @samp{CALL SQRT} is interpreted by @code{g77} as -an invalid reference to the @code{SQRT} intrinsic function, -because the reference is a subroutine invocation. - -First, @code{g77} recognizes the statement @samp{CALL SQRT} -as a reference to a @emph{procedure} named @samp{SQRT}, not -to a @emph{variable} with that name (as it would for a statement -such as @samp{V = SQRT}). - -Next, @code{g77} establishes that, in the program unit being compiled, -@code{SQRT} is an intrinsic---not a subroutine that -happens to have the same name as an intrinsic (as would be -the case if, for example, @samp{EXTERNAL SQRT} was present). - -Finally, @code{g77} recognizes that the @emph{form} of the -reference is invalid for that particular intrinsic. -That is, it recognizes that it is invalid for an intrinsic -@emph{function}, such as @code{SQRT}, to be invoked as -a @emph{subroutine}. - -At that point, @code{g77} issues a diagnostic. - -Some users claim that it is ``obvious'' that @samp{CALL SQRT} -references an external subroutine of their own, not an -intrinsic function. - -However, @code{g77} knows about intrinsic -subroutines, not just functions, and is able to support both having -the same names, for example. - -As a result of this, @code{g77} rejects calls -to intrinsics that are not subroutines, and function invocations -of intrinsics that are not functions, just as it (and most compilers) -rejects invocations of intrinsics with the wrong number (or types) -of arguments. - -So, use the @samp{EXTERNAL SQRT} statement in a program unit that calls -a user-written subroutine named @samp{SQRT}. - -@node Context-Sensitive Constants -@subsection Context-Sensitive Constants -@cindex constants, context-sensitive -@cindex context-sensitive constants - -@code{g77} does not use context to determine the types of -constants or named constants (@code{PARAMETER}), except -for (non-standard) typeless constants such as @samp{'123'O}. - -For example, consider the following statement: - -@smallexample -PRINT *, 9.435784839284958 * 2D0 -@end smallexample - -@noindent -@code{g77} will interpret the (truncated) constant -@samp{9.435784839284958} as a @code{REAL(KIND=1)}, not @code{REAL(KIND=2)}, -constant, because the suffix @code{D0} is not specified. - -As a result, the output of the above statement when -compiled by @code{g77} will appear to have ``less precision'' -than when compiled by other compilers. - -In these and other cases, some compilers detect the -fact that a single-precision constant is used in -a double-precision context and therefore interpret the -single-precision constant as if it was @emph{explicitly} -specified as a double-precision constant. -(This has the effect of appending @emph{decimal}, not -@emph{binary}, zeros to the fractional part of the -number---producing different computational results.) - -The reason this misfeature is dangerous is that a slight, -apparently innocuous change to the source code can change -the computational results. -Consider: - -@smallexample -REAL ALMOST, CLOSE -DOUBLE PRECISION FIVE -PARAMETER (ALMOST = 5.000000000001) -FIVE = 5 -CLOSE = 5.000000000001 -PRINT *, 5.000000000001 - FIVE -PRINT *, ALMOST - FIVE -PRINT *, CLOSE - FIVE -END -@end smallexample - -@noindent -Running the above program should -result in the same value being -printed three times. -With @code{g77} as the compiler, -it does. - -However, compiled by many other compilers, -running the above program would print -two or three distinct values, because -in two or three of the statements, the -constant @samp{5.000000000001}, which -on most systems is exactly equal to @samp{5.} -when interpreted as a single-precision constant, -is instead interpreted as a double-precision -constant, preserving the represented -precision. -However, this ``clever'' promotion of -type does not extend to variables or, -in some compilers, to named constants. - -Since programmers often are encouraged to replace manifest -constants or permanently-assigned variables with named -constants (@code{PARAMETER} in Fortran), and might need -to replace some constants with variables having the same -values for pertinent portions of code, -it is important that compilers treat code so modified in the -same way so that the results of such programs are the same. -@code{g77} helps in this regard by treating constants just -the same as variables in terms of determining their types -in a context-independent way. - -Still, there is a lot of existing Fortran code that has -been written to depend on the way other compilers freely -interpret constants' types based on context, so anything -@code{g77} can do to help flag cases of this in such code -could be very helpful. - -@node Equivalence Versus Equality -@subsection Equivalence Versus Equality -@cindex .EQV., with integer operands -@cindex comparing logical expressions -@cindex logical expressions, comparing - -Use of @code{.EQ.} and @code{.NE.} on @code{LOGICAL} operands -is not supported, except via @samp{-fugly-logint}, which is not -recommended except for legacy code (where the behavior expected -by the @emph{code} is assumed). - -Legacy code should be changed, as resources permit, to use @code{.EQV.} -and @code{.NEQV.} instead, as these are permitted by the various -Fortran standards. - -New code should never be written expecting @code{.EQ.} or @code{.NE.} -to work if either of its operands is @code{LOGICAL}. - -The problem with supporting this ``feature'' is that there is -unlikely to be consensus on how it works, as illustrated by the -following sample program: - -@smallexample -LOGICAL L,M,N -DATA L,M,N /3*.FALSE./ -IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N' -END -@end smallexample - -The issue raised by the above sample program is: what is the -precedence of @code{.EQ.} (and @code{.NE.}) when applied to -@code{LOGICAL} operands? - -Some programmers will argue that it is the same as the precedence -for @code{.EQ.} when applied to numeric (such as @code{INTEGER}) -operands. -By this interpretation, the subexpression @samp{M.EQ.N} must be -evaluated first in the above program, resulting in a program that, -when run, does not execute the @code{PRINT} statement. - -Other programmers will argue that the precedence is the same as -the precedence for @code{.EQV.}, which is restricted by the standards -to @code{LOGICAL} operands. -By this interpretation, the subexpression @samp{L.AND.M} must be -evaluated first, resulting in a program that @emph{does} execute -the @code{PRINT} statement. - -Assigning arbitrary semantic interpretations to syntactic expressions -that might legitimately have more than one ``obvious'' interpretation -is generally unwise. - -The creators of the various Fortran standards have done a good job -in this case, requiring a distinct set of operators (which have their -own distinct precedence) to compare @code{LOGICAL} operands. -This requirement results in expression syntax with more certain -precedence (without requiring substantial context), making it easier -for programmers to read existing code. -@code{g77} will avoid muddying up elements of the Fortran language -that were well-designed in the first place. - -(Ask C programmers about the precedence of expressions such as -@samp{(a) & (b)} and @samp{(a) - (b)}---they cannot even tell -you, without knowing more context, whether the @samp{&} and @samp{-} -operators are infix (binary) or unary!) - -Most dangerous of all is the fact that, -even assuming consensus on its meaning, -an expression like @samp{L.AND.M.EQ.N}, -if it is the result of a typographical error, -doesn't @emph{look} like it has such a typo. -Even experienced Fortran programmers would not likely notice that -@samp{L.AND.M.EQV.N} was, in fact, intended. - -So, this is a prime example of a circumstance in which -a quality compiler diagnoses the code, -instead of leaving it up to someone debugging it -to know to turn on special compiler options -that might diagnose it. - -@node Order of Side Effects -@subsection Order of Side Effects -@cindex side effects, order of evaluation -@cindex order of evaluation, side effects - -@code{g77} does not necessarily produce code that, when run, performs -side effects (such as those performed by function invocations) -in the same order as in some other compiler---or even in the same -order as another version, port, or invocation (using different -command-line options) of @code{g77}. - -It is never safe to depend on the order of evaluation of side effects. -For example, an expression like this may very well behave differently -from one compiler to another: - -@smallexample -J = IFUNC() - IFUNC() -@end smallexample - -@noindent -There is no guarantee that @samp{IFUNC} will be evaluated in any particular -order. -Either invocation might happen first. -If @samp{IFUNC} returns 5 the first time it is invoked, and -returns 12 the second time, @samp{J} might end up with the -value @samp{7}, or it might end up with @samp{-7}. - -Generally, in Fortran, procedures with side-effects intended to -be visible to the caller are best designed as @emph{subroutines}, -not functions. -Examples of such side-effects include: - -@itemize @bullet -@item -The generation of random numbers -that are intended to influence return values. - -@item -Performing I/O -(other than internal I/O to local variables). - -@item -Updating information in common blocks. -@end itemize - -An example of a side-effect that is not intended to be visible -to the caller is a function that maintains a cache of recently -calculated results, intended solely to speed repeated invocations -of the function with identical arguments. -Such a function can be safely used in expressions, because -if the compiler optimizes away one or more calls to the -function, operation of the program is unaffected (aside -from being speeded up). - -@node Warnings and Errors -@section Warning Messages and Error Messages - -@cindex error messages -@cindex warnings vs errors -@cindex messages, warning and error -The GNU compiler can produce two kinds of diagnostics: errors and -warnings. -Each kind has a different purpose: - -@itemize @w{} -@item -@emph{Errors} report problems that make it impossible to compile your -program. -GNU Fortran reports errors with the source file name, line -number, and column within the line where the problem is apparent. - -@item -@emph{Warnings} report other unusual conditions in your code that -@emph{might} indicate a problem, although compilation can (and does) -proceed. -Warning messages also report the source file name, line number, -and column information, -but include the text @samp{warning:} to distinguish them -from error messages. -@end itemize - -Warnings might indicate danger points where you should check to make sure -that your program really does what you intend; or the use of obsolete -features; or the use of nonstandard features of GNU Fortran. -Many warnings are issued only if you ask for them, with one of the -@samp{-W} options (for instance, @samp{-Wall} requests a variety of -useful warnings). - -@emph{Note:} Currently, the text of the line and a pointer to the column -is printed in most @code{g77} diagnostics. -Probably, as of version 0.6, @code{g77} will -no longer print the text of the source line, instead printing -the column number following the file name and line number in -a form that GNU Emacs recognizes. -This change is expected to speed up and reduce the memory usage -of the @code{g77} compiler. -@c -@c Say this when it is true -- hopefully 0.6, maybe 0.7 or later. --burley -@c -@c GNU Fortran always tries to compile your program if possible; it never -@c gratuitously rejects a program whose meaning is clear merely because -@c (for instance) it fails to conform to a standard. In some cases, -@c however, the Fortran standard specifies that certain extensions are -@c forbidden, and a diagnostic @emph{must} be issued by a conforming -@c compiler. The @samp{-pedantic} option tells GNU Fortran to issue warnings -@c in such cases; @samp{-pedantic-errors} says to make them errors instead. -@c This does not mean that @emph{all} non-ANSI constructs get warnings -@c or errors. - -@xref{Warning Options,,Options to Request or Suppress Warnings}, for -more detail on these and related command-line options. - -@node Open Questions -@chapter Open Questions - -Please consider offering useful answers to these questions! - -@itemize @bullet -@item -@code{LOC()} and other intrinsics are probably somewhat misclassified. -Is the a need for more precise classification of intrinsics, and if so, -what are the appropriate groupings? -Is there a need to individually -enable/disable/delete/hide intrinsics from the command line? -@end itemize - -@node Bugs -@chapter Reporting Bugs -@cindex bugs -@cindex reporting bugs - -Your bug reports play an essential role in making GNU Fortran reliable. - -When you encounter a problem, the first thing to do is to see if it is -already known. -@xref{Trouble}. -If it isn't known, then you should report the problem. - -Reporting a bug might help you by bringing a solution to your problem, or -it might not. -(If it does not, look in the service directory; see -@ref{Service}.) -In any case, the principal function of a bug report is -to help the entire community by making the next version of GNU Fortran work -better. -Bug reports are your contribution to the maintenance of GNU Fortran. - -Since the maintainers are very overloaded, we cannot respond to every -bug report. -However, if the bug has not been fixed, we are likely to -send you a patch and ask you to tell us whether it works. - -In order for a bug report to serve its purpose, you must include the -information that makes for fixing the bug. - -@menu -* Criteria: Bug Criteria. Have you really found a bug? -* Where: Bug Lists. Where to send your bug report. -* Reporting: Bug Reporting. How to report a bug effectively. -* Patches: Sending Patches. How to send a patch for GNU Fortran. -@end menu - -@xref{Trouble,,Known Causes of Trouble with GNU Fortran}, -for information on problems we already know about. - -@xref{Service,,How To Get Help with GNU Fortran}, -for information on where to ask for help. - -@node Bug Criteria -@section Have You Found a Bug? -@cindex bug criteria - -If you are not sure whether you have found a bug, here are some guidelines: - -@itemize @bullet -@cindex fatal signal -@cindex core dump -@item -If the compiler gets a fatal signal, for any input whatever, that is a -compiler bug. -Reliable compilers never crash---they just remain obsolete. - -@cindex invalid assembly code -@cindex assembly code, invalid -@item -If the compiler produces invalid assembly code, for any input whatever, -@c (except an @code{asm} statement), -that is a compiler bug, unless the -compiler reports errors (not just warnings) which would ordinarily -prevent the assembler from being run. - -@cindex undefined behavior -@cindex undefined function value -@item -If the compiler produces valid assembly code that does not correctly -execute the input source code, that is a compiler bug. - -However, you must double-check to make sure, because you might have run -into an incompatibility between GNU Fortran and traditional Fortran. -@c (@pxref{Incompatibilities}). -These incompatibilities might be considered -bugs, but they are inescapable consequences of valuable features. - -Or you might have a program whose behavior is undefined, which happened -by chance to give the desired results with another Fortran compiler. -It is best to check the relevant Fortran standard thoroughly if -it is possible that the program indeed does something undefined. - -After you have localized the error to a single source line, it should -be easy to check for these things. -If your program is correct and well defined, you have found -a compiler bug. - -It might help if, in your submission, you identified the specific -language in the relevant Fortran standard that specifies the -desired behavior, if it isn't likely to be obvious and agreed-upon -by all Fortran users. - -@item -If the compiler produces an error message for valid input, that is a -compiler bug. - -@cindex invalid input -@item -If the compiler does not produce an error message for invalid input, -that is a compiler bug. -However, you should note that your idea of -``invalid input'' might be someone else's idea -of ``an extension'' or ``support for traditional practice''. - -@item -If you are an experienced user of Fortran compilers, your suggestions -for improvement of GNU Fortran are welcome in any case. -@end itemize - -Many, perhaps most, bug reports against @code{g77} turn out to -be bugs in the user's code. -While we find such bug reports educational, they sometimes take -a considerable amount of time to track down or at least respond -to---time we could be spending making @code{g77}, not some user's -code, better. - -Some steps you can take to verify that the bug is not certainly -in the code you're compiling with @code{g77}: - -@itemize @bullet -@item -Compile your code using the @code{g77} options @samp{-W -Wall -O}. -These options enable many useful warning; the @samp{-O} option -enables flow analysis that enables the uninitialized-variable -warning. - -If you investigate the warnings and find evidence of possible bugs -in your code, fix them first and retry @code{g77}. - -@item -Compile your code using the @code{g77} options @samp{-finit-local-zero}, -@samp{-fno-automatic}, @samp{-ffloat-store}, and various -combinations thereof. - -If your code works with any of these combinations, that is not -proof that the bug isn't in @code{g77}---a @code{g77} bug exposed -by your code might simply be avoided, or have a different, more subtle -effect, when different options are used---but it can be a -strong indicator that your code is making unwarranted assumptions -about the Fortran dialect and/or underlying machine it is -being compiled and run on. - -@xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, -for information on the @samp{-fno-automatic} and -@samp{-finit-local-zero} options and how to convert -their use into selective changes in your own code. - -@item -@pindex ftnchek -Validate your code with @code{ftnchek} or a similar code-checking -tool. -@code{ftnchek} can be found at @uref{ftp://ftp.netlib.org/fortran} -or @uref{ftp://ftp.dsm.fordham.edu}. - -@pindex make -@cindex Makefile example -Here are some sample @file{Makefile} rules using @code{ftnchek} -``project'' files to do cross-file checking and @code{sfmakedepend} -(from @uref{ftp://ahab.rutgers.edu/pub/perl/sfmakedepend}) -to maintain dependencies automatically. -These assume the use of GNU @code{make}. - -@smallexample -# Dummy suffix for ftnchek targets: -.SUFFIXES: .chek -.PHONY: chekall - -# How to compile .f files (for implicit rule): -FC = g77 -# Assume `include' directory: -FFLAGS = -Iinclude -g -O -Wall - -# Flags for ftnchek: -CHEK1 = -array=0 -include=includes -noarray -CHEK2 = -nonovice -usage=1 -notruncation -CHEKFLAGS = $(CHEK1) $(CHEK2) - -# Run ftnchek with all the .prj files except the one corresponding -# to the target's root: -%.chek : %.f ; \ - ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \ - -noextern -library $< - -# Derive a project file from a source file: -%.prj : %.f ; \ - ftnchek $(CHEKFLAGS) -noextern -project -library $< - -# The list of objects is assumed to be in variable OBJS. -# Sources corresponding to the objects: -SRCS = $(OBJS:%.o=%.f) -# ftnchek project files: -PRJS = $(OBJS:%.o=%.prj) - -# Build the program -prog: $(OBJS) ; \ - $(FC) -o $@ $(OBJS) - -chekall: $(PRJS) ; \ - ftnchek $(CHEKFLAGS) $(PRJS) - -prjs: $(PRJS) - -# For Emacs M-x find-tag: -TAGS: $(SRCS) ; \ - etags $(SRCS) - -# Rebuild dependencies: -depend: ; \ - sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1) -@end smallexample - -@item -Try your code out using other Fortran compilers, such as @code{f2c}. -If it does not work on at least one other compiler (assuming the -compiler supports the features the code needs), that is a strong -indicator of a bug in the code. - -However, even if your code works on many compilers @emph{except} -@code{g77}, that does @emph{not} mean the bug is in @code{g77}. -It might mean the bug is in your code, and that @code{g77} simply -exposes it more readily than other compilers. -@end itemize - -@node Bug Lists -@section Where to Report Bugs -@cindex bug report mailing lists -@kindex @value{email-bugs} -Send bug reports for GNU Fortran to @email{@value{email-bugs}}. - -Often people think of posting bug reports to a newsgroup instead of -mailing them. -This sometimes appears to work, but it has one problem which can be -crucial: a newsgroup posting does not contain a mail path back to the -sender. -Thus, if maintainers need more information, they might be unable -to reach you. For this reason, you should always send bug reports by -mail to the proper mailing list. - -As a last resort, send bug reports on paper to: - -@example -GNU Compiler Bugs -Free Software Foundation -59 Temple Place - Suite 330 -Boston, MA 02111-1307, USA -@end example - -@node Bug Reporting -@section How to Report Bugs -@cindex compiler bugs, reporting - -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. -If you are not sure whether to state a -fact or leave it out, state it! - -Often people omit facts because they think they know what causes the -problem and they conclude that some details don't matter. -Thus, you might -assume that the name of the variable you use in an example does not matter. -Well, probably it doesn't, but one cannot be sure. -Perhaps the bug is a -stray memory reference which happens to fetch from the location where that -name is stored in memory; perhaps, if the name were different, the contents -of that location would fool the compiler into doing the right thing despite -the bug. -Play it safe and give a specific, complete example. -That is the -easiest thing for you to do, and the most helpful. - -Keep in mind that the purpose of a bug report is to enable someone to -fix the bug if it is not known. -It isn't very important what happens if -the bug is already known. -Therefore, always write your bug reports on -the assumption that the bug is not known. - -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' -This cannot help us fix a bug, so it is rarely helpful. -We respond by asking for enough details to enable us to investigate. -You might as well expedite matters by sending them to begin with. -(Besides, there are enough bells ringing around here as it is.) - -Try to make your bug report self-contained. -If we have to ask you for -more information, it is best if you include all the previous information -in your response, as well as the information that was missing. - -Please report each bug in a separate message. -This makes it easier for -us to track which bugs have been fixed and to forward your bugs reports -to the appropriate maintainer. - -Do not compress and encode any part of your bug report using programs -such as @file{uuencode}. -If you do so it will slow down the processing -of your bug. -If you must submit multiple large files, use @file{shar}, -which allows us to read your message without having to run any -decompression programs. - -(As a special exception for GNU Fortran bug-reporting, at least -for now, if you are sending more than a few lines of code, if -your program's source file format contains ``interesting'' things -like trailing spaces or strange characters, or if you need to -include binary data files, it is acceptable to put all the -files together in a @code{tar} archive, and, whether you need to -do that, it is acceptable to then compress the single file (@code{tar} -archive or source file) -using @code{gzip} and encode it via @code{uuencode}. -Do not use any MIME stuff---the current maintainer can't decode this. -Using @code{compress} instead of @code{gzip} is acceptable, assuming -you have licensed the use of the patented algorithm in -@code{compress} from Unisys.) - -To enable someone to investigate the bug, you should include all these -things: - -@itemize @bullet -@item -The version of GNU Fortran. -You can get this by running @code{g77} with the @samp{-v} option. -(Ignore any error messages that might be displayed -when the linker is run.) - -Without this, we won't know whether there is any point in looking for -the bug in the current version of GNU Fortran. - -@item -@cindex preprocessor -@cindex cpp program -@cindex programs, cpp -@pindex cpp -A complete input file that will reproduce the bug. - -If your source file(s) require preprocessing -(for example, their names have suffixes like -@samp{.F}, @samp{.fpp}, @samp{.FPP}, and @samp{.r}), -and the bug is in the compiler proper (@file{f771}) -or in a subsequent phase of processing, -run your source file through the C preprocessor -by doing @samp{g77 -E @var{sourcefile} > @var{newfile}}. -Then, include the contents of @var{newfile} in the bug report. -(When you do this, use the same preprocessor options---such as -@samp{-I}, @samp{-D}, and @samp{-U}---that you used in actual -compilation.) - -A single statement is not enough of an example. -In order to compile it, -it must be embedded in a complete file of compiler input. -The bug might depend on the details of how this is done. - -Without a real example one can compile, -all anyone can do about your bug report is wish you luck. -It would be futile to try to guess how to provoke the bug. -For example, bugs in register allocation and reloading -can depend on every little detail of the source and include files -that trigger them. - -@item -@cindex included files -@cindex INCLUDE directive -@cindex directive, INCLUDE -@cindex #include directive -@cindex directive, #include -Note that you should include with your bug report any files -included by the source file -(via the @code{#include} or @code{INCLUDE} directive) -that you send, and any files they include, and so on. - -It is not necessary to replace -the @code{#include} and @code{INCLUDE} directives -with the actual files in the version of the source file that -you send, but it might make submitting the bug report easier -in the end. -However, be sure to @emph{reproduce} the bug using the @emph{exact} -version of the source material you submit, to avoid wild-goose -chases. - -@item -The command arguments you gave GNU Fortran to compile that example -and observe the bug. For example, did you use @samp{-O}? To guarantee -you won't omit something important, list all the options. - -If we were to try to guess the arguments, we would probably guess wrong -and then we would not encounter the bug. - -@item -The type of machine you are using, and the operating system name and -version number. -(Much of this information is printed by @samp{g77 -v}---if you -include that, send along any additional info you have that you -don't see clearly represented in that output.) - -@item -The operands you gave to the @code{configure} command when you installed -the compiler. - -@item -A complete list of any modifications you have made to the compiler -source. (We don't promise to investigate the bug unless it happens in -an unmodified compiler. But if you've made modifications and don't tell -us, then you are sending us on a wild-goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own (such as a machine description for a machine we -don't support) is a modification of the compiler source. - -@item -Details of any other deviations from the standard procedure for installing -GNU Fortran. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The compiler gets a fatal signal,'' or, -``The assembler instruction at line 208 in the output is incorrect.'' - -Of course, if the bug is that the compiler gets a fatal signal, then one -can't miss it. But if the bug is incorrect output, the maintainer might -not notice unless it is glaringly wrong. None of us has time to study -all the assembler code from a 50-line Fortran program just on the chance that -one instruction might be wrong. We need @emph{you} to do this part! - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the compiler is out of synch, or you have encountered a bug in -the C library on your system. (This has happened!) Your copy might -crash and the copy here would not. If you @i{said} to expect a crash, -then when the compiler here fails to crash, we would know that the bug -was not happening. If you don't say to expect a crash, then we would -not know whether the bug was happening. We would not be able to draw -any conclusion from our observations. - -If the problem is a diagnostic when building GNU Fortran with some other -compiler, say whether it is a warning or an error. - -Often the observed symptom is incorrect output when your program is run. -Sad to say, this is not enough information unless the program is short -and simple. None of us has time to study a large program to figure out -how it would work if compiled correctly, much less which line of it was -compiled wrong. So you will have to do that. Tell us which source line -it is, and what incorrect result happens when that line is executed. A -person who understands the program can find this as easily as finding a -bug in the program itself. - -@item -If you send examples of assembler code output from GNU Fortran, -please use @samp{-g} when you make them. The debugging information -includes source line numbers which are essential for correlating the -output with the input. - -@item -If you wish to mention something in the GNU Fortran source, refer to it by -context, not by line number. - -The line numbers in the development sources don't match those in your -sources. Your line numbers would convey no convenient information to the -maintainers. - -@item -Additional information from a debugger might enable someone to find a -problem on a machine which he does not have available. However, you -need to think when you collect this information if you want it to have -any chance of being useful. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is never -useful by itself. A simple backtrace with arguments conveys little -about GNU Fortran because the compiler is largely data-driven; the same -functions are called over and over for different RTL insns, doing -different things depending on the details of the insn. - -Most of the arguments listed in the backtrace are useless because they -are pointers to RTL list structure. The numeric values of the -pointers, which the debugger prints in the backtrace, have no -significance whatever; all that matters is the contents of the objects -they point to (and most of the contents are other such pointers). - -In addition, most compiler passes consist of one or more loops that -scan the RTL insn sequence. The most vital piece of information about -such a loop---which insn it has reached---is usually in a local variable, -not in an argument. - -@findex debug_rtx -What you need to provide in addition to a backtrace are the values of -the local variables for several stack frames up. When a local -variable or an argument is an RTX, first print its value and then use -the GDB command @code{pr} to print the RTL expression that it points -to. (If GDB doesn't run on your machine, use your debugger to call -the function @code{debug_rtx} with the RTX as an argument.) In -general, whenever a variable is a pointer, its value is no use -without the data it points to. -@end itemize - -Here are some things that are not necessary: - -@itemize @bullet -@item -A description of the envelope of the bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger with -breakpoints, not by pure deduction from a series of examples. You might -as well save your time for something else. - -Of course, if you can find a simpler example to report @emph{instead} of -the original one, that is a convenience. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. -Most GNU Fortran bugs involve just one function, so the most straightforward -way to simplify an example is to delete all the function definitions -except the one where the bug occurs. Those earlier in the file may be -replaced by external declarations if the crucial function depends on -them. (Exception: inline functions might affect compilation of functions -defined later in the file.) - -However, simplification is not vital; if you don't want to do this, -report the bug anyway and send the entire test case you used. - -@item -In particular, some people insert conditionals @samp{#ifdef BUG} around -a statement which, if removed, makes the bug not happen. These are just -clutter; we won't pay any attention to them anyway. Besides, you should -send us preprocessor output, and that can't have conditionals. - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -necessary information, such as the test case, on the assumption that a -patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. - -Sometimes with a program as complicated as GNU Fortran it is very hard to -construct an example that will make the program follow a certain path -through the code. If you don't send the example, we won't be able to -construct one, so we won't be able to verify that the bug is fixed. - -And if we can't understand what bug you are trying to fix, or why your -patch should be an improvement, we won't install it. A test case will -help us to understand. - -@xref{Sending Patches}, for guidelines on how to make it easy for us to -understand and install your patches. - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even the maintainer can't guess right -about such things without first using the debugger to find the facts. - -@item -A core dump file. - -We have no way of examining a core dump for your type of machine -unless we have an identical system---and if we do have one, -we should be able to reproduce the crash ourselves. -@end itemize - -@node Sending Patches -@section Sending Patches for GNU Fortran - -If you would like to write bug fixes or improvements for the GNU Fortran -compiler, that is very helpful. -Send suggested fixes to the bug report -mailing list, @email{@value{email-bugs}}. - -Please follow these guidelines so we can study your patches efficiently. -If you don't follow these guidelines, your information might still be -useful, but using it will take extra work. Maintaining GNU Fortran is a lot -of work in the best of circumstances, and we can't keep up unless you do -your best to help. - -@itemize @bullet -@item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a bug fix, just include a copy of the -bug report, and explain why the change fixes the bug. - -(Referring to a bug report is not as good as including it, because then -we will have to look it up, and we have probably already deleted it if -we've already fixed the bug.) - -@item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is right, we might have trouble judging it if -we don't have a way to reproduce the problem. - -@item -Include all the comments that are appropriate to help people reading the -source in the future understand why this change was needed. - -@item -Don't mix together changes made for different reasons. -Send them @emph{individually}. - -If you make two changes for separate reasons, then we might not want to -install them both. We might want to install just one. If you send them -all jumbled together in a single set of diffs, we have to do extra work -to disentangle them---to figure out which parts of the change serve -which purpose. If we don't have time for this, we might have to ignore -your changes entirely. - -If you send each change as soon as you have written it, with its own -explanation, then the two changes never get tangled up, and we can -consider each one properly without any extra work to disentangle them. - -Ideally, each change you send should be impossible to subdivide into -parts that we might want to consider separately, because each of its -parts gets its motivation from the other parts. - -@item -Send each change as soon as that change is finished. Sometimes people -think they are helping us by accumulating many changes to send them all -together. As explained above, this is absolutely the worst thing you -could do. - -Since you should send each change separately, you might as well send it -right away. That gives us the option of installing it immediately if it -is important. - -@item -Use @samp{diff -c} to make your diffs. Diffs without context are hard -for us to install reliably. More than that, they make it hard for us to -study the diffs to decide whether we want to install them. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. - -If you have GNU @code{diff}, use @samp{diff -cp}, which shows the name of the -function that each change occurs in. -(The maintainer of GNU Fortran currently uses @samp{diff -rcp2N}.) - -@item -Write the change log entries for your changes. We get lots of changes, -and we don't have time to do all the change log writing ourselves. - -Read the @file{ChangeLog} file to see what sorts of information to put -in, and to learn the style that we use. The purpose of the change log -is to show people where to find what was changed. So you need to be -specific about what functions you changed; in large functions, it's -often helpful to indicate where within the function the change was. - -On the other hand, once you have shown people where to find the change, -you need not explain its purpose. Thus, if you add a new function, all -you need to say about it is that it is new. If you feel that the -purpose needs explaining, it probably does---but the explanation will be -much more useful if you put it in comments in the code. - -If you would like your name to appear in the header line for who made -the change, send us the header line. - -@item -When you write the fix, keep in mind that we can't install a change that -would break other systems. - -People often suggest fixing a problem by changing machine-independent -files such as @file{toplev.c} to do something special that a particular -system needs. Sometimes it is totally obvious that such changes would -break GNU Fortran for almost all users. We can't possibly make a change like -that. At best it might tell us how to write another patch that would -solve the problem acceptably. - -Sometimes people send fixes that @emph{might} be an improvement in -general---but it is hard to be sure of this. It's hard to install -such changes because we have to study them very carefully. Of course, -a good explanation of the reasoning by which you concluded the change -was correct can help convince us. - -The safest changes are changes to the configuration files for a -particular machine. These are safe because they can't create new bugs -on other machines. - -Please help us keep up with the workload by designing the patch in a -form that is good to install. -@end itemize - -@node Service -@chapter How To Get Help with GNU Fortran - -If you need help installing, using or changing GNU Fortran, there are two -ways to find it: - -@itemize @bullet -@item -Look in the service directory for someone who might help you for a fee. -The service directory is found in the file named @file{SERVICE} in the -GNU CC distribution. - -@item -Send a message to @email{@value{email-general}}. -@end itemize - -@end ifset -@ifset INTERNALS -@node Adding Options -@chapter Adding Options -@cindex options, adding -@cindex adding options - -To add a new command-line option to @code{g77}, first decide -what kind of option you wish to add. -Search the @code{g77} and @code{gcc} documentation for one -or more options that is most closely like the one you want to add -(in terms of what kind of effect it has, and so on) to -help clarify its nature. - -@itemize @bullet -@item -@emph{Fortran options} are options that apply only -when compiling Fortran programs. -They are accepted by @code{g77} and @code{gcc}, but -they apply only when compiling Fortran programs. - -@item -@emph{Compiler options} are options that apply -when compiling most any kind of program. -@end itemize - -@emph{Fortran options} are listed in the file -@file{@value{path-g77}/lang-options.h}, -which is used during the build of @code{gcc} to -build a list of all options that are accepted by -at least one language's compiler. -This list goes into the @code{lang_options} array -in @file{gcc/toplev.c}, which uses this array to -determine whether a particular option should be -offered to the linked-in front end for processing -by calling @code{lang_option_decode}, which, for -@code{g77}, is in @file{@value{path-g77}/com.c} and just -calls @code{ffe_decode_option}. - -If the linked-in front end ``rejects'' a -particular option passed to it, @file{toplev.c} -just ignores the option, because @emph{some} -language's compiler is willing to accept it. - -This allows commands like @samp{gcc -fno-asm foo.c bar.f} -to work, even though Fortran compilation does -not currently support the @samp{-fno-asm} option; -even though the @code{f771} version of @code{lang_decode_option} -rejects @samp{-fno-asm}, @file{toplev.c} doesn't -produce a diagnostic because some other language (C) -does accept it. - -This also means that commands like -@samp{g77 -fno-asm foo.f} yield no diagnostics, -despite the fact that no phase of the command was -able to recognize and process @samp{-fno-asm}---perhaps -a warning about this would be helpful if it were -possible. - -Code that processes Fortran options is found in -@file{@value{path-g77}/top.c}, function @code{ffe_decode_option}. -This code needs to check positive and negative forms -of each option. - -The defaults for Fortran options are set in their -global definitions, also found in @file{@value{path-g77}/top.c}. -Many of these defaults are actually macros defined -in @file{@value{path-g77}/target.h}, since they might be -machine-specific. -However, since, in practice, GNU compilers -should behave the same way on all configurations -(especially when it comes to language constructs), -the practice of setting defaults in @file{target.h} -is likely to be deprecated and, ultimately, stopped -in future versions of @code{g77}. - -Accessor macros for Fortran options, used by code -in the @code{g77} FFE, are defined in @file{@value{path-g77}/top.h}. - -@emph{Compiler options} are listed in @file{gcc/toplev.c} -in the array @code{f_options}. -An option not listed in @code{lang_options} is -looked up in @code{f_options} and handled from there. - -The defaults for compiler options are set in the -global definitions for the corresponding variables, -some of which are in @file{gcc/toplev.c}. - -You can set different defaults for @emph{Fortran-oriented} -or @emph{Fortran-reticent} compiler options by changing -the source code of @code{g77} and rebuilding. -How to do this depends on the version of @code{g77}: - -@table @code -@item G77 0.5.24 (EGCS 1.1) -@itemx G77 0.5.25 (EGCS 1.2) -Change the @code{lang_init_options} routine in @file{egcs/gcc/f/com.c}. - -(Note that these versions of @code{g77} -perform internal consistency checking automatically -when the @samp{-fversion} option is specified.) - -@item G77 0.5.23 -@itemx G77 0.5.24 (EGCS 1.0) -Change the way @code{f771} handles the @samp{-fset-g77-defaults} -option, which is always provided as the first option when -called by @code{g77} or @code{gcc}. - -This code is in @code{ffe_decode_options} in @file{@value{path-g77}/top.c}. -Have it change just the variables that you want to default -to a different setting for Fortran compiles compared to -compiles of other languages. - -The @samp{-fset-g77-defaults} option is passed to @code{f771} -automatically because of the specification information -kept in @file{@value{path-g77}/lang-specs.h}. -This file tells the @code{gcc} command how to recognize, -in this case, Fortran source files (those to be preprocessed, -and those that are not), and further, how to invoke the -appropriate programs (including @code{f771}) to process -those source files. - -It is in @file{@value{path-g77}/lang-specs.h} that @samp{-fset-g77-defaults}, -@samp{-fversion}, and other options are passed, as appropriate, -even when the user has not explicitly specified them. -Other ``internal'' options such as @samp{-quiet} also -are passed via this mechanism. -@end table - -@node Projects -@chapter Projects -@cindex projects - -If you want to contribute to @code{g77} by doing research, -design, specification, documentation, coding, or testing, -the following information should give you some ideas. -More relevant information might be available from -@uref{ftp://alpha.gnu.org/gnu/g77/projects/}. - -@menu -* Efficiency:: Make @code{g77} itself compile code faster. -* Better Optimization:: Teach @code{g77} to generate faster code. -* Simplify Porting:: Make @code{g77} easier to configure, build, - and install. -* More Extensions:: Features many users won't know to ask for. -* Machine Model:: @code{g77} should better leverage @code{gcc}. -* Internals Documentation:: Make maintenance easier. -* Internals Improvements:: Make internals more robust. -* Better Diagnostics:: Make using @code{g77} on new code easier. -@end menu - -@node Efficiency -@section Improve Efficiency -@cindex efficiency - -Don't bother doing any performance analysis until most of the -following items are taken care of, because there's no question -they represent serious space/time problems, although some of -them show up only given certain kinds of (popular) input. - -@itemize @bullet -@item -Improve @code{malloc} package and its uses to specify more info about -memory pools and, where feasible, use obstacks to implement them. - -@item -Skip over uninitialized portions of aggregate areas (arrays, -@code{COMMON} areas, @code{EQUIVALENCE} areas) so zeros need not be output. -This would reduce memory usage for large initialized aggregate -areas, even ones with only one initialized element. - -As of version 0.5.18, a portion of this item has already been -accomplished. - -@item -Prescan the statement (in @file{sta.c}) so that the nature of the statement -is determined as much as possible by looking entirely at its form, -and not looking at any context (previous statements, including types -of symbols). -This would allow ripping out of the statement-confirmation, -symbol retraction/confirmation, and diagnostic inhibition -mechanisms. -Plus, it would result in much-improved diagnostics. -For example, @samp{CALL some-intrinsic(@dots{})}, where the intrinsic -is not a subroutine intrinsic, would result actual error instead of the -unimplemented-statement catch-all. - -@item -Throughout @code{g77}, don't pass line/column pairs where -a simple @code{ffewhere} type, which points to the error as much as is -desired by the configuration, will do, and don't pass @code{ffelexToken} types -where a simple @code{ffewhere} type will do. -Then, allow new default -configuration of @code{ffewhere} such that the source line text is not -preserved, and leave it to things like Emacs' next-error function -to point to them (now that @samp{next-error} supports column, -or, perhaps, character-offset, numbers). -The change in calling sequences should improve performance somewhat, -as should not having to save source lines. -(Whether this whole -item will improve performance is questionable, but it should -improve maintainability.) - -@item -Handle @samp{DATA (A(I),I=1,1000000)/1000000*2/} more efficiently, especially -as regards the assembly output. -Some of this might require improving -the back end, but lots of improvement in space/time required in @code{g77} -itself can be fairly easily obtained without touching the back end. -Maybe type-conversion, where necessary, can be speeded up as well in -cases like the one shown (converting the @samp{2} into @samp{2.}). - -@item -If analysis shows it to be worthwhile, optimize @file{lex.c}. - -@item -Consider redesigning @file{lex.c} to not need any feedback -during tokenization, by keeping track of enough parse state on its -own. -@end itemize - -@node Better Optimization -@section Better Optimization -@cindex optimization, better -@cindex code generation, improving - -Much of this work should be put off until after @code{g77} has -all the features necessary for its widespread acceptance as a -useful F77 compiler. -However, perhaps this work can be done in parallel during -the feature-adding work. - -@itemize @bullet -@item -Do the equivalent of the trick of putting @samp{extern inline} in front -of every function definition in @code{libg2c} and #include'ing the resulting -file in @code{f2c}+@code{gcc}---that is, inline all run-time-library functions -that are at all worth inlining. -(Some of this has already been done, such as for integral exponentiation.) - -@item -When doing @samp{CHAR_VAR = CHAR_FUNC(@dots{})}, -and it's clear that types line up -and @samp{CHAR_VAR} is addressable or not a @code{VAR_DECL}, -make @samp{CHAR_VAR}, not a -temporary, be the receiver for @samp{CHAR_FUNC}. -(This is now done for @code{COMPLEX} variables.) - -@item -Design and implement Fortran-specific optimizations that don't -really belong in the back end, or where the front end needs to -give the back end more info than it currently does. - -@item -Design and implement a new run-time library interface, with the -code going into @code{libgcc} so no special linking is required to -link Fortran programs using standard language features. -This library -would speed up lots of things, from I/O (using precompiled formats, -doing just one, or, at most, very few, calls for arrays or array sections, -and so on) to general computing (array/section implementations of -various intrinsics, implementation of commonly performed loops that -aren't likely to be optimally compiled otherwise, etc.). - -Among the important things the library would do are: - -@itemize @bullet -@item -Be a one-stop-shop-type -library, hence shareable and usable by all, in that what are now -library-build-time options in @code{libg2c} would be moved at least to the -@code{g77} compile phase, if not to finer grains (such as choosing how -list-directed I/O formatting is done by default at @code{OPEN} time, for -preconnected units via options or even statements in the main program -unit, maybe even on a per-I/O basis with appropriate pragma-like -devices). -@end itemize - -@item -Probably requiring the new library design, change interface to -normally have @code{COMPLEX} functions return their values in the way -@code{gcc} would if they were declared @code{__complex__ float}, -rather than using -the mechanism currently used by @code{CHARACTER} functions (whereby the -functions are compiled as returning void and their first arg is -a pointer to where to store the result). -(Don't append underscores to -external names for @code{COMPLEX} functions in some cases once @code{g77} uses -@code{gcc} rather than @code{f2c} calling conventions.) - -@item -Do something useful with @code{doiter} references where possible. -For example, @samp{CALL FOO(I)} cannot modify @samp{I} if within -a @code{DO} loop that uses @samp{I} as the -iteration variable, and the back end might find that info useful -in determining whether it needs to read @samp{I} back into a register after -the call. -(It normally has to do that, unless it knows @samp{FOO} never -modifies its passed-by-reference argument, which is rarely the case -for Fortran-77 code.) -@end itemize - -@node Simplify Porting -@section Simplify Porting -@cindex porting, simplify -@cindex simplify porting - -Making @code{g77} easier to configure, port, build, and install, either -as a single-system compiler or as a cross-compiler, would be -very useful. - -@itemize @bullet -@item -A new library (replacing @code{libg2c}) should improve portability as well as -produce more optimal code. -Further, @code{g77} and the new library should -conspire to simplify naming of externals, such as by removing unnecessarily -added underscores, and to reduce/eliminate the possibility of naming -conflicts, while making debugger more straightforward. - -Also, it should -make multi-language applications more feasible, such as by providing -Fortran intrinsics that get Fortran unit numbers given C @code{FILE *} -descriptors. - -@item -Possibly related to a new library, @code{g77} should produce the equivalent -of a @code{gcc} @samp{main(argc, argv)} function when it compiles a -main program unit, instead of compiling something that must be -called by a library -implementation of @code{main()}. - -This would do many useful things such as -provide more flexibility in terms of setting up exception handling, -not requiring programmers to start their debugging sessions with -@kbd{breakpoint MAIN__} followed by @kbd{run}, and so on. - -@item -The GBE needs to understand the difference between alignment -requirements and desires. -For example, on Intel x86 machines, @code{g77} currently imposes -overly strict alignment requirements, due to the back end, but it -would be useful for Fortran and C programmers to be able to override -these @emph{recommendations} as long as they don't violate the actual -processor @emph{requirements}. -@end itemize - -@node More Extensions -@section More Extensions -@cindex extensions, more - -These extensions are not the sort of things users ask for ``by name'', -but they might improve the usability of @code{g77}, and Fortran in -general, in the long run. -Some of these items really pertain to improving @code{g77} internals -so that some popular extensions can be more easily supported. - -@itemize @bullet -@item -Look through all the documentation on the GNU Fortran language, -dialects, compiler, missing features, bugs, and so on. -Many mentions of incomplete or missing features are -sprinkled throughout. -It is not worth repeating them here. - -@item -Consider adding a @code{NUMERIC} type to designate typeless numeric constants, -named and unnamed. -The idea is to provide a forward-looking, effective -replacement for things like the old-style @code{PARAMETER} statement -when people -really need typelessness in a maintainable, portable, clearly documented -way. -Maybe @code{TYPELESS} would include @code{CHARACTER}, @code{POINTER}, -and whatever else might come along. -(This is not really a call for polymorphism per se, just -an ability to express limited, syntactic polymorphism.) - -@item -Support @samp{OPEN(@dots{},KEY=(@dots{}),@dots{})}. - -@item -Support arbitrary file unit numbers, instead of limiting them -to 0 through @samp{MXUNIT-1}. -(This is a @code{libg2c} issue.) - -@item -@samp{OPEN(NOSPANBLOCKS,@dots{})} is treated as -@samp{OPEN(UNIT=NOSPANBLOCKS,@dots{})}, so a -later @code{UNIT=} in the first example is invalid. -Make sure this is what users of this feature would expect. - -@item -Currently @code{g77} disallows @samp{READ(1'10)} since -it is an obnoxious syntax, but -supporting it might be pretty easy if needed. -More details are needed, such -as whether general expressions separated by an apostrophe are supported, -or maybe the record number can be a general expression, and so on. - -@item -Support @code{STRUCTURE}, @code{UNION}, @code{MAP}, and @code{RECORD} -fully. -Currently there is no support at all -for @code{%FILL} in @code{STRUCTURE} and related syntax, -whereas the rest of the -stuff has at least some parsing support. -This requires either major -changes to @code{libg2c} or its replacement. - -@item -F90 and @code{g77} probably disagree about label scoping relative to -@code{INTERFACE} and @code{END INTERFACE}, and their contained -procedure interface bodies (blocks?). - -@item -@code{ENTRY} doesn't support F90 @code{RESULT()} yet, -since that was added after S8.112. - -@item -Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent -with the final form of the standard (it was vague at S8.112). - -@item -It seems to be an ``open'' question whether a file, immediately after being -@code{OPEN}ed,is positioned at the beginning, the end, or wherever---it -might be nice to offer an option of opening to ``undefined'' status, requiring -an explicit absolute-positioning operation to be performed before any -other (besides @code{CLOSE}) to assist in making applications port to systems -(some IBM?) that @code{OPEN} to the end of a file or some such thing. -@end itemize - -@node Machine Model -@section Machine Model - -This items pertain to generalizing @code{g77}'s view of -the machine model to more fully accept whatever the GBE -provides it via its configuration. - -@itemize @bullet -@item -Switch to using @code{REAL_VALUE_TYPE} to represent floating-point constants -exclusively so the target float format need not be required. -This -means changing the way @code{g77} handles initialization of aggregate areas -having more than one type, such as @code{REAL} and @code{INTEGER}, -because currently -it initializes them as if they were arrays of @code{char} and uses the -bit patterns of the constants of the various types in them to determine -what to stuff in elements of the arrays. - -@item -Rely more and more on back-end info and capabilities, especially in the -area of constants (where having the @code{g77} front-end's IL just store -the appropriate tree nodes containing constants might be best). - -@item -Suite of C and Fortran programs that a user/administrator can run on a -machine to help determine the configuration for @code{g77} before building -and help determine if the compiler works (especially with whatever -libraries are installed) after building. -@end itemize - -@node Internals Documentation -@section Internals Documentation - -Better info on how @code{g77} works and how to port it is needed. -Much of this should be done only after the redesign planned for -0.6 is complete. - -@xref{Front End}, which contains some information -on @code{g77} internals. - -@node Internals Improvements -@section Internals Improvements - -Some more items that would make @code{g77} more reliable -and easier to maintain: - -@itemize @bullet -@item -Generally make expression handling focus -more on critical syntax stuff, leaving semantics to callers. -For example, -anything a caller can check, semantically, let it do so, rather -than having @file{expr.c} do it. -(Exceptions might include things like -diagnosing @samp{FOO(I--K:)=BAR} where @samp{FOO} is a @code{PARAMETER}---if -it seems -important to preserve the left-to-right-in-source order of production -of diagnostics.) - -@item -Come up with better naming conventions for @samp{-D} to establish requirements -to achieve desired implementation dialect via @file{proj.h}. - -@item -Clean up used tokens and @code{ffewhere}s in @code{ffeglobal_terminate_1}. - -@item -Replace @file{sta.c} @code{outpooldisp} mechanism with @code{malloc_pool_use}. - -@item -Check for @code{opANY} in more places in @file{com.c}, @file{std.c}, -and @file{ste.c}, and get rid of the @samp{opCONVERT(opANY)} kludge -(after determining if there is indeed no real need for it). - -@item -Utility to read and check @file{bad.def} messages and their references in the -code, to make sure calls are consistent with message templates. - -@item -Search and fix @samp{&ffe@dots{}} and similar so that -@samp{ffe@dots{}ptr@dots{}} macros are -available instead (a good argument for wishing this could have written all -this stuff in C++, perhaps). -On the other hand, it's questionable whether this sort of -improvement is really necessary, given the availability of -tools such as Emacs and Perl, which make finding any -address-taking of structure members easy enough? - -@item -Some modules truly export the member names of their structures (and the -structures themselves), maybe fix this, and fix other modules that just -appear to as well (by appending @samp{_}, though it'd be ugly and probably -not worth the time). - -@item -Implement C macros @samp{RETURNS(value)} and @samp{SETS(something,value)} -in @file{proj.h} -and use them throughout @code{g77} source code (especially in the definitions -of access macros in @samp{.h} files) so they can be tailored -to catch code writing into a @samp{RETURNS()} or reading from a @samp{SETS()}. - -@item -Decorate throughout with @code{const} and other such stuff. - -@item -All F90 notational derivations in the source code are still based -on the S8.112 version of the draft standard. -Probably should update -to the official standard, or put documentation of the rules as used -in the code@dots{}uh@dots{}in the code. - -@item -Some @code{ffebld_new} calls (those outside of @file{ffeexpr.c} or -inside but invoked via paths not involving @code{ffeexpr_lhs} or -@code{ffeexpr_rhs}) might be creating things -in improper pools, leading to such things staying around too long or -(doubtful, but possible and dangerous) not long enough. - -@item -Some @code{ffebld_list_new} (or whatever) calls might not be matched by -@code{ffebld_list_bottom} (or whatever) calls, which might someday matter. -(It definitely is not a problem just yet.) - -@item -Probably not doing clean things when we fail to @code{EQUIVALENCE} something -due to alignment/mismatch or other problems---they end up without -@code{ffestorag} objects, so maybe the backend (and other parts of the front -end) can notice that and handle like an @code{opANY} (do what it wants, just -don't complain or crash). -Most of this seems to have been addressed -by now, but a code review wouldn't hurt. -@end itemize - -@node Better Diagnostics -@section Better Diagnostics - -These are things users might not ask about, or that need to -be looked into, before worrying about. -Also here are items that involve reducing unnecessary diagnostic -clutter. - -@itemize @bullet -@item -When @code{FUNCTION} and @code{ENTRY} point types disagree (@code{CHARACTER} -lengths, type classes, and so on), -@code{ANY}-ize the offending @code{ENTRY} point and any @emph{new} dummies -it specifies. - -@item -Speed up and improve error handling for data when repeat-count is -specified. -For example, don't output 20 unnecessary messages after the -first necessary one for: - -@smallexample -INTEGER X(20) -CONTINUE -DATA (X(I), J= 1, 20) /20*5/ -END -@end smallexample - -@noindent -(The @code{CONTINUE} statement ensures the @code{DATA} statement -is processed in the context of executable, not specification, -statements.) -@end itemize - -@include ffe.texi - -@end ifset - -@ifset USING -@node Diagnostics -@chapter Diagnostics -@cindex diagnostics - -Some diagnostics produced by @code{g77} require sufficient explanation -that the explanations are given below, and the diagnostics themselves -identify the appropriate explanation. - -Identification uses the GNU Info format---specifically, the @code{info} -command that displays the explanation is given within square -brackets in the diagnostic. -For example: - -@smallexample -foo.f:5: Invalid statement [info -f g77 M FOOEY] -@end smallexample - -More details about the above diagnostic is found in the @code{g77} Info -documentation, menu item @samp{M}, submenu item @samp{FOOEY}, -which is displayed by typing the UNIX command -@samp{info -f g77 M FOOEY}. - -Other Info readers, such as EMACS, may be just as easily used to display -the pertinent node. -In the above example, @samp{g77} is the Info document name, -@samp{M} is the top-level menu item to select, -and, in that node (named @samp{Diagnostics}, the name of -this chapter, which is the very text you're reading now), -@samp{FOOEY} is the menu item to select. - -@iftex -In this printed version of the @code{g77} manual, the above example -points to a section, below, entitled @samp{FOOEY}---though, of course, -as the above is just a sample, no such section exists. -@end iftex - -@menu -* CMPAMBIG:: Ambiguous use of intrinsic. -* EXPIMP:: Intrinsic used explicitly and implicitly. -* INTGLOB:: Intrinsic also used as name of global. -* LEX:: Various lexer messages -* GLOBALS:: Disagreements about globals. -* LINKFAIL:: When linking @code{f771} fails. -* Y2KBAD:: Use of non-Y2K-compliant intrinsic. -@end menu - -@node CMPAMBIG -@section @code{CMPAMBIG} - -@noindent -@smallexample -Ambiguous use of intrinsic @var{intrinsic} @dots{} -@end smallexample - -The type of the argument to the invocation of the @var{intrinsic} -intrinsic is a @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}. -Typically, it is @code{COMPLEX(KIND=2)}, also known as -@code{DOUBLE COMPLEX}. - -The interpretation of this invocation depends on the particular -dialect of Fortran for which the code was written. -Some dialects convert the real part of the argument to -@code{REAL(KIND=1)}, thus losing precision; other dialects, -and Fortran 90, do no such conversion. - -So, GNU Fortran rejects such invocations except under certain -circumstances, to avoid making an incorrect assumption that results -in generating the wrong code. - -To determine the dialect of the program unit, perhaps even whether -that particular invocation is properly coded, determine how the -result of the intrinsic is used. - -The result of @var{intrinsic} is expected (by the original programmer) -to be @code{REAL(KIND=1)} (the non-Fortran-90 interpretation) if: - -@itemize @bullet -@item -It is passed as an argument to a procedure that explicitly or -implicitly declares that argument @code{REAL(KIND=1)}. - -For example, -a procedure with no @code{DOUBLE PRECISION} or @code{IMPLICIT DOUBLE PRECISION} -statement specifying the dummy argument corresponding to an -actual argument of @samp{REAL(Z)}, where @samp{Z} is declared -@code{DOUBLE COMPLEX}, strongly suggests that the programmer -expected @samp{REAL(Z)} to return @code{REAL(KIND=1)} instead -of @code{REAL(KIND=2)}. - -@item -It is used in a context that would otherwise not include -any @code{REAL(KIND=2)} but where treating the @var{intrinsic} -invocation as @code{REAL(KIND=2)} would result in unnecessary -promotions and (typically) more expensive operations on the -wider type. - -For example: - -@smallexample -DOUBLE COMPLEX Z -@dots{} -R(1) = T * REAL(Z) -@end smallexample - -The above example suggests the programmer expected the real part -of @samp{Z} to be converted to @code{REAL(KIND=1)} before being -multiplied by @samp{T} (presumed, along with @samp{R} above, to -be type @code{REAL(KIND=1)}). - -Otherwise, the conversion would have to be delayed until after -the multiplication, requiring not only an extra conversion -(of @samp{T} to @code{REAL(KIND=2)}), but a (typically) more -expensive multiplication (a double-precision multiplication instead -of a single-precision one). -@end itemize - -The result of @var{intrinsic} is expected (by the original programmer) -to be @code{REAL(KIND=2)} (the Fortran 90 interpretation) if: - -@itemize @bullet -@item -It is passed as an argument to a procedure that explicitly or -implicitly declares that argument @code{REAL(KIND=2)}. - -For example, a procedure specifying a @code{DOUBLE PRECISION} -dummy argument corresponding to an -actual argument of @samp{REAL(Z)}, where @samp{Z} is declared -@code{DOUBLE COMPLEX}, strongly suggests that the programmer -expected @samp{REAL(Z)} to return @code{REAL(KIND=2)} instead -of @code{REAL(KIND=1)}. - -@item -It is used in an expression context that includes -other @code{REAL(KIND=2)} operands, -or is assigned to a @code{REAL(KIND=2)} variable or array element. - -For example: - -@smallexample -DOUBLE COMPLEX Z -DOUBLE PRECISION R, T -@dots{} -R(1) = T * REAL(Z) -@end smallexample - -The above example suggests the programmer expected the real part -of @samp{Z} to @emph{not} be converted to @code{REAL(KIND=1)} -by the @code{REAL()} intrinsic. - -Otherwise, the conversion would have to be immediately followed -by a conversion back to @code{REAL(KIND=2)}, losing -the original, full precision of the real part of @code{Z}, -before being multiplied by @samp{T}. -@end itemize - -Once you have determined whether a particular invocation of @var{intrinsic} -expects the Fortran 90 interpretation, you can: - -@itemize @bullet -@item -Change it to @samp{DBLE(@var{expr})} (if @var{intrinsic} is -@code{REAL}) or @samp{DIMAG(@var{expr})} (if @var{intrinsic} -is @code{AIMAG}) -if it expected the Fortran 90 interpretation. - -This assumes @var{expr} is @code{COMPLEX(KIND=2)}---if it is -some other type, such as @code{COMPLEX*32}, you should use the -appropriate intrinsic, such as the one to convert to @code{REAL*16} -(perhaps @code{DBLEQ()} in place of @code{DBLE()}, and -@code{QIMAG()} in place of @code{DIMAG()}). - -@item -Change it to @samp{REAL(@var{intrinsic}(@var{expr}))}, -otherwise. -This converts to @code{REAL(KIND=1)} in all working -Fortran compilers. -@end itemize - -If you don't want to change the code, and you are certain that all -ambiguous invocations of @var{intrinsic} in the source file have -the same expectation regarding interpretation, you can: - -@itemize @bullet -@item -Compile with the @code{g77} option @samp{-ff90}, to enable the -Fortran 90 interpretation. - -@item -Compile with the @code{g77} options @samp{-fno-f90 -fugly-complex}, -to enable the non-Fortran-90 interpretations. -@end itemize - -@xref{REAL() and AIMAG() of Complex}, for more information on this -issue. - -Note: If the above suggestions don't produce enough evidence -as to whether a particular program expects the Fortran 90 -interpretation of this ambiguous invocation of @var{intrinsic}, -there is one more thing you can try. - -If you have access to most or all the compilers used on the -program to create successfully tested and deployed executables, -read the documentation for, and @emph{also} test out, each compiler -to determine how it treats the @var{intrinsic} intrinsic in -this case. -(If all the compilers don't agree on an interpretation, there -might be lurking bugs in the deployed versions of the program.) - -The following sample program might help: - -@cindex JCB003 program -@smallexample - PROGRAM JCB003 -C -C Written by James Craig Burley 1997-02-23. -C -C Determine how compilers handle non-standard REAL -C and AIMAG on DOUBLE COMPLEX operands. -C - DOUBLE COMPLEX Z - REAL R - Z = (3.3D0, 4.4D0) - R = Z - CALL DUMDUM(Z, R) - R = REAL(Z) - R - IF (R .NE. 0.) PRINT *, 'REAL() is Fortran 90' - IF (R .EQ. 0.) PRINT *, 'REAL() is not Fortran 90' - R = 4.4D0 - CALL DUMDUM(Z, R) - R = AIMAG(Z) - R - IF (R .NE. 0.) PRINT *, 'AIMAG() is Fortran 90' - IF (R .EQ. 0.) PRINT *, 'AIMAG() is not Fortran 90' - END -C -C Just to make sure compiler doesn't use naive flow -C analysis to optimize away careful work above, -C which might invalidate results.... -C - SUBROUTINE DUMDUM(Z, R) - DOUBLE COMPLEX Z - REAL R - END -@end smallexample - -If the above program prints contradictory results on a -particular compiler, run away! - -@node EXPIMP -@section @code{EXPIMP} - -@noindent -@smallexample -Intrinsic @var{intrinsic} referenced @dots{} -@end smallexample - -The @var{intrinsic} is explicitly declared in one program -unit in the source file and implicitly used as an intrinsic -in another program unit in the same source file. - -This diagnostic is designed to catch cases where a program -might depend on using the name @var{intrinsic} as an intrinsic -in one program unit and as a global name (such as the name -of a subroutine or function) in another, but @code{g77} recognizes -the name as an intrinsic in both cases. - -After verifying that the program unit making implicit use -of the intrinsic is indeed written expecting the intrinsic, -add an @samp{INTRINSIC @var{intrinsic}} statement to that -program unit to prevent this warning. - -This and related warnings are disabled by using -the @samp{-Wno-globals} option when compiling. - -Note that this warning is not issued for standard intrinsics. -Standard intrinsics include those described in the FORTRAN 77 -standard and, if @samp{-ff90} is specified, those described -in the Fortran 90 standard. -Such intrinsics are not as likely to be confused with user -procedures as intrinsics provided as extensions to the -standard by @code{g77}. - -@node INTGLOB -@section @code{INTGLOB} - -@noindent -@smallexample -Same name `@var{intrinsic}' given @dots{} -@end smallexample - -The name @var{intrinsic} is used for a global entity (a common -block or a program unit) in one program unit and implicitly -used as an intrinsic in another program unit. - -This diagnostic is designed to catch cases where a program -intends to use a name entirely as a global name, but @code{g77} -recognizes the name as an intrinsic in the program unit that -references the name, a situation that would likely produce -incorrect code. - -For example: - -@smallexample -INTEGER FUNCTION TIME() -@dots{} -END -@dots{} -PROGRAM SAMP -INTEGER TIME -PRINT *, 'Time is ', TIME() -END -@end smallexample - -The above example defines a program unit named @samp{TIME}, but -the reference to @samp{TIME} in the main program unit @samp{SAMP} -is normally treated by @code{g77} as a reference to the intrinsic -@code{TIME()} (unless a command-line option that prevents such -treatment has been specified). - -As a result, the program @samp{SAMP} will @emph{not} -invoke the @samp{TIME} function in the same source file. - -Since @code{g77} recognizes @code{libU77} procedures as -intrinsics, and since some existing code uses the same names -for its own procedures as used by some @code{libU77} -procedures, this situation is expected to arise often enough -to make this sort of warning worth issuing. - -After verifying that the program unit making implicit use -of the intrinsic is indeed written expecting the intrinsic, -add an @samp{INTRINSIC @var{intrinsic}} statement to that -program unit to prevent this warning. - -Or, if you believe the program unit is designed to invoke the -program-defined procedure instead of the intrinsic (as -recognized by @code{g77}), add an @samp{EXTERNAL @var{intrinsic}} -statement to the program unit that references the name to -prevent this warning. - -This and related warnings are disabled by using -the @samp{-Wno-globals} option when compiling. - -Note that this warning is not issued for standard intrinsics. -Standard intrinsics include those described in the FORTRAN 77 -standard and, if @samp{-ff90} is specified, those described -in the Fortran 90 standard. -Such intrinsics are not as likely to be confused with user -procedures as intrinsics provided as extensions to the -standard by @code{g77}. - -@node LEX -@section @code{LEX} - -@noindent -@smallexample -Unrecognized character @dots{} -Invalid first character @dots{} -Line too long @dots{} -Non-numeric character @dots{} -Continuation indicator @dots{} -Label at @dots{} invalid with continuation line indicator @dots{} -Character constant @dots{} -Continuation line @dots{} -Statement at @dots{} begins with invalid token -@end smallexample - -Although the diagnostics identify specific problems, they can -be produced when general problems such as the following occur: - -@itemize @bullet -@item -The source file contains something other than Fortran code. - -If the code in the file does not look like many of the examples -elsewhere in this document, it might not be Fortran code. -(Note that Fortran code often is written in lower case letters, -while the examples in this document use upper case letters, -for stylistic reasons.) - -For example, if the file contains lots of strange-looking -characters, it might be APL source code; if it contains lots -of parentheses, it might be Lisp source code; if it -contains lots of bugs, it might be C++ source code. - -@item -The source file contains free-form Fortran code, but @samp{-ffree-form} -was not specified on the command line to compile it. - -Free form is a newer form for Fortran code. -The older, classic form is called fixed form. - -@cindex continuation character -@cindex characters, continuation -Fixed-form code is visually fairly distinctive, because -numerical labels and comments are all that appear in -the first five columns of a line, the sixth column is -reserved to denote continuation lines, -and actual statements start at or beyond column 7. -Spaces generally are not significant, so if you -see statements such as @samp{REALX,Y} and @samp{DO10I=1,100}, -you are looking at fixed-form code. -@cindex * -@cindex asterisk -Comment lines are indicated by the letter @samp{C} or the symbol -@samp{*} in column 1. -@cindex trailing comment -@cindex comment -@cindex characters, comment -@cindex ! -@cindex exclamation point -(Some code uses @samp{!} or @samp{/*} to begin in-line comments, -which many compilers support.) - -Free-form code is distinguished from fixed-form source -primarily by the fact that statements may start anywhere. -(If lots of statements start in columns 1 through 6, -that's a strong indicator of free-form source.) -Consecutive keywords must be separated by spaces, so -@samp{REALX,Y} is not valid, while @samp{REAL X,Y} is. -There are no comment lines per se, but @samp{!} starts a -comment anywhere in a line (other than within a character or -Hollerith constant). - -@xref{Source Form}, for more information. - -@item -The source file is in fixed form and has been edited without -sensitivity to the column requirements. - -Statements in fixed-form code must be entirely contained within -columns 7 through 72 on a given line. -Starting them ``early'' is more likely to result in diagnostics -than finishing them ``late'', though both kinds of errors are -often caught at compile time. - -For example, if the following code fragment is edited by following -the commented instructions literally, the result, shown afterward, -would produce a diagnostic when compiled: - -@smallexample -C On XYZZY systems, remove "C" on next line: -C CALL XYZZY_RESET -@end smallexample - -The result of editing the above line might be: - -@smallexample -C On XYZZY systems, remove "C" on next line: - CALL XYZZY_RESET -@end smallexample - -However, that leaves the first @samp{C} in the @code{CALL} -statement in column 6, making it a comment line, which is -not really what the author intended, and which is likely -to result in one of the above-listed diagnostics. - -@emph{Replacing} the @samp{C} in column 1 with a space -is the proper change to make, to ensure the @code{CALL} -keyword starts in or after column 7. - -Another common mistake like this is to forget that fixed-form -source lines are significant through only column 72, and that, -normally, any text beyond column 72 is ignored or is diagnosed -at compile time. - -@xref{Source Form}, for more information. - -@item -The source file requires preprocessing, and the preprocessing -is not being specified at compile time. - -A source file containing lines beginning with @code{#define}, -@code{#include}, @code{#if}, and so on is likely one that -requires preprocessing. - -If the file's suffix is @samp{.f}, @samp{.for}, or @samp{.FOR}, -the file normally will be compiled @emph{without} preprocessing -by @code{g77}. - -Change the file's suffix from @samp{.f} to @samp{.F} -(or, on systems with case-insensitive file names, -to @samp{.fpp} or @samp{.FPP}), -from @samp{.for} to @samp{.fpp}, -or from @samp{.FOR} to @samp{.FPP}. -@code{g77} compiles files with such names @emph{with} -preprocessing. - -@pindex cpp -@cindex preprocessor -@cindex cpp program -@cindex programs, cpp -@cindex @samp{-x f77-cpp-input} option -@cindex options, @samp{-x f77-cpp-input} -Or, learn how to use @code{gcc}'s @samp{-x} option to specify -the language @samp{f77-cpp-input} for Fortran files that -require preprocessing. -@xref{Overall Options,,gcc,Using and Porting GNU CC}. - -@item -The source file is preprocessed, and the results of preprocessing -result in syntactic errors that are not necessarily obvious to -someone examining the source file itself. - -Examples of errors resulting from preprocessor macro expansion -include exceeding the line-length limit, improperly starting, -terminating, or incorporating the apostrophe or double-quote in -a character constant, improperly forming a Hollerith constant, -and so on. - -@xref{Overall Options,,Options Controlling the Kind of Output}, -for suggestions about how to use, and not use, preprocessing -for Fortran code. -@end itemize - -@node GLOBALS -@section @code{GLOBALS} - -@noindent -@smallexample -Global name @var{name} defined at @dots{} already defined@dots{} -Global name @var{name} at @dots{} has different type@dots{} -Too many arguments passed to @var{name} at @dots{} -Too few arguments passed to @var{name} at @dots{} -Argument #@var{n} of @var{name} is @dots{} -@end smallexample - -These messages all identify disagreements about the -global procedure named @var{name} among different program units -(usually including @var{name} itself). - -Whether a particular disagreement is reported -as a warning or an error -can depend on the relative order -of the disagreeing portions of the source file. - -Disagreements between a procedure invocation -and the @emph{subsequent} procedure itself -are, usually, diagnosed as errors -when the procedure itself @emph{precedes} the invocation. -Other disagreements are diagnosed via warnings. - -@cindex forward references -@cindex in-line code -@cindex compilation, in-line -This distinction, between warnings and errors, -is due primarily to the present tendency of the @code{gcc} back end -to inline only those procedure invocations that are -@emph{preceded} by the corresponding procedure definitions. -If the @code{gcc} back end is changed -to inline ``forward references'', -in which invocations precede definitions, -the @code{g77} front end will be changed -to treat both orderings as errors, accordingly. - -The sorts of disagreements that are diagnosed by @code{g77} include -whether a procedure is a subroutine or function; -if it is a function, the type of the return value of the procedure; -the number of arguments the procedure accepts; -and the type of each argument. - -Disagreements regarding global names among program units -in a Fortran program @emph{should} be fixed in the code itself. -However, if that is not immediately practical, -and the code has been working for some time, -it is possible it will work -when compiled with the @samp{-fno-globals} option. - -The @samp{-fno-globals} option -causes these diagnostics to all be warnings -and disables all inlining of references to global procedures -(to avoid subsequent compiler crashes and bad-code generation). -Use of the @samp{-Wno-globals} option as well as @samp{-fno-globals} -suppresses all of these diagnostics. -(@samp{-Wno-globals} by itself disables only the warnings, -not the errors.) - -After using @samp{-fno-globals} to work around these problems, -it is wise to stop using that option and address them by fixing -the Fortran code, because such problems, while they might not -actually result in bugs on some systems, indicate that the code -is not as portable as it could be. -In particular, the code might appear to work on a particular -system, but have bugs that affect the reliability of the data -without exhibiting any other outward manifestations of the bugs. - -@node LINKFAIL -@section @code{LINKFAIL} - -@noindent -@smallexample -If the above command failed due to an unresolved reference -to strtoul, _strtoul, bsearch, _bsearch, or similar, see -[info -f g77 M LINKFAIL] (a node in the g77 documentation) -for information on what causes this, how to work around -the problem by editing $@{srcdir@}/proj.c, and what else to do. -@end smallexample - -@xref{Missing strtoul or bsearch}, for more information on -this problem, -which occurs only in releases of @code{g77} -based on @code{gcc}. -(It does not occur in @code{egcs}.) - -On AIX 4.1, @code{g77} might not build with the native (non-GNU) tools -due to a linker bug in coping with the @samp{-bbigtoc} option which -leads to a @samp{Relocation overflow} error. The GNU linker is not -recommended on current AIX versions, though; it was developed under a -now-unsupported version. This bug is said to be fixed by `update PTF -U455193 for APAR IX75823'. - -Compiling with @samp{-mminimal-toc} -might solve this problem, e.g.@: by adding -@smallexample -BOOT_CFLAGS='-mminimal-toc -O2 -g' -@end smallexample -to the @code{make bootstrap} command line. - -@node Y2KBAD -@section @code{Y2KBAD} -@cindex Y2K compliance -@cindex Year 2000 compliance - -@noindent -@smallexample -Intrinsic `@var{name}', invoked at (^), known to be non-Y2K-compliant@dots{} -@end smallexample - -This diagnostic indicates that -the specific intrinsic invoked by the name @var{name} -is known to have an interface -that is not Year-2000 (Y2K) compliant. - -@xref{Year 2000 (Y2K) Problems}. - -@end ifset - -@node Index -@unnumbered Index - -@printindex cp -@summarycontents -@contents -@bye |