diff options
Diffstat (limited to 'upstream/archlinux/man1p/fort77.1p')
| -rw-r--r-- | upstream/archlinux/man1p/fort77.1p | 584 |
1 files changed, 584 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/fort77.1p b/upstream/archlinux/man1p/fort77.1p new file mode 100644 index 00000000..3851aaeb --- /dev/null +++ b/upstream/archlinux/man1p/fort77.1p @@ -0,0 +1,584 @@ +'\" et +.TH FORT77 "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fort77 +\(em FORTRAN compiler (\fBFORTRAN\fP) +.SH SYNOPSIS +.LP +.nf +fort77 \fB[\fR-c\fB] [\fR-g\fB] [\fR-L \fIdirectory\fB]\fR...\fB [\fR-O \fIoptlevel\fB] [\fR-o \fIoutfile\fB] [\fR-s\fB] + [\fR-w\fB] \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR fort77 +utility is the interface to the FORTRAN compilation system; it shall +accept the full FORTRAN-77 language defined by the ANSI\ X3.9\(hy1978 standard. The system +conceptually consists of a compiler and link editor. The files +referenced by +.IR operand s +are compiled and linked to produce an executable file. It is +unspecified whether the linking occurs entirely within the operation of +.IR fort77 ; +some implementations may produce objects that are not fully resolved +until the file is executed. +.P +If the +.BR \-c +option is present, for all pathname operands of the form +.IR file \c +.BR .f , +the files: +.sp +.RS 4 +.nf + +$(basename \fIpathname\fR.f).o +.fi +.P +.RE +.P +shall be created or overwritten as the result of successful +compilation. If the +.BR \-c +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .f +operands. +.P +If there are no options that prevent link editing (such as +.BR \-c ) +and all operands compile and link without error, the resulting +executable file shall be written into the file named by the +.BR \-o +option (if present) or to the file +.BR a.out . +The executable file shall be created as specified in the System Interfaces volume of POSIX.1\(hy2017, except +that the file permissions shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and that the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR fort77 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +The +.BR \-l +.IR library +operands have the format of options, but their position within a list +of operands affects the order in which libraries are searched. +.IP " *" 4 +The order of specifying the multiple +.BR \-L +options is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \-cg ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\-c\fR" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\-g\fR" 10 +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. +.IP "\fB\-s\fR" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family of functions defined in the System Interfaces volume of POSIX.1\(hy2017 has been removed (stripped). +If both +.BR \-g +and +.BR \-s +options are present, the action taken is unspecified. +.IP "\fB\-o\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \-o +option is present with +.BR \-c , +the result is unspecified. +.IP "\fB\-L\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in +.BR \-l +operands to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \-L +options shall be searched in the specified order. At least ten +instances of this option shall be supported in a single +.IR fort77 +command invocation. If a directory specified by a +.BR \-L +option contains a file named +.BR libf.a , +the results are unspecified. +.IP "\fB\-O\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \-O +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \-O +0 option is the same as that generated when +.BR \-O +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\-w\fR" 10 +Suppress warnings. +.P +Multiple instances of +.BR \-L +options can be specified. +.SH OPERANDS +An +.IR operand +is either in the form of a pathname or the form +.BR \-l +.IR library . +At least one operand of the pathname form shall be specified. The +following operands shall be supported: +.IP "\fIfile.\fBf\fR" 10 +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 +.BR \-c +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by +.IR ar , +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR fort77 +.BR \-c +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.IP "\fB\-l\ \fIlibrary\fR" 10 +(The letter ell.) Search the library named: +.RS 10 +.sp +.RS 4 +.nf + +lib\fIlibrary\fR.a +.fi +.P +.RE +.P +A library is searched when its name is encountered, so the placement of +a +.BR \-l +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 +.BR .a +as denoting libraries. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The input file shall be one of the following: a text file containing +FORTRAN source code; an object file in the format produced by +.IR fort77 +.BR \-c ; +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input files are implementation-defined. +.P +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" +The following environment variables shall affect the execution of +.IR fort77 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that should override the default directory for +temporary files, if any. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +If more than one +.IR file +operand ending in +.BR .f +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf + +"%s:\en", <\fIfile\fR> +.fi +.P +.RE +.P +may be written to allow identification of the diagnostic message with +the appropriate input file. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files, listing files, and executable files shall be produced in +unspecified formats. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR fort77 +utility shall recognize the following +.BR \-l +operand for the standard library: +.IP "\fB\-l\ f\fR" 10 +This library contains all functions referenced in the ANSI\ X3.9\(hy1978 standard. This +operand shall not be required to be present to cause a search of this +library. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \-c , +the +.IR fort77 +utility shall cause the equivalent of a +.BR "\-l\ f" +operand to be passed to the link editor as the last +.BR \-l +operand, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the library +.BR libf.a +exists as a regular file. The implementation may accept as +.BR \-l +operands names of objects that do not exist as regular files. +.SS "External Symbols" +.P +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. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 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" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR fort77 +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 +.IR fort77 +shall exit with a non-zero status. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following usage example compiles +.BR xyz.f +and creates the executable file +.BR foo : +.sp +.RS 4 +.nf + +fort77 -o foo xyz.f +.fi +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the object file +.BR xyz.o : +.sp +.RS 4 +.nf + +fort77 -c xyz.f +.fi +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf + +fort77 xyz.f +.fi +.P +.RE +.P +The following example compiles +.BR xyz.f , +links it with +.BR b.o , +and creates the executable +.BR a.out : +.sp +.RS 4 +.nf + +fort77 xyz.f b.o +.fi +.P +.RE +.SH RATIONALE +The name of this utility was chosen as +.IR fort77 +to parallel the renaming of the C compiler. The name +.IR f77 +was not chosen to avoid problems with historical implementations. The +ANSI\ X3.9\(hy1978 standard was selected as a normative reference because the ISO/IEC version +of FORTRAN-77 has been superseded by the ISO/IEC\ 1539:\|1991 standard. +.P +The file inclusion and symbol definition +.BR #define +mechanisms used by the +.IR c99 +utility were not included in this volume of POSIX.1\(hy2017\(emeven though they are commonly +implemented\(emsince there is no requirement that the FORTRAN compiler +use the C preprocessor. +.P +The +.BR \-onetrip +option was not included in this volume of POSIX.1\(hy2017, even though many historical compilers +support it, because it is derived from FORTRAN-66; it is an anachronism +that should not be perpetuated. +.P +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 +.BR \-V +option overlapped with historical vendor practice and a naming +convention of creating files with +.BR .l +suffixes collided with historical +.IR lex +file naming practice. +.P +There is no +.BR \-I +option in this version of this volume of POSIX.1\(hy2017 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. +.P +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. +.P +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\(hy1992 does not specify the military standard or any +special preprocessing requirements. Furthermore, use of that document +would have been inappropriate for an international standard. +.P +The specification of optimization has been subject to changes through +early proposals. At one time, +.BR \-O +and +.BR \-N +were Booleans: optimize and do not optimize (with an unspecified +default). Some historical practice led this to be changed to: +.IP "\fB\-O\fR\ 0" 10 +No optimization. +.IP "\fB\-O\fR\ 1" 10 +Some level of optimization. +.IP "\fB\-O\ \fIn\fR" 10 +Other, unspecified levels of optimization. +.P +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 +.BR \-O +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 +.BR \-O +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 +.BR \-O +0 option to ask for inefficient code generation, but rather to assure +that any semantically visible optimization is suppressed. +.P +The specification of standard library access is consistent with the C +compiler specification. Implementations are not required to have +.BR /usr/lib/libf.a , +as many historical implementations do, but if not they are required to +recognize +.BR f +as a token. +.P +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. +.P +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 +.BR a.out , +file in the face of compiler or linker errors. If a linker writes the +executable file, then links it on disk with +\fIlseek\fR()s +and +\fIwrite\fR()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 +.IR fort77 , +rather than on the existence or mode of the executable file. +.P +The +.BR \-g +and +.BR \-s +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. +.P +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, +.BR \-gc +as if it were +.BR \-g +.BR \-c ; +nor are they forbidden from doing so. The SYNOPSIS shows all of the +options separately to highlight this requirement on applications. +.P +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 +.IR c99 . +.SH "FUTURE DIRECTIONS" +Future versions of this standard may withdraw this utility. There are +implementations of compilers that conform to much more recent versions +of the FORTRAN programming language. Since there is no active FORTRAN +binding to POSIX.1\(hy2008, this standard does not need to specify any compiler. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIasa\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIexec\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |