diff options
Diffstat (limited to 'man1p/fort77.1p')
| -rw-r--r-- | man1p/fort77.1p | 500 |
1 files changed, 500 insertions, 0 deletions
diff --git a/man1p/fort77.1p b/man1p/fort77.1p new file mode 100644 index 000000000..b860f70ca --- /dev/null +++ b/man1p/fort77.1p @@ -0,0 +1,500 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FORT77" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fort77 +.SH NAME +fort77 \- FORTRAN compiler (\fBFORTRAN\fP) +.SH SYNOPSIS +.LP +\fBfort77\fP \fB[\fP\fB-c\fP\fB][\fP\fB-g\fP\fB][\fP\fB-L\fP +\fIdirectory\fP\fB]\fP\fB...\fP \fB[\fP\fB-O\fP \fIoptlevel\fP\fB][\fP\fB-o\fP +\fIoutfile\fP\fB][\fP\fB-s\fP\fB][\fP\fB-w\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB\fP\fIoperand\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIfort77\fP utility is the interface to the FORTRAN compilation +system; it shall accept the full FORTRAN-77 language +defined by the ANSI\ X3.9-1978 standard. The system conceptually consists +of a compiler and link editor. The files referenced +by \fIoperand\fPs are compiled and linked to produce an executable +file. It is unspecified whether the linking occurs entirely +within the operation of \fIfort77\fP; some implementations may produce +objects that are not fully resolved until the file is +executed. +.LP +If the \fB-c\fP option is present, for all pathname operands of the +form \fIfile\fP \fB.f\fP, the files: +.sp +.RS +.nf + +\fB$(basename\fP \fIpathname\fP\fB.f).o +\fP +.fi +.RE +.LP +shall be created or overwritten as the result of successful compilation. +If the \fB-c\fP option is not specified, it is +unspecified whether such \fB.o\fP files are created or deleted for +the \fIfile\fP \fB.f\fP operands. +.LP +If there are no options that prevent link editing (such as \fB-c\fP) +and all operands compile and link without error, the +resulting executable file shall be written into the file named by +the \fB-o\fP option (if present) or to the file \fBa.out\fP. +The executable file shall be created as specified in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, except that +the file permissions shall be set to: +.sp +.RS +.nf + +S_IRWXO | S_IRWXG | S_IRWXU +.fi +.RE +.LP +and that the bits specified by the \fIumask\fP of the process shall +be cleared. +.SH OPTIONS +.LP +The \fIfort77\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, +except that: +.IP " *" 3 +The \fB-l\fP \fIlibrary\fP operands have the format of options, but +their position within a list of operands affects the order +in which libraries are searched. +.LP +.IP " *" 3 +The order of specifying the multiple \fB-L\fP options is significant. +.LP +.IP " *" 3 +Conforming applications shall specify each option separately; that +is, grouping option letters (for example, \fB-cg\fP) need +not be recognized by all implementations. +.LP +.LP +The following options shall be supported: +.TP 7 +\fB-c\fP +Suppress the link-edit phase of the compilation, and do not remove +any object files that are produced. +.TP 7 +\fB-g\fP +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be +modified by implementation-defined interactions with other options. +.TP 7 +\fB-s\fP +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using +the \fIexec\fP family of functions defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 has been removed +(stripped). If both \fB-g\fP and \fB-s\fP options are present, the +action taken is unspecified. +.TP 7 +\fB-o\ \fP \fIoutfile\fP +Use the pathname \fIoutfile\fP, instead of the default \fBa.out\fP, +for the executable file produced. If the \fB-o\fP option +is present with \fB-c\fP, the result is unspecified. +.TP 7 +\fB-L\ \fP \fIdirectory\fP +Change the algorithm of searching for the libraries named in \fB-l\fP +operands to look in the directory named by the +\fIdirectory\fP pathname before looking in the usual places. Directories +named in \fB-L\fP options shall be searched in the +specified order. At least ten instances of this option shall be supported +in a single \fIfort77\fP command invocation. If a +directory specified by a \fB-L\fP option contains a file named \fBlibf.a\fP, +the results are unspecified. +.TP 7 +\fB-O\ \fP \fIoptlevel\fP +Specify the level of code optimization. If the \fIoptlevel\fP option-argument +is the digit \fB'0'\fP , all special code +optimizations shall be disabled. If it is the digit \fB'1'\fP , the +nature of the optimization is unspecified. If the \fB-O\fP +option is omitted, the nature of the system's default optimization +is unspecified. It is unspecified whether code generated in the +presence of the \fB-O\fP 0 option is the same as that generated when +\fB-O\fP is omitted. Other \fIoptlevel\fP values may be +supported. +.TP 7 +\fB-w\fP +Suppress warnings. +.sp +.LP +Multiple instances of \fB-L\fP options can be specified. +.SH OPERANDS +.LP +An \fIoperand\fP is either in the form of a pathname or the form \fB-l\fP +\fIlibrary\fP. At least one operand of the pathname +form shall be specified. The following operands shall be supported: +.TP 7 +\fIfile.\fP\fBf\fP +The pathname of a FORTRAN source file to be compiled and optionally +passed to the link editor. The filename operand shall be of +this form if the \fB-c\fP option is used. +.TP 7 +\fIfile.\fP\fBa\fP +A library of object files typically produced by \fIar\fP, and passed +directly to the link +editor. Implementations may recognize implementation-defined suffixes +other than \fB.a\fP as denoting object file libraries. +.TP 7 +\fIfile.\fP\fBo\fP +An object file produced by \fIfort77\fP \fB-c\fP and passed directly +to the link editor. Implementations may recognize +implementation-defined suffixes other than \fB.o\fP as denoting object +files. +.sp +.LP +The processing of other files is implementation-defined. +.TP 7 +\fB-l\ \fP \fIlibrary\fP +(The letter ell.) Search the library named: +.sp +.RS +.nf + +\fBlib\fP\fIlibrary\fP\fB.a +\fP +.fi +.RE +.LP +A library is searched when its name is encountered, so the placement +of a \fB-l\fP operand is significant. Several standard +libraries can be specified in this manner, as described in the EXTENDED +DESCRIPTION section. Implementations may recognize +implementation-defined suffixes other than \fB.a\fP as denoting libraries. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +The input file shall be one of the following: a text file containing +FORTRAN source code; an object file in the format produced +by \fIfort77\fP \fB-c\fP; or a library of object files, in the format +produced by archiving zero or more object files, using \fIar\fP. Implementations +may supply additional utilities that produce files in these formats. +Additional input files are implementation-defined. +.LP +A <tab> encountered within the first six characters on a line of source +code shall cause the compiler to interpret the +following character as if it were the seventh character on the line +(that is, in column 7). +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfort77\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITMPDIR\fP +Determine the pathname that should override the default directory +for temporary files, if any. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. If +more than one \fIfile\fP operand ending in \fB.f\fP (or +possibly other unspecified suffixes) is given, for each such file: +.sp +.RS +.nf + +\fB"%s:\\n", <\fP\fIfile\fP\fB> +\fP +.fi +.RE +.LP +may be written to allow identification of the diagnostic message with +the appropriate input file. +.LP +This utility may produce warning messages about certain conditions +that do not warrant returning an error (non-zero) exit +value. +.SH OUTPUT FILES +.LP +Object files, listing files, and executable files shall be produced +in unspecified formats. +.SH EXTENDED DESCRIPTION +.SS Standard Libraries +.LP +The \fIfort77\fP utility shall recognize the following \fB-l\fP operand +for the standard library: +.TP 7 +\fB-l\ f\fP +This library contains all functions referenced in the ANSI\ X3.9-1978 +standard. This operand shall not be required to be +present to cause a search of this library. +.sp +.LP +In the absence of options that inhibit invocation of the link editor, +such as \fB-c\fP, the \fIfort77\fP utility shall cause +the equivalent of a \fB-l\ f\fP operand to be passed to the link editor +as the last \fB-l\fP operand, causing it to be +searched after all other object files and libraries are loaded. +.LP +It is unspecified whether the library \fBlibf.a\fP exists as a regular +file. The implementation may accept as \fB-l\fP +operands names of objects that do not exist as regular files. +.SS External Symbols +.LP +The FORTRAN compiler and link editor shall support the significance +of external symbols up to a length of at least 31 bytes; +case folding is permitted. The action taken upon encountering symbols +exceeding the implementation-defined maximum symbol length is +unspecified. +.LP +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4095 +external symbols total. A diagnostic message is written to standard +output if the implementation-defined limit is exceeded; other +actions are unspecified. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful compilation or link edit. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +When \fIfort77\fP encounters a compilation error, it shall write a +diagnostic to standard error and continue to compile other +source code operands. It shall return a non-zero exit status, but +it is implementation-defined whether an object module is created. +If the link edit is unsuccessful, a diagnostic message shall be written +to standard error, and \fIfort77\fP shall exit with a +non-zero status. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +The following usage example compiles \fBxyz.f\fP and creates the executable +file \fBfoo\fP: +.sp +.RS +.nf + +\fBfort77 -o foo xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP and creates the object +file \fBxyz.o\fP: +.sp +.RS +.nf + +\fBfort77 -c xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP and creates the executable +file \fBa.out\fP: +.sp +.RS +.nf + +\fBfort77 xyz.f +\fP +.fi +.RE +.LP +The following example compiles \fBxyz.f\fP, links it with \fBb.o\fP, +and creates the executable \fBa.out\fP: +.sp +.RS +.nf + +\fBfort77 xyz.f b.o +\fP +.fi +.RE +.SH RATIONALE +.LP +The name of this utility was chosen as \fIfort77\fP to parallel the +renaming of the C compiler. The name \fIf77\fP was not +chosen to avoid problems with historical implementations. The ANSI\ X3.9-1978 +standard was selected as a normative reference +because the ISO/IEC version of FORTRAN-77 has been superseded by the +ISO/IEC\ 1539:1990 standard (Fortran-90). +.LP +The file inclusion and symbol definition \fB#define\fP mechanisms +used by the \fIc99\fP +utility were not included in this volume of IEEE\ Std\ 1003.1-2001-even +though they are commonly implemented-since there is +no requirement that the FORTRAN compiler use the C preprocessor. +.LP +The \fB-onetrip\fP option was not included in this volume of IEEE\ Std\ 1003.1-2001, +even though many historical +compilers support it, because it is derived from FORTRAN-66; it is +an anachronism that should not be perpetuated. +.LP +Some implementations produce compilation listings. This aspect of +FORTRAN has been left unspecified because there was +controversy concerning the various methods proposed for implementing +it: a \fB-V\fP option overlapped with historical vendor +practice and a naming convention of creating files with \fB.l\fP suffixes +collided with historical \fIlex\fP file naming practice. +.LP +There is no \fB-I\fP option in this version of this volume of IEEE\ Std\ 1003.1-2001 +to specify a directory for file +inclusion. An INCLUDE directive has been a part of the Fortran-90 +discussions, but an interface supporting that standard is not in +the current scope. +.LP +It is noted that many FORTRAN compilers produce an object module even +when compilation errors occur; during a subsequent +compilation, the compiler may patch the object module rather than +recompiling all the code. Consequently, it is left to the +implementor whether or not an object file is created. +.LP +A reference to MIL-STD-1753 was removed from an early proposal in +response to a request from the POSIX FORTRAN-binding standard +developers. It was not the intention of the standard developers to +require certification of the FORTRAN compiler, and +IEEE\ Std\ 1003.9-1992 does not specify the military standard or any +special preprocessing requirements. Furthermore, use +of that document would have been inappropriate for an international +standard. +.LP +The specification of optimization has been subject to changes through +early proposals. At one time, \fB-O\fP and \fB-N\fP were +Booleans: optimize and do not optimize (with an unspecified default). +Some historical practice led this to be changed to: +.TP 7 +\fB-O\fP\ 0 +No optimization. +.TP 7 +\fB-O\fP\ 1 +Some level of optimization. +.TP 7 +\fB-O\ \fP \fIn\fP +Other, unspecified levels of optimization. +.sp +.LP +It is not always clear whether "good code generation" is the same +thing as optimization. Simple optimizations of local actions +do not usually affect the semantics of a program. The \fB-O\fP 0 option +has been included to accommodate the very particular +nature of scientific calculations in a highly optimized environment; +compilers make errors. Some degree of optimization is +expected, even if it is not documented here, and the ability to shut +it off completely could be important when porting an +application. An implementation may treat \fB-O\fP 0 as "do less than +normal" if it wishes, but this is only meaningful if any of +the operations it performs can affect the semantics of a program. +It is highly dependent on the implementation whether doing less +than normal is logical. It is not the intent of the \fB-O\fP 0 option +to ask for inefficient code generation, but rather to assure +that any semantically visible optimization is suppressed. +.LP +The specification of standard library access is consistent with the +C compiler specification. Implementations are not required +to have \fB/usr/lib/libf.a\fP, as many historical implementations +do, but if not they are required to recognize \fBf\fP as a +token. +.LP +External symbol size limits are in normative text; conforming applications +need to know these limits. However, the minimum +maximum symbol length should be taken as a constraint on a conforming +application, not on an implementation, and consequently the +action taken for a symbol exceeding the limit is unspecified. The +minimum size for the external symbol table was added for similar +reasons. +.LP +The CONSEQUENCES OF ERRORS section clearly specifies the behavior +of the compiler when compilation or link-edit errors occur. +The behavior of several historical implementations was examined, and +the choice was made to be silent on the status of the +executable, or \fBa.out\fP, file in the face of compiler or linker +errors. If a linker writes the executable file, then links it +on disk with \fIlseek\fP()s and \fIwrite\fP()s, the +partially linked executable file can be left on disk and its execute +bits turned off if the link edit fails. However, if the linker +links the image in memory before writing the file to disk, it need +not touch the executable file (if it already exists) because the +link edit fails. Since both approaches are historical practice, a +conforming application shall rely on the exit status of +\fIfort77\fP, rather than on the existence or mode of the executable +file. +.LP +The \fB-g\fP and \fB-s\fP options are not specified as mutually-exclusive. +Historically these two options have been +mutually-exclusive, but because both are so loosely specified, it +seemed appropriate to leave their interaction unspecified. +.LP +The requirement that conforming applications specify compiler options +separately is to reserve the multi-character option name +space for vendor-specific compiler options, which are known to exist +in many historical implementations. Implementations are not +required to recognize, for example, \fB-gc\fP as if it were \fB-g\fP +\fB-c\fP; nor are they forbidden from doing so. The +SYNOPSIS shows all of the options separately to highlight this requirement +on applications. +.LP +Echoing filenames to standard error is considered a diagnostic message +because it would otherwise be difficult to associate an +error message with the erring file. They are described with "may" +to allow implementations to use other methods of identifying +files and to parallel the description in \fIc99\fP. +.SH FUTURE DIRECTIONS +.LP +A compilation system based on the ISO/IEC\ 1539:1990 standard (Fortran-90) +may be considered for a future version; it may +have a different utility name from \fIfort77\fP. +.SH SEE ALSO +.LP +\fIar\fP , \fIasa\fP , \fIc99\fP , \fIumask\fP() , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIexec\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |