\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) @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 } 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)}, 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)} 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) @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) @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) @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 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.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