4.3BSD/usr/contrib/icon/docs/icont.1

Compare this file to the similar file:
Show the results in this format: 

.ds M \fB
.if t .if !\nd .ds M \fM
.TH ICONT 1 "The University of Arizona \- 8/20/84"
.SH NAME
icont \- translate Icon programs for interpretive execution
.SH SYNOPSIS
\f3icont\fR
[ option ... ] file ... [
\f3\-x\fR
arg ... ]
.SH DESCRIPTION
.I Icont
is a translator for Version 5.9 of the Icon programming language,
which produces a file suitable for interpretation by the Icon
interpreter.
Translation consists of two phases:
.I translation
and
.IR linking .
During translation,
each Icon source file is translated into an intermediate language;
during linking,
the intermediate language files are combined and a single
output file is produced.
The output file from the linker is referred to as an \fIinterpretable\fR file.
Unless the
\f3\-o\fR
option is specified, the name of the resulting interpretable file is
formed by deleting the suffix of the first input file named on the
command line.
If the
\f3\-x\fR
argument is used,
the file is automatically executed by the interpreter
and any arguments following the
\f3\-x\fR
are passed as execution arguments to the Icon program itself.
.PP
Files whose names end in \*M.icn\fR are assumed to be Icon source programs;
they are translated, and the intermediate code is left in two files of
the same name with \*M.u1\fR and \*M.u2\fR substituted for \*M.icn\fR.
The intermediate code files normally are deleted when compilation has finished.
Files whose names end in \*M.u1\fR or \*M.u2\fR are assumed to be intermediate
code files from a previous translation
(only one should be named \(em the other is assumed);
these files are included in the linking phase after any \*M.icn\fR
files have been translated.
A \*M.u1\fR or \*M.u2\fR file that is explicitly named is not deleted.
Icon source programs may be read from standard input.
The argument
\f3\-\fR
signifies the use of standard input as a source file.
In this case, the intermediate code is placed in \*Mstdin.u1\fR and \*Mstdin.u2\fR
and the interpretable file is \*Mstdin\fR.
.PP
The following options are recognized by
.IR icont .
.TP 4
\f3\-c\fR
Suppress the linking phase.
The intermediate code files are not deleted.
.TP
\f3\-m\fR
Preprocess each \*M.icn\fR source file
with the \fIm4\^(1)\fR
macro processor before translation.
.TP
\f3\-o \fIoutput\fR
Name the interpretable file
.IR output .
.TP
\f3\-s\fR
Suppress any informative messages from the translator and
linker.
Normally, both informative messages and error messages are sent
to standard error output.
.TP
\f3\-t\fR
Arrange for \*M&trace\fR to have an initial value of \-1
when the program is executed.
Normally, \*M&trace\fR has an initial value of 0.
.TP
\f3\-u\fR
Issue warning messages for undeclared identifiers in the program.
The warnings are issued during the linking phase.
.PP
Icon has a number of memory regions related to the translation of programs.
These regions are large enough for most programs, but their size can be
changed, if necessary, by the \f3\-S\fR option, which has the
form \f3\-S[cfgilrstCL]\fI n\fR, where the letter following the
\f3S\fR specifies the region and \fIn\fR is the number of storage units to
allocate for the region. The regions are:
.IP \f3c\fR
literal table
.IP \f3f\fR
field table
.IP \f3g\fR
global symbol table
.IP \f3i\fR
identifier table
.IP \f3l\fR
local symbol table
.IP \f3r\fR
field table for record lists
.IP \f3s\fR
string space
.IP \f3t\fR
tree space
.IP \f3C\fR
code buffer
.IP \f3L\fR
labels
.PP
The environment variable \fIIPATH\fR controls the location of files
specified in link directives. \fIIPATH\fR should have a value of the
form \fIp1:p2: .\^.\^. : pn\fR where the \fIpi\fR name directories.
Each directory is searched in turn to locate files named in link
directives. The default value for \fIIPATH\fR is \*M.\fR , that is, the current
directory.
.PP
The interpretable
file produced by the Icon linker is
.I
directly executable.
\fRFor example, the command
.nf
.sp 1
.in +.5i
\*M
icont hello.icn
.ft R
.in -.5i
.sp 1
.fi
produces a file named \*Mhello\fR
that can be run by the command
.nf
.sp 1
.in +.5i
\*M
hello
.ft R
.in -.5i
.sp 1
.fi
The method used to make interpretable files appear to be directly
executable is system dependent.
See the Icon installation guide for complete details.
For most intents and purposes, interpretable
files are executable programs in the same sense that files produced by
.IR ld \^(1)
are executable programs.
.PP
Arguments can be passed to the Icon program by following the program
name with the arguments.  Any such arguments are passed to the main
procedure as a list of strings.
.PP
When an Icon program is executed, a number of environment variables
are examined to determine certain execution parameters.
The values assigned to these variables should be numbers.
The variables that affect execution
and the interpretations of their values are as follows:
.TP 4
.I TRACE
Initialize the value of \*M&trace\fR.
If this variable has a value, it overrides the translation-time
\f3\-t\fR
option.
.TP
.I NBUFS
The number of i/o buffers to use for files.
When a file is opened, it is assigned an i/o buffer if one is available
and the file is not a tty.
If no buffer is available, the file is not buffered.
\*M&input\fR, \*M&output\fR, and \*M&errout\fR are buffered if buffers
are available.
On VAX systems, ten buffers are allocated initially;
on PDP-11 systems, five buffers are allocated initially.
.TP
.I NOERRBUF
If set, \*M&errout\fR is not buffered.
.TP
.I STRSIZE
The initial size of the string space, in bytes.
The string space grows if necessary, but it never shrinks.
On VAX systems, the string space is initially 51,200 bytes;
on PDP-11 systems, 10,240 bytes initially.
.TP
.I HEAPSIZE
The initial size of the heap, in bytes.
The heap grows if necessary, but it never shrinks.
On VAX systems, the heap is initially 51,200 bytes;
on PDP-11 systems, 10,240 bytes initially.
.TP
.I NSTACKS
The number of stacks initially available for co-expressions.
On VAX systems, four stacks are initially allocated; on PDP-11
systems, two stacks are initially allocated.
More are automatically allocated if needed.
.TP
.I STKSIZE
The size of each co-expression stack, in words.
On VAX systems, stacks are normally 2000 words;
on PDP-11 systems, stacks are normally 1000 words.
.SH FILES
.ta \w'\*Mv5g/bin/itran\fR     'u
\*Mv5g/bin/itran\fR	icon translator
.br
\*Mv5g/bin/ilink\fR	icon linker
.br
\*Mv5g/bin/iconx\fR	icon run-time system
.br
.SH SEE ALSO
.I
The Icon Programming Language\fR,
Ralph E. Griswold and Madge T. Griswold,
Prentice-Hall Inc.,
Englewood Cliffs, New Jersey,
1983.
.LP
\fIVersion 5.9 of Icon\fR, Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
Department of Computer Science, The University of Arizona,
August 1984.
.LP
\fIInstallation and Maintenance Guide for Version 5.9 of Icon\fR,
Ralph E. Griswold and William H. Mitchell,
Department of Computer Science, The University of Arizona,
August 1984.
.LP
m4\^(1), icon-pi(1)
.SH BUGS
.LP
Downward compatibility of interpretable files will not be maintained
in subsequent releases of Icon.  No checks are performed to determine
if the interpretable file and the interpreter are compatible.  Peculiar
program behavior is the only indication of such incompatibility.
.LP
Interpretable files do not stand alone; the Icon interpreter must be
present on the system.  This implies that an interpretable
file produced on one system will not work on another system unless
the Icon interpreter is in the same place on both systems and that
the interpreter is of the same version of Icon as the translator
that produced the interpretable file.
.LP
Because of the way that co-expressions are implemented,
there is a possibility that programs
in which they are used may malfunction mysteriously.
.LP
Integer overflow on multiplication is not detected.
.LP
If the
\f3\-m\fR
option is used,
line numbers reported in error messages or tracing messages
are from the file after, not before, preprocessing.