puman5.n

早期freebsd实现

.\" Copyright (c) 1980, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)puman5.n	8.1 (Berkeley) 6/8/93
.\"
.if !\n(xx \{\
.so tmac.p \}
.ND
.nr H1 4
.NH
Details on the components of the system
.NH 2
Options
.PP
The programs
.PI ,
.PC ,
and
.XP
take a number of options.\*(dg
.FS
\*(dgAs
.IX
uses
.PI
to translate Pascal programs,
it takes the options of
.PI
also.
We refer to them here, however, as
.PI
options.
.FE
There is a standard
.UX
convention for passing options to programs on the command line,
and this convention is followed by the
.UP
system programs.
As we saw in the examples above,
option related arguments consisted of the character `\-' followed
by a single character option name.
.PP
Except for the
.B b
option
which takes a single digit value,
each option may be set on (enabled)
or off (disabled.)
When an on/off valued option appears on the command line of
.PI
or
.PX
it inverts the default setting of that option.
Thus
.LS
% \*bpi -l foo.p\fR
.LE
enables the listing option
.B l ,
since it defaults off, while
.LS
% \*bpi -t foo.p\fR
.LE
disables the run time tests option
.B t ,
since it defaults on.
.PP
In additon to inverting the default settings of
.PI
options on the command line, it is also possible to control the
.PI
options 
within the body of the program by using comments of a special
form illustrated by
.LS
{$l-}
.LE
.PP
Here we see that the opening comment delimiter (which could also be a `(*')
is immediately followed by the character `$'.
After this `$', which signals the start of the option list,
we can place a sequence of letters and option controls, separated by `,'
characters\*(dd.
.FS
\*(ddThis format was chosen because it is used by Pascal 6000-3.4.
In general the options common to both implementations are controlled
in the same way so that comment control in options is mostly
portable.
It is recommended, however, that only one control be put per comment for
maximum portability, as the Pascal 6000-3.4
implementation will ignore controls
after the first one which it does not recognize.
.FE
The most basic actions for options are to set them, thus
.LS
{$l+ Enable listing}
.LE
or to clear them
.LS
{$t-,p- No run-time tests, no post mortem analysis}
.LE
Notice that `+' always enables an option and `\-' always disables it,
no matter what the default is.
Thus `\-' has a different meaning in an option comment than it has on the
command line.
As shown in the examples,
normal comment text may follow the option list.
.NH 2
Options common to Pi, Pc, and Pix
.PP
The following options are common to both the compiler
and the interpreter.
With each option we give its default setting,
the setting it would have if it appeared on the command line,
and a sample command using the option.
Most options are on/off valued,
with the
.B b
option
taking a single digit value.
.SH
Buffering of the file output \- b
.PP
The
.B b
option controls the buffering of the file
.I output .
The default is line buffering, with flushing at
each reference to the file
.I input
and under certain other circumstances detailed in section 5
below.
Mentioning
.B b
on the command line, e.g.
.LS
% \*bpi -b assembler.p\fR
.LE
causes standard output to be block buffered,
where a block is some system\-defined number of characters.
The
.B b
option may also be controlled in comments.
It, unique among the
.UP
options,
takes a single digit value rather than an on or off setting.
A value of 0, e.g.
.LS
	{$b0}
.LE
causes the file
.I output
to be unbuffered.
Any value 2 or greater causes block buffering and is equivalent
to the flag on the command line.
The option control comment setting
.B b
must precede the
.B program
statement.
.SH
Include file listing \- i
.PP
The
.B i
option takes the name of an
.B include
file,
.B procedure
or
.B function
name and causes it
to be listed while translating\*(dg.
.FS
\*(dg\*bInclude\fR files are discussed in section 5.9.
.FE
Typical uses would be
.LS
% \*bpix -i scanner.i compiler.p\fR
.LE
to make a listing of the routines in the file scanner.i, and
.LS
% \*bpix -i scanner compiler.p\fR
.LE
to make a listing of only the routine
.I scanner .
This option is especially useful for conservation-minded programmers making
partial program listings.
.SH
Make a listing \- l
.PP
The
.B l
option enables a listing of the program.
The
.B l
option defaults off.
When specified on the command line, it causes
a header line identifying the version of the translator in use
and a line giving the modification time of the file being translated
to appear before the actual program listing.
The
.B l
option is pushed and popped by the
.B i
option at appropriate points in the program.
.SH
Standard Pascal only \- s
.PP
The
.B s
option causes many of the features of the
.SM UNIX
implementation which are not found in standard Pascal
to be diagnosed as `s' warning errors.
This option defaults off and is enabled when mentioned on the command line.
Some of the features which are diagnosed are:
non-standard
.B procedure s
and
.B function s,
extensions to the
.B procedure
.I write ,
and the padding of constant strings with blanks.
In addition, all letters are mapped to lower case except in
strings and characters so that the case of keywords and identifiers
is effectively ignored.
The
.B s
option is most useful when a program is to be transported, thus
.LS
% \*bpi -s isitstd.p\fR
.LE
will produce warnings unless the program meets the standard.
.SH
Runtime tests \- t and C
.PP
These
options control the generation of tests that subrange variable
values are within bounds at run time.
.PI
defaults to generating tests and uses the option
.B t
to disable them.
.PC
defaults to not generating tests,
and uses the option
.B C
to enable them.
Disabling runtime tests also causes
.B assert
statements to be treated as comments.\*(dd
.FS
\*(ddSee section A.1 for a description of
.B assert
statements.
.FE
.SH
Suppress warning diagnostics \- w
.PP
The
.B w
option, which defaults on,
allows the translator to print a number of warnings about inconsistencies
it finds in the input program.
Turning this option off with a comment of the form
.LS
{$w-}
.LE
or on the command line
.LS
% \*bpi -w tryme.p\fR
.LE
suppresses these usually useful diagnostics.
.SH
Generate counters for a pxp execution profile \- z
.PP
The
.B z
option, which defaults off,
enables the production of execution profiles.
By specifying
.B z
on the command line, i.e.
.LS
% \*bpi -z foo.p\fR
.LE
or by enabling it in a comment before the
.B program
statement causes
.PI
and
.PC
to insert operations in the interpreter code to
count the number of times each statement was executed.
An example of using
.XP
was given in section 2.6;
its options are described in section 5.6.
Note that the
.B z
option cannot be used on separately compiled programs.
.NH 2
Options available in Pi
.SH
Post-mortem dump \- p
.PP
The
.B p
option defaults on,
and causes the runtime system to initiate a post-mortem
backtrace when an error occurs.
It also cause
.X
to count statements in the executing program,
enforcing a statement limit to prevent infinite loops.
Specifying
.B p
on the command line disables these checks and the ability
to give this post-mortem analysis.
It does make smaller and faster programs, however.
It is also possible to control the
.B p
option in comments.
To prevent the post-mortem backtrace on error,
.B p
must be off at the end of the
.B program
statement.
Thus, the Pascal cross-reference program was translated with
.LS
% \*bpi -pbt pxref.p\fR
.LE
.NH 2
Options available in Px
.PP
The first argument to
.X
is the name of the file containing the program to be interpreted.
If no arguments are given, then the file
.I obj
is executed.
If more arguments are given, they are available to the Pascal
program by using the built-ins
.I argc
and
.I argv
as described in section 4.6.
.ne 7
.PP
.I Px
may also be invoked automatically.
In this case, whenever a Pascal object file name is given as a command,
the command will be executed with
.X
prepended to it; that is
.LS
% \*bobj primes\fR
.LE
will be converted to read
.LS
% \*bpx obj primes\fR
.LE
.NH 2
Options available in Pc
.SH
Generate assembly language \- S
.PP
The program is compiled and the assembly language
output is left in file appended .s.
Thus
.LS
% \*bpc -S foo.p\fR
.LE
creates a file
.I foo.s .
No executable file is created.
.SH
Symbolic Debugger Information \- g
.PP
The
.B g
option causes the compiler to generate information
needed by
.I sdb (1)
the symbolic debugger.
For a complete description of
.I sdb
see Volume 2c of the
.UX
Reference Manual.
.SH
Redirect the output file \- o
.PP
The
.I name
argument after the
.B -o
is used as the name of the output file instead of
.I a.out .
Its typical use is to name the compiled program using
the root of the file name.
Thus:
.LS
% \*bpc -o myprog myprog.p\fR
.LE
causes the compiled program to be called
.I myprog .
.SH
Generate counters for a \*iprof\fP execution profile \- p
.PP
The compiler produces code which counts the number of times each
routine is called.
The profiling is based on a periodic sample taken by the
system rather than by inline counters used by
.XP .
This results in less degradation in execution,
at somewhat of a loss in accuracy.
See
.I prof (1)
for a more complete description.
.SH
Run the object code optimizer \- O
.PP
The output of the compiler is run through
the object code optimizer.
This provides an increase in compile time in
exchange for a decrease in compiled code size
and execution time.
.NH 2
Options available in Pxp
.PP
.I Pxp
takes, on its command line, a list of options followed by the program file
name, which must end in `.p' as it must for
.PI ,
.PC ,
and
.IX .
.I Pxp