P2C(1) USER COMMANDS P2C(1)
NAME
p2c - Pascal to C translator, version 1.20
SYNOPSIS
p2c [ options ] [ file [ module ] ]
DESCRIPTION
P2c is a tool for translating Pascal programs into C. The
input consists of a set of source files in any of the fol-
lowing Pascal dialects: HP Pascal, Turbo/UCSD Pascal, DEC
VAX Pascal, Oregon Software Pascal/2, Macintosh Programmer's
Workshop Pascal, Sun/Berkeley Pascal. Modula-2 syntax is
also supported. Output is a set of .c and .h files that
comprise an equivalent program in any of several dialects of
C. Output code may be kept machine- and dialect-
independent, or it may be targeted to a specific machine and
compiler. Most reasonable Pascal programs are converted
into fully functional C which will compile and run with no
further modifications, although p2c sometimes chooses to
generate readable code at the expense of absolute general-
ity. P2c endeavors to insert notes and warning messages into
the output code to point out areas which may require human
intervention. Output code is arranged to be readable and
efficient, and to make use of C idioms wherever possible.
The main goal of the translation is to produce C files which
are pleasant and "natural" enough to be acceptable as the
new source files for a program. In a pinch, p2c will also
serve as an ad hoc Pascal compiler.
Code generated by p2c normally does not assume characters
are signed or unsigned. Also, it assumes int is the same as
either short or long but does not depend on which. However,
if int is not the same as long it is best to use a modern C
compiler which supports prototypes. Generated code does not
require an ANSI-compatible compiler (unless ANSI-style code
is requested), but it does use various ANSI-standard library
routines.
All generated code includes the file <p2c/p2c.h> which in
turn includes <stdio.h> and various other common resources.
Also, many translated programs will need to be linked with
the run-time library, typically -lp2c.
Given a file name, p2c reads from the specified file and
outputs to a file with a .c suffix added or substituted.
For example,
p2c myfile.pas
reads from myfile.pas to produce the file myfile.c. The
input file may contain a Pascal main program or a single
Pascal module (or "unit" in Turbo and UCSD Pascal
Sun Release 4.1 Last change: local 1
P2C(1) USER COMMANDS P2C(1)
nomenclature), or it may just contain a number of procedures
and declarations. P2c is designed to work for correct input
programs. That is, it will accept partial programs but may
occasionally core dump if the input refers to undefined sym-
bols.
If the input is a module, the translator will also produce a
file module.h containing a translation of the module's
interface section. The implementation section may be omit-
ted in which case only the .h file will be interesting. If
the program or module has include files, these may cause
additional .c files to be generated depending on the value
of the ExpandIncludes option (see below).
If no file name is given, p2c reads Pascal from the standard
input and writes the resulting C to standard output (though
a .h file may still be produced). If a file name and module
name are given, the file may include several modules (or
units). The specified module is translated; any others are
skipped. The output files will be named module.c and
module.h. P2c never translates more than one module per
run.
Before starting, p2c reads the file /usr2/mbk/p2c-
1.20/home/p2crc for a number of configuration parameters.
(The actual path used on your system may vary. The -i
option is a handy way to examine this file.) If the P2CRC
environment variable is set, it gives the name of a file to
read instead of the system file; this file can start with
Include %H/p2crc to include the system file. Next, p2c
attempts to read the file p2crc in your directory for
further configuration. If this file does not exist, p2c
looks for .p2crc instead.
OPTIONS
-o cfile
Use cfile in place of file.c or module.c as the primary
output file. A single dash (`-o -') says to write the
C code to the standard output.
-h hfile
Use hfile in place of module.h as the output file for
interface text. This only has effect if the input is
an HP Pascal module or a Turbo Pascal unit.
-s sfile
Read interface text from sfile before beginning the
translation. This file typically contains one or more
modules, often with interface sections omitted for
speed, which the program or module being translated
will use. (Typically the ImportFrom and ImportDir
parameters in p2crc are set up to allow p2c to locate
Sun Release 4.1 Last change: local 2
P2C(1) USER COMMANDS P2C(1)
interface text without needing any -s options.) If
there are several -s options in the command, the sfiles
are read from left to right.
-pn Display progress of translation in the form of a line
number/file name display. This is refreshed every n
lines, 25 by default.
-c rcfile
Read local configuration commands from rcfile instead
of p2crc or .p2crc. A dash (`-c -') in place of rcfile
causes no local configuration file to be used.
-v ("Vanilla.") Do not read from the system configuration
file /usr2/mbk/p2c-1.20/home/p2crc. Since some of the
parameters in this file are required, your local confi-
guration file must include those parameters instead.
This also suppresses the file named by the P2CRC
environment variable.
-H homedir
Use homedir instead of /usr2/mbk/p2c-1.20/home as the
p2c home directory. The system p2crc file will be
searched for in this directory.
-Ipattern
Add pattern to the ImportDir search list of places to
find modules which are imported. The pattern should
include a %s to represent the module name, and should
evaluate to a potential file name for that module's
source code. For example, ../%s.pas looks for
modulename.pas in the parent of the current directory.
-i This special option (which must be the only argument on
the command line if used) simply copies the system con-
figuration file /usr2/mbk/p2c-1.20/home/p2crc to the
standard output in its entirety. (It may be used with
-H, but -i is most useful precisely when you don't know
the location of the home directory.)
-q Quiet mode. Suppresses output of status messages dur-
ing translation.
-En Abort translation after n errors. If n is omitted it
defaults to zero, which means unlimited errors are
allowed. Use -E1 to make p2c halt after the first
error.
-e Echo the Pascal source into the output file, surrounded
by #ifdefs. This is the same as the CopySource parame-
ter in the p2crc file.
Sun Release 4.1 Last change: local 3
P2C(1) USER COMMANDS P2C(1)
-a Produce modern ANSI C. This is a convenient override
for the AnsiC parameter in the p2crc file.
-L language
Select input language name, such as VAX or TURBO. This
is a convenient override for the Language parameter.
-V Verbose mode. This causes p2c to generate an addi-
tional ".log" file with further details of the transla-
tion, such as a list of warnings and notes including
those which are suppressed in the regular output.
-M0 Disable memory conservation. This prevents p2c from
freeing various data structures after translating each
function, in case this new conservation feature causes
unforseen problems.
-R Regression testing mode. Formats notes and warning
messages in a way that makes it easier to run diff(1)
on the output of p2c.
P2c also understands a few debugging options which may occa-
sionally be useful when tracking down translation problems.
The -dn option sets the "debug level" to n, a small integer
which is normally zero. Debugging output is written into
the regular output file along with the C code; the higher
your n, the more "wallpaper" you get. Also, -t prints
debugging information at every Pascal token, -Bn enables
line-breaker debugging, and -Cn enables comment placement
debugging.
CHOICE OF SOURCE LANGUAGE
The Language configuration parameter or -L command-line
option tells p2c which Pascal dialect to expect in the input
file. Any language features which do not overlap between
dialects are supported all of the time. The Language param-
eter is consulted when a syntax or usage is detected that
has different meanings in two different dialects, and also
to determine default values for various other translation
parameters as described below.
The following language words are supported by p2c. Names are
case-insensitive.
HP HP Pascal. This is the default language. All
features of HP Standard Pascal, the Pascal Worksta-
tion version, are supported except as noted in BUGS
below. Some features of MODCAL, HP's extended Pas-
cal, are also supported. This is a superset of ISO
standard Pascal, including conformant arrays and
procedural parameters.
Sun Release 4.1 Last change: local 4
P2C(1) USER COMMANDS P2C(1)
HP-UX HP Pascal, HP-UX version. Almost identical to the
"HP" dialect.
Turbo Turbo Pascal 5.0 for the IBM PC. Few conflicts with
HP Pascal, so the Language parameter is not often
needed for Turbo. (Most important is that the Turbo
and HP dialects use 16 and 32 bit integers, respec-
tively.)
UCSD UCSD Pascal. Similar to Turbo in many ways.
MPW Macintosh Programmer's Workshop Pascal 2.0. Should
also do a pretty good job for Lightspeed Pascal.
Object Pascal features are not supported, nor is the
fact that char variables are sometimes stored in 16
bits.
VAX VAX/VMS Pascal version 3.5. Most but not all
language features supported. This has not yet been
tested on large programs.
Oregon Oregon Software Pascal/2. All features implemented.
Berk Berkeley Pascal with Sun extensions.
Modula Modula-2. Based on Wirth's Programming in Modula-2,
3rd edition. Proper setting of the Language parame-
ter is not optional. Translation will be incomplete
in most cases, but should be good enough to work
with. Structure of local sub-modules is essentially
ignored; like-named identifiers may be confused.
Type WORD is translated as an integer, but type
ADDRESS is translated as char * or void *; this may
cause inconsistencies in the output code.
Modula-2 modules have two parts in separate files.
Suppose these are called foo.def (definition part)
and foo.mod (implementation part) for module foo.
Then a pattern like %s.def must be included in the
ImportDir list, and LibraryFile must be changed to
refer to system.m2 instead of system.imp. To
translate the definition part, give the command
p2c foo.def
to translate the definition part into files foo.h
and foo.c; the latter will usually be empty. The
command
p2c -s foo.def foo.mod
will translate the implementation part into file
Sun Release 4.1 Last change: local 5
P2C(1) USER COMMANDS P2C(1)
foo.c.
Even if all language features are supported for a dialect,
some predefined functions may be omitted. In these cases,
the function call will be translated literally into C with a
warning. Some hand modification may be required.
CONFIGURATION PARAMETERS
P2c is highly configurable. The defaults are suitable for
most applications, but customizing these parameters will
help you get the best possible translation. Since the out-
put of p2c is intended to be used as human-maintainable
source code, there are many parameters for describing the
coding style and conventions you prefer. Others give hints
about your program that help p2c to generate more correct,
efficient, or readable code.
The p2crc files contain a list of parameters, one per line.
The system configuration file, which may be viewed using the
-i option to p2c, serves as an example of the proper format.
Parameter names are case-insensitive. If a parameter name
occurs exactly once in the system p2crc, this indicates that
it must have a unique value and the last value given to it
by the configuration files is used. Other parameters are
written several times in a row; these are lists to which
each configuration line adds an entry.
Many p2crc options take a numeric value of 0 or 1, roughly
corresponding to "no" or "yes." Sometimes a blank value or
the value "def" corresponds to an intermediate "maybe"
state. For example, the stylistic option ExtraParens
switches between copious or minimal parentheses in expres-
sions, with the default being a nice compromise intended to
be best for readers with an average knowledge of C operator
precedences.
Configuration options may also be embedded in the source
file in the form of Pascal comments:
{ShortOpt=0} {AvoidName=fred}
{FuncMacro slope(x,y)=atan2(y,x)*RadDeg}
disables automatic short-circuiting of and and or expres-
sions, adds "fred" to the list of names to avoid using in
generated C code, and defines a special translation for the
Pascal program's slope function using the standard C atan2
function and a constant RadDeg presumably defined in the
program. Whitespace is generally not allowed in embedded
parameters. The `=' sign is required for embedded parame-
ters, though it is optional in p2crc files. Comments within
embedded parameters are delimited by `##'. Numeric parame-
ters may replace `=' with `+' or `-' to increase or decrease
Sun Release 4.1 Last change: local 6
P2C(1) USER COMMANDS P2C(1)
the parameter; list-based parameters may use `-' to remove a
name from a list rather than adding it. Also, the parameter
name by itself in comment braces means to restore the
parameter's value that was current before the last change:
{VarFiles=0 ## Pass FILE *'s params by value even if
VAR}
some declarations
{VarFiles ## Back to original FILE * passing}
causes the parameter VarFiles to have the value 0 for those
few declarations, without affecting the parameter's value
elsewhere in the file.
If an embedded parameter appears in an include file or in
interface text for a module, the effect of the assignment
normally carries over to any programs that included that
file. If the parameter name is preceded by a `*', then the
assignment is automatically undone after the source file
that contains it ends:
{IncludeFrom strings=<p2c/strings.h>}
{*ExportSymbol=pascal_%s}
module strings;
will record the location of the strings module's include
file for the rest of the translation, but the assignment of
ExportSymbol pertains only to the module itself.
For the complete list of p2crc parameters, run p2c with the
-i option. Here are some additional comments on selected
parameters:
ImportAll Because Turbo Pascal only allows one unit per
source file, p2c normally stops reading past
the word implementation in a file being
scanned for interface text. But HP Pascal
allows several modules per file and so this
would not be safe to do. The ImportAll
option lets you override the default behavior
for your Pascal dialect.
AnsiC This parameter selects which dialect of C to
use. If 1, all conventions of ANSI C such as
prototypes, void * pointers, etc. are used.
If 0, only strict K&R (first edition) C is
used. The default is to use "traditional
UNIX C," which includes enum and void but not
void * or prototypes. Once again there are a
number of other parameters which may be used
to control the individual features if just
setting AnsiC is not enough.
Sun Release 4.1 Last change: local 7
P2C(1) USER COMMANDS P2C(1)
C++ At present p2c does not use much of C++ at
all. The default action is to generate code
that will compile in either language.
UseVExtern Many non-UNIX linkers prohibit variables from
being defined (not declared) by more than one
source file. One module must declare, e.g.,
"int foo;", and all others must declare
"extern int foo;". P2c accomplishes this by
declaring public variables "vextern" in
header files, and arranging for the macro
vextern to expand to extern or to nothing
when appropriate. If you set UseVExtern=0
p2c will instead declare variables in a
simpler way that works only on UNIX-style
linkers.
UseAnyptrMacros
Certain C reserved words have meanings which
may vary from one C implementation to
another. P2c uses special capitalized names
for these words; these names are defined as
macros in the file p2c.h which all translated
programs include. You can set UseAnyptrMac-
ros=0 to disable the use of these macros.
Note that the functions of many of these mac-
ros can also be had directly using other
parameters; for example, UseConsts allows you
to specify whether your target language
recognizes the word const in constant
declarations. The default is to use the
Const macro instead, so that your code will
be portable to either kind of implementation.
Signed expands to the reserved word signed if
that word is available, otherwise it is given
a null definition. Similarly, Const expands
to const if that feature is available. The
words Volatile and Register are also defined
in p2c.h, although p2c does not use them at
present. The word Char expands to char by
default, but might need to be redefined to
signed char or unsigned char in a particular
implementation. This is used for the Pascal
character type; lowercase char is used when
the desired meaning is "byte," not "charac-
ter."
The word Static always expands to static by
default. This is used in situations where a
function or variable is declared static to
make it local to the source file; lowercase
Sun Release 4.1 Last change: local 8
P2C(1) USER COMMANDS P2C(1)
static is used for static local variables.
Thus you can redefine Static to be null if
you want to force private names to be public
for purposes of debugging.
The word Void expands to void in all cases;
it is used when declaring a function with no
return value. The word Anyptr is a typedef
for void * or char * as necessary; it
represents a generic pointer.
UsePPMacros The p2c.h header also declares two macros for
function prototyping, PP(x) and PV(). These
macros are used as follows:
Void foo PP( (int x, int y, Char *z) );
Char *bar PV( );
If prototypes are available, these macros
will expand to
Void foo (int x, int y, Char *z);
Char *bar (void);
but if only old-style declarations are sup-
ported, you instead get
Void foo ();
Char *bar ();
By default, p2c uses these macros for all
function declarations, but function defini-
tions are written in old-style C. The UsePP-
Macros parameter can be set to 0 to disable
all use of PP and PV, or it can be set to 1
to use the macros even when defining a func-
tion. (This is accomplished by preceding
each old-style definition with a PP-style
declaration.) If you know your code will
always be compiled on systems that support
prototyping, it is prettier to set Proto-
types=1 or simply AnsiC=1 to get true func-
tion prototypes.
EatNotes Notes and warning messages containing any of
these strings as sub-strings are not omitted.
Each type of message includes an identifier
like [145]; you can add this identifier to
the EatNotes list to suppress that message.
Another useful form is to use a variable name
or other identifier to suppress warnings
about that variable. The strings are a
Sun Release 4.1 Last change: local 9
P2C(1) USER COMMANDS P2C(1)
space-separated list, and thus may not con-
tain embedded spaces. To suppress notes
around a section of code, use, e.g., {Eat-
Notes+[145]} and {EatNotes-[145]}. Most notes
are generated during parsing, but to suppress
those generated during output the string may
need to remain in the list far beyond the
point where it appears to be generated. Use
the string "1" or "0" to disable or enable
all notes, respectively.
ExpandIncludes The default action is to expand Pascal
include files in-line. This may not be
desirable if include files are being used to
simulate modules. With ExpandIncludes=0, p2c
attempts to convert include files containing
only whole procedures and global declarations
into analogous C include files. This may not
always work, though; if you get error mes-
sages, don't use this option. By combining
this option with StaticFunctions=0, then
doing some fairly minor editing on the
result, you can convert a pseudo-modular Pas-
cal program into a truly modular collection
of C source files.
ElimDeadCode Some transformations that p2c does on the
program may result in unreachable or "dead"
code. By default p2c removes such code, but
sometimes it removes more than it should. If
you have "if false" segments which you wish
to retain in C, you may have to set ElimDead-
Code=0.
SkipIndices Normally Pascal arrays not based at zero are
"shifted" down for C, preserving the total
size of the array. A Pascal array a[2..10]
is translated to a C array a[9] with refer-
ences like "a[i]" changed to "a[i-2]" every-
where. If SkipIndices is set to a value of 2
or higher, this array would instead be
translated to a[11] with the first two ele-
ments never used. This arrangement may gen-
erate incorrect code, though, for tricky
source programs.
FoldConstants Pascal non-structured constants generally
translate to #define's in C. Set this to 1
to have constants instantiated directly into
the code. This may be turned on or off
around specific constant declarations. Set
this to 0 to force p2c to make absolutely no
Sun Release 4.1 Last change: local 10
P2C(1) USER COMMANDS P2C(1)
assumptions about the constant's value in
generated code, so that you can change the
constant later in the C code without invali-
dating the translation. The default is to
allow p2c to take advantage of its knowledge
of a constant's value, such as by generating
code that assumes the constant is positive.
CharConsts This governs whether single-character string
literals in Pascal const declarations should
be interpreted as characters or strings. In
other words, const a='x'; will translate to
#define a 'x' if CharConsts=1 (the default),
or to #define a x if CharConsts=0. Note that
if p2c guesses wrong, the generated code will
not be wrong, just uglier. For example, if a
is written as a character constant but it
turns out to be used as a string, p2c will
have to write char-to-string conversion code
each time the constant is used.
VarStrings In HP Pascal, a parameter of the form "var s
: string" will match a string variable of any
size; a hidden size parameter is passed which
may be accessed by the Pascal strmax func-
tion. You can prevent p2c from creating a
hidden size parameter by setting VarString=0.
(Note that each function uses the value of
VarStrings as of the first declaration of the
function that is parsed, which is often in
the interface section of a module.)
Prototypes Control whether ANSI C function prototypes
are used. Default is according to AnsiC.
This also controls whether to include parame-
ter names or just their types in situations
where names are optional. The FullPrototyp-
ing parameter allows prototypes to be gen-
erated for declarations but not for defini-
tions (older versions of Lightspeed C
required this). If you use a mixture of pro-
totypes and old-style definitions, types like
short and float will be promoted to int and
double as required by the ANSI standard,
unless PromoteArgs is used to override this.
The CastArgs parameter controls whether
type-casts are used in function arguments; by
default they are used only if prototypes are
not available.
StaticLinks HP Pascal and Turbo Pascal each include the
concept of procedure or function pointers,
Sun Release 4.1 Last change: local 11
P2C(1) USER COMMANDS P2C(1)
though with somewhat different syntaxes. P2c
recognizes both notational styles. Another
difference is that HP's procedure pointers
can point to nested procedures, while Turbo's
can point only to global procedures. In HP
Pascal a procedure pointer must be stored as
a struct containing both a pure C function
pointer and a "static link," a pointer to the
parent procedure's locals. (The static link
is NULL for global procedures.) This nota-
tion can be forced by setting StaticLinks=1.
In Turbo, the default (StaticLinks=0) is to
use plain C function pointers with no static
links. A third option (StaticLinks=2) uses
structures with static links, but assumes the
links are always NULL when calling through a
pointer (if you need compatibility with the
HP format but know your procedures are glo-
bal).
SmallSetConst Pascal sets are translated into one of two
formats, depending on the size of the set.
If all elements have ordinal values in the
range 0..31, the set is translated as a sin-
gle integer variable using bit operations.
(The SetBits parameter may be used to change
the upper limit of 31.) The SmallSetConst
parameter controls whether these small-sets
are used, and, if so, how constant sets
should be represented in C. For larger
sets, an array of long is used. The s[0]
element contains the number of succeeding
array elements which are in use. Set ele-
ments in the range 0..31 are stored in the
s[1] array element, and so on. Sets are nor-
malized so that s[s[0]] is nonzero for any
nonempty set. The standard run-time library
includes all the necessary procedures for
operating on sets.
ReturnValueName
This is one of many "naming conventions"
parameters. Most of these take the form of a
printf-like string containing a %s where the
relevant information should go. In the case
of ReturnValueName, the %s refers to a func-
tion name and the resulting string gives the
name of the variable to use to hold the
function's return value. Such a variable
will be made if a function contains assign-
ments to its return value buried within the
body, so that return statements cannot
Sun Release 4.1 Last change: local 12
P2C(1) USER COMMANDS P2C(1)
conveniently be used. Some parameters
(ReturnValueName included) do not require the
%s to be present in the format string; for
example, the standard p2crc file stores every
function's return value in a variable called
Result.
AlternateName P2c normally translates Pascal names into C
names verbatim, but occasionally this is not
possible. A Pascal name may be a C reserved
word or traditional C name like putc, or
there may be several like-named things that
are hidden from each other by Pascal's scop-
ing rules but must be global in C. In these
situations p2c uses the parameter Alterna-
teName1 to generate an alternative name for
the symbol. The default is to add an under-
score to the name. There is also an Alterna-
teName2 parameter for a second alternate
name, and an AlternateName parameter for the
nth alternate name. (The value for this
parameter should include both a %s and a %d,
in either order.) If these latter parameters
are not defined, p2c applies AlternateName1
many times over.
ExportSymbol Symbols in the interface section for a Pascal
module are formatted according to the value
of ExportSymbol, if any. It is not uncommon
to use modulename_%s for this symbol; the
default is %s, i.e., no special treatment for
exported symbols. If you also define the
Export_Symbol parameter, that format is used
instead for exported symbols which contain an
underscore character. If %S (with a capital
"S") appears in the format string it stands
for the current module name.
Alias If the value of this parameter contains a %s,
it is a format string applied to the names of
external functions or variables. If the
value does not contain a %s, it becomes the
name of the next external symbol which is
declared (after which the parameter is
cleared).
Synonym This creates a synonym for another Pascal
symbol or keyword. The format is
Synonym old-name = new-name
All occurrences of old-name in the input text
Sun Release 4.1 Last change: local 13
P2C(1) USER COMMANDS P2C(1)
are treated as if they were new-name by the
parser. If new-name is a keyword, old-name
will be an equivalent keyword. If new-name
is the name of a predefined function, old-
name will behave in the same way as that
function, and so on. If new-name is omitted,
then occurrences of old-name are entirely
ignored in the input file. Synonyms allow
you to skip over a keyword in your dialect of
Pascal that is not understood by p2c, or to
simulate a keyword or predefined identifier
of your dialect with a similar one that p2c
recognizes. Note that all predefined func-
tions are available at all times; if you have
a library routine that behaves like, e.g.,
Turbo Pascal's getmem procedure, you can make
your routine a synonym for getmem even if you
are not translating in Turbo mode.
NameOf This defines the name to use in C for a
specific symbol. It must appear before the
symbol is declared in the Pascal code; it is
usually placed in the local p2crc file for
the project. The format is
NameOf pascal-name = C-name
By default, Pascal names map directly onto C
names with no change (except for the various
kinds of formatting outlined above). If the
pascal-name is of the form module.name or
procedure.name then the command applies only
to the instance of the Pascal name that is
global to that module, or local to that pro-
cedure. Otherwise, it applies to all usages
of the name.
VarMacro This is analogous to NameOf, but specifically
for use with Pascal variables. The righthand
side can be most any C expression; all refer-
ences to the variable are expanded into that
C expression. Names used in the C expression
are taken verbatim. There is also a Const-
Macro parameter for translating constants as
arbitrary expressions. Note that the vari-
able on the lefthand side must actually be
declared in the program or in a module that
it uses. The declaration for the variable
will be omitted from the generated code
unless the Pascal-name appears in the expres-
sion: If you ask to replace i with i+1, the
variable i will still be declared but its
Sun Release 4.1 Last change: local 14
P2C(1) USER COMMANDS P2C(1)
value will be shifted accordingly. Note that
if i appears on the lefthand side of an
assignment, p2c will use algebra to "solve"
for i.
In all cases where p2c parses C expressions,
all C operators are recognized except com-
pound assignments like `+='. (Increment and
decrement operators are allowed.) All vari-
able and function names are assumed to have
integer type, even if they are names that
occur in the actual program. A type-
specification operator `::' has been intro-
duced; it has the same precedence as `.' or
`->' but the righthand side must be a Pascal
type identifier (built-in or defined by your
program previously to when the macro defini-
tion was parsed), or an arbitrary Pascal type
expression in parentheses. The lefthand
argument is then considered to have the
specified type. This may be necessary if
your macro is used in situations where the
exact type of the expression must be known
(say, as the argument to a writeln).
FieldMacro Here the lefthand side must have the form
record.field, where record is the Pascal type
or variable name for a record, and field is a
field in that record. The righthand side
must be a C expression generally including
the name record. All instances of that name
are replaced by the actual record being "dot-
ted." For example,
FieldMacro Rect.topLeft = topLeft(Rect)
translates a[i].topLeft into topLeft(a[i]),
where a is an array of Rect.
FuncMacro The lefthand side must be any Pascal function
or procedure name plus a parameter list. The
number of parameters must match the number in
the function's uses and declaration. Calls
to the function are replaced by the C expres-
sion on the righthand side. For example,
FuncMacro PtInRect(p,r) = PtInRect(p,&r)
causes the second argument of PtInRect to be
passed by reference, even though the declara-
tion says it's not. If the function in ques-
tion is actually defined in the program or
Sun Release 4.1 Last change: local 15
P2C(1) USER COMMANDS P2C(1)
module being translated, the FuncMacro will
not affect the definition but it will affect
all calls to the function elsewhere in the
module. FuncMacros can also be applied to
predefined or never-defined functions.
IncludeFrom This specifies that a given module's header
should be included from a given place. The
second argument may be surrounded by " " or
< > as necessary; if the second argument is
omitted, no include directive will be gen-
erated for the module.
ImportFrom This specifies that a given module's Pascal
interface text can be found in the given
file. The named file should be either the
source file for the module, or a specially
prepared file with the implementation section
removed for speed. If no ImportFrom entry is
found for a module, the path defined by the
ImportDir list is searched. Each entry in
the path may contain a %s, which expands to
the name of the module. The default path
looks for %s.pas and %s.text in the current
directory, then for /usr2/mbk/p2c-
1.20/home/%s.imp. (where /usr2/mbk/p2c-
1.20/home is the p2c home directory.)
StructFunction This parameter is a list of functions which
follow the p2c semantics for structure-valued
functions (functions returning arrays, sets,
and strings, and structs in primitive C
dialects). For these functions, a pointer to
a return-value area is passed to the function
as a special first parameter. The function
stores the result in this area, then returns
a copy of the pointer. (The standard C func-
tion strcpy is an example of this concept.
Sprintf also behaves this way in some
dialects; it always appears on the
StructFunction list regardless of the type of
implementation.) The system configuration
file includes a list of common structured
functions so that p2c's optimizer will know
how to manipulate them.
StrlapFunction Functions on this list are structured func-
tions as above, but with the ability to work
in-place; that is, the same pointer may be
passed as both the return value area and a
regular parameter.
Sun Release 4.1 Last change: local 16
P2C(1) USER COMMANDS P2C(1)
Deterministic Functions on this list have no side effects
or side dependencies. An example is the sin
function in the standard math library; two
calls with the same parameter values produce
the same result, and have no effects other
than returning a value. P2c can make use of
this knowledge when optimizing code for effi-
ciency or readability. Functions on this
list are also assumed to be relatively fast,
so that it is acceptable to duplicate a call
to the function.
LeaveAlone Functions on this list are not subjected to
the normal built-in translation rules that
p2c would otherwise use. For example, adding
writeln to this list would translate writeln
statements blindly into calls to a C wri-
teln() function, rather than being translated
into equivalent printf calls. The built-in
translation is also suppressed if the func-
tion has a FuncMacro.
BufferedFile P2c normally assumes binary files will use
read/write, not get/put/^ notation. A file
buffer variable will only be created for a
file if buffer notation is used for it. For
global file variables this may be detected
too late (a declaration without buffers may
already have been written). Such files can
be listed in BufferedFile to force p2c to
allocate buffers for them; do this if you get
a warning message that says it is necessary.
Set BufferedFile=1 to buffer all files, in
which case UnBufferedFile allows you to force
certain files not to have buffers.
StructFiles If p2c still can't translate your file opera-
tions correctly, you can set StructFiles=1 to
cause Pascal files to translate into structs
which include the usual C FILE pointer, as
well as file buffer and file name fields.
While the resulting code doesn't look as much
like native C, the file structs will allow
p2c to do a correct translation in many more
cases.
CheckFileEOF Normally only file-open operations are
checked for errors. Additional error check-
ing, such as read-past-end-of-file, can be
enabled with parameters like CheckFileEOF.
These checks can make the code very ugly! If
I/O checking is enabled by the program
Sun Release 4.1 Last change: local 17
P2C(1) USER COMMANDS P2C(1)
($iocheck on$ in HP Pascal; {$I+} in Turbo;
this is always the default state), these
checks will generate fatal errors unless
enclosed in an HP Pascal try-recover con-
struct. If I/O checking is disabled, these
will cause the global variable P_ioresult to
be set zero or nonzero according to the out-
come. The default for most of these options
is to check only when I/O checking is dis-
abled.
ISSUES
Integer size. P2c normally generates code to work with
either 16 or 32 bit ints. If you know your C integers will
be 16 or 32 bits, set IntSize appropriately. In particular
setting IntSize=32 will generate much cleaner code: p2c no
longer must carefully cast function arguments between int
and long. These casts also will be unnecessary if ANSI pro-
totypes are available. To disable int/long casting because
you know at least one of these cases will hold, set Cast-
LongArgs=0. (The CastArgs parameter similarly controls
other types of casts, such as between ints and doubles.) The
Integer16 parameter controls whether Pascal integers are
interpreted as 16 or 32 bits, or translated as native C
integers. The default value depends on the Language
selected.
Signed/unsigned chars. Pascal characters are normally
"weakly" interpreted as unsigned; this is controlled by
UnsignedChar. The default is "either," so that C's native
char type may be used even if its signed-ness is unknown.
Code that uses characters outside of the range 0-127 may
need a different setting. Alternatively, you can use the
types {SIGNED} char and {UNSIGNED} char in the few cases
where it really matters. These comments are controlled by
the SignedComment and UnsignedComment parameters. (The type
{UNSIGNED} integer is also recognized.) The SignedChar
parameter tells whether C characters are signed or unsigned
(default is "unknown"). The HasSignedChar parameter tells
whether the phrase "signed char" is legal in the output. If
it is not, p2c may have to translate Pascal signed bytes
into C shorts.
Special types. P2c understands the following predefined Pas-
cal type names: integer, signed integers depending on
Integer16; longint, signed 32-bit integers; unsigned,
unsigned 32-bit integers; sword, signed 16-bit integers;
word, unsigned 16-bit integers; c_int, signed native C
integers; c_uint, unsigned native C integers; sbyte, signed
8-bit integers; byte, unsigned 8-bit integers; real,
floating-point numbers depending on DoubleReals; single,
single-precision floats; longreal, double, and extended,
Sun Release 4.1 Last change: local 18
P2C(1) USER COMMANDS P2C(1)
double-precision floats; pointer and anyptr, generic
pointers (assignment-compatible with any pointer type);
string, generic string of length StringDefault (normally
255); also, the usual Pascal types char, boolean, and text.
(If your Pascal uses different names for these concepts, the
Synonym option will come in handy.)
Embedded code. It is possible to write a Pascal comment con-
taining C code to be embedded into the output. See the
descriptions of EmbedComment and its relatives in the system
p2crc file. These techniques are helpful if you plan to do
repeated translations of code that is still being maintained
in Pascal.
Comments and blank lines. P2c collects the comments in a
procedure into a list. All comments and statements are
stamped with serial numbers which are used to reattach com-
ments to statements even after code has been added, removed,
or rearranged during translation. "Orphan" comments
attached to statements that have been lost are attached to
nearby statements or emitted at the end of the procedure.
Blank lines are treated as a kind of comment, so p2c will
also reproduce your usage of blank lines. If the comment
mechanism goes awry, you can disable comments with EatCom-
ments or disable their being attached to code with SpitCom-
ments.
Indentation. P2c has a number of parameters to govern inden-
tation of code. The default values produce the GNU Emacs
standard indentation style, although p2c can do a better job
since it knows more about the code it is indenting. Inden-
tation works by applying "indentation deltas," which are
either absolute numbers (which override the previous inden-
tation), or signed relative numbers (which augment the pre-
vious indentation). A delta of "+0" specifies no change in
indentation. All of the indentation options are described
in the standard p2crc file.
Line breaking. P2c uses an algorithm similar to the TeX
typesetter's paragraph formatter for breaking long state-
ments into multiple lines. A "penalty" is assigned to vari-
ous undesirable aspects of all possible line breaks; the
"badness" of a set of line breaks is approximately the sum
of all the penalties. Chief among these are serious penal-
ties for overrunning the desired maximum line length
(default 78 columns), an infinite penalty for overrunning
the absolute maximum line length (default 90), and progres-
sively greater penalties for breaking at operators deeply
nested in expressions. Parameters such as OpBreakPenalty
control the relative weights of various choices. BreakArith
and its neighbors control whether the operator at a line
break should be placed at the end of the previous line or at
Sun Release 4.1 Last change: local 19
P2C(1) USER COMMANDS P2C(1)
the beginning of the next. If you don't want any oversize
lines, define MaxLineWidth=78.
Unlike TeX, p2c's line breaker must actually try all possi-
ble sets of break points. To avoid excessive computation,
the total penalty contributed at each decision point must
sum to a nonnegative value; negative values are clipped up
to zero. This allows p2c to prune away obviously undesir-
able alternatives in advance. The MaxLineBreakTries parame-
ter (default 5000) controls how many alternatives to try
before giving up and using the best so far.
PASCAL_MAIN. P2c generates a call to this function at the
front of the main program. In the (unmodified) run-time
library all this does is save argc and argv away because in
both HP and Turbo these are accessed as global variables.
If you do not wish to use this feature, define ArgCName to
be argc, ArgVName to be argv, and MainName (normally
"PASCAL_MAIN") to be blank. This will work if argc and argv
are never accessed outside of your main program.
BUGS
P2c was designed with the idea that clean, readable output
in most cases is worth more than guaranteed correct output
in extreme cases. P2c is not a compiler! However, ideally
the "extreme" cases would include only those which never
arise in real life. Thus if p2c actually generates
incorrect code I will consider it a bug, but I will not apo-
logize for it. :-) Below are the major remaining cases
where this is known to occur.
Certain kinds of conformant array parameters (including
multi-dimensional conformant arrays) produce code that
declares variable-length arrays in C. Only a few C com-
pilers, such as the GNU C compiler, support this language
extension. Otherwise some hand re-coding will be required.
HP Pascal try-recover structures are translated into calls
to TRY and RECOVER macros, which are defined to simulate the
construct using setjmp and longjmp. If this emulation does
not work, define the symbol FAKE_TRY to cause these macros
to become "inert." (In cases where the error is detected by
code physically within the body of the try statement, a C
goto to the recover section is always generated.) Also,
local file variables in scopes which are destroyed by an
escape are not closed.
Non-local GOTO's and try-recover statements are each imple-
mented, but may conflict if both are used at once. Non-
local GOTO's are fairly careful about closing files that go
out of scope but may fail to do so in the presence of recur-
sion.
Sun Release 4.1 Last change: local 20
P2C(1) USER COMMANDS P2C(1)
Arrays containing files are not initialized to NULL as other
files are. In some cases, such as file variables allocated
by NEW, the file is initialized but not automatically closed
by DISPOSE.
LINK variables allowing sub-procedures access to their
parents' variables are occasionally omitted by mistake, if
the access is too indirect for p2c to notice. If this hap-
pens, you can add an explicit reference to a parent variable
in the sub-procedure. A statement of the form "a:=a" will
count as a reference but then be optimized away by p2c.
Many aspects of Modula-2 are translated only superficially.
For example, the type-compatibility properties of the WORD
and ARRAY OF WORD types are only roughly modelled, as are
the scope rules concerning modules.
Parts of VAX Pascal are still untreated. In particular, the
[UNSAFE] attribute and a few others are not fully supported,
nor are the semantics of the OPEN procedure.
Turbo and VAX Pascal's double, quadruple, and extended real
types all translate to the C double type. Turbo's computa-
tional type is not supported at all.
Because Pascal strings (with length bytes) are translated
into C strings (with null terminators), certain Pascal
string tricks will not work in the translated code. For
example the assignment s[0]:=chr(x) is translated to s[x]=0
on the assumption that the string is being shortened. If x
is actually greater than the current length, but not of a
recognizable form like ord(s[0])+n, then the generated code
will not work. In VAX Pascal this corresponds to performing
arithmetic on the LENGTH field of a varying-length string.
Turbo Pascal's automatic clipping of strings is not sup-
ported. In Turbo, if a ten character string is assigned to
a string[8] variable, the last two characters are silently
removed. The code produced by p2c generally will overrun
the target string instead! The StringTruncLimit parameter
(80 by default if Language=Turbo) specifies a string size
which should be considered "short"; assignments of
potentially-long strings to short string variables will
cause a warning but will not automatically truncate. The
cure is to use copy in the Pascal source to truncate the
strings explicitly.
FILES
file.xxx Pascal source files
file.c resulting C source file
module.h resulting C header file
p2crc local configuration file
Sun Release 4.1 Last change: local 21
P2C(1) USER COMMANDS P2C(1)
.p2crc alternate local configura-
tion file
/usr2/mbk/p2c-1.20/home/p2crc system-wide configuration
file
/usr2/mbk/p2c-1.20/home/system.impdeclarations for prede-
fined functions
/usr2/mbk/p2c-1.20/home/system.m2 analogous declarations for
Modula-2
/usr2/mbk/p2c-1.20/home/*.imp interface text for stan-
dard modules
/usr2/mbk/p2c-1.20/home/p2c/p2c.h header file for translated
programs
/usr2/mbk/p2c-1.20/home/libp2c.a run-time library
AUTHOR
Dave Gillespie, daveg@csvax.cs.caltech.edu.
Many thanks to William Bader, Steven Levi, Rick Koshi, Eric
Raymond, Magne Haveraaen, Dirk Grunwald, David Barto, Paul
Fisher, Tom Schneider, and others whose suggestions and bug
reports have helped improve p2c in countless ways.
Sun Release 4.1 Last change: local 22
