PC(1)

NAME
pc - Pascal compiler

SYNOPSIS
pc [ option ] ... file ...

DESCRIPTION
Pc is an ISO Level 1 Pascal compiler with Berkley extensions. Pc shares the Acorn / Norcroft code generation and preprocessor with the C compiler. As such it shares many of its command line options with cc. Only brief descriptions of these options are given here. See cc(1).

A program may consist of more than one module. Arguments whose name end with `.p' are taken to be Pascal source modules; they are compiled to object files with the extension `.o' in place of `.p'. Arguments ending with `.o' are taken to be object modules (possibly generated from another language), these are passed to ld(1) along with the compiled `.o' files to form an executable a.out. If a single Pascal program is compiled the `.o' file is deleted in the loading phase.

OPTIONS
The following options are interpreted by pc. Unrecognised options are passed to ld.

-c  Supress the loading phase of compilation.

-w  Suppress warning diagnostics.

-r"[options]"
    Enable or disable a selection of run time checks. The state of the run time check is toggled by each letter specified in options. The following options may be specified (defaults in brackets).
    a Array bound checking (off).
    c Case constant for case expression (off).
    n Nil pointer dereferencing (off).
    r Variable referenced before assigned (off).
    p Assertion checking (off).
    d Dead code checking (on).

-p  Generate objects suitable for profiling using prof. See prof(1).

-pg Generate objects suitable for profiling using gprof. See gprof(1).

-S  Leave assembly language output on corresponding files suffixed `.s'.

-M  Use the macro preprocessor to generate Makefile dependencies.

-E  Preprocess the source code, output to standard output.

-C  Do not remove comments when preprocessing, use with -E.

-o output
    Leave the executable in output instead of `a.out'.

-Dname
    Define preprocessor symbol name.

-Uname
    Undefine preprocessor symbol name.

-Idir
    Specify search path for `#include' files.

-help
    Output a nmemonic description of command line options.

-list
    Generate a line-numbered compiler listing in a file with extension .lst.

-iso
    Compile strictly according to ISO level 1 Pascal (BS 6192 : 1982).

LANGUAGE EXTENSIONS

Identifiers
    Identifiers may start with and contain underscores. There is no limit on identifier length and all characters are significant.

Files
    Input and output need not appear in the program header. `File of char' and `packed file of char' are treated as equivalent to `text'. Lazy evaluation is performed on files opened for input. In the absence of explicit file bindings (see reset and rewrite in the section on library extensions) external files are bound to a filename corresponding to the file identifier in the current directory, input and output are bound to /dev/tty. Files are buffered, on a read request from input the output buffer is flushed.

Strings
    Strings are blank padded or truncated in expressions and as value parameters to fit the required size. Strings may be of length 1. The null string '' is permitted. The packed attribute may be omitted in a string declaration.
    Pascal strings are zero terminated, the compiler adds one byte to the allocation space of the string and initialises this byte to zero when the string is assigned. Thus Pascal strings may be used in calls to external functions written in C.
    The predefined type string is equivalent to the C `char *' and may be used in external calls to C. Variables of type string are compatible with Pascal strings and may be used in assignments and expressions and as value parameters. Note that no space is allocated for a variable of type string, space must be allocated either by assignment or by explicit allocation using, for example, malloc(3).
    The predefined type alpha = packed array[1..10] of char is intended for use with the extended Pascal library, for example, date and time. See the section on library extensions.

Procedures and functions
    Procedures may return values, these are declared like functions with the keyword procedure substituted for function. Value returning procedures may be called in a procedure or function context. This is intended for use with external functions which return error codes which are not generally checked, for example, putchar(3).
    Procedures and functions may return records, like pointers these may not be immediatly referenced but must be assigned to a variable.
    Variadic functions may be declared by placing a .. as the last parameter. Variadic arguments may be accessed using the address and size functions (see the section on library extensions) however the intended purpose is for declaring external variadic functions, for example, printf(3).
    Procedure and functions pointers may be declared, these are declared by placing a `^' before a procedure or function declaration in a type declaration, note that the procedure or function must be given a name and all parameters must be named. Only top level and external procedures or functions may be be assigned to a procedure or function pointer. Procedure and function pointers are intended for use with external procedures or functions which take or return procedure or function pointers, for example, signal(3).

External objects
    Procedures, functions and variables may be declared external or global by placing extern; or external; after the declaration (like forward is used for declaring forward referenced procedures or functions. Such objects are taken to be external if there is no definition of the object in the same module and global if there is a definition. Objects declared external use the case of the external declaration identifier. External declarations are case sensitive between modules and case insensitive within a single module. The program heading may be omitted to create a module containing only procedure and functions and/or variables. No mainline may be given if the program heading is omitted.
    The recommended way to use external declarations is to create a header file (ending with `.h') containing the external declarations and use the #include mechanism provided by the C preprocessor to include this header in both the module defining the object and the module referencing the object. This insures type correctness between modules. Note that the filename after the #include must be enclosed in double quotes not single quotes.

Type casts
    For each pointer, ordinal or file type declared a cast function of the same name is automatically declared which casts a pointer, ordinal or file variable to the declared type.

Constants
    Constant expressions may be used in const declarations. The following functions may be used in constant expressions if they have constant arguments: shl, shr, uand, uor, uxor, unot, trunc, ord, chr, succ, pred, odd, and undefined.

Declarations
    Multiple Label, Const, Type and Variable declarations sections may be given within a single block. Label, Const, Type, Variable, Procedure and Function declarations may occur in any order.

Predefined types
    string = ^char - This type is compatible with Pascal strings and is intended for with with external library functions which require a C style string.
    alpha = packed array[1..10] of char - This type is used with the extended library functions time and date.
    pointer - This is a generic pointer type compatible with all other pointer types. It is equivalent to the C void * type.
    byte - This is a one byte long signed integer type.
    short - This is a half word long signed integer type.
    word - This is a word long unsigned integer type.

Operators
    The additional operators `&' and `|' are provided. These are functionally identical to and and or.

Conditional compilation
    Conditional compilation is provided using the #ifdef ... #else ... #endif construct provided by the C preprocessor. Preprocessor symbols may be defined using #define name. The use of #if and #define name value is not advised.

LIBRARY EXTENSIONS

address(x) : pointer
    Returns the address of variable access x.

argc : integer
    Returns the number of command line arguments to the program including the program name (ie argc is always at least 1).

argv(i, a)
    where i is an integer expression in range 0 to argc and a is a string variable. If a is of type string then the C expression argv[i] is assigned directly to a (ie a will point directly into the argv array and should not therefore be modified otherwise the contents of argv[i] are copied (possibly blank padded or truncated) to a.

assert(x[, a])
    where x is a boolean expressions and a is an optional string expression (typically explaining why the assertion might of failed). The assert call checks the value of x and if it is false generates a run time error giving the file and line number where the assertion failed. The reason string a is also printed if given in the assert call. Calls to the assert function must be enabled with the -rp option on the command line.

byte_offset(t, f) : integer
    t is the name of a record type, f is the name of a field within that record. Returns the offset (in bytes) of field f within a variable of record type t.

card(s) : integer
    where s is a set expression returns the number of elements in s.

close(f)
    where f is a file variable close the file bound to f, deallocates all buffers associated with f and frees f for reallocation.

clock : integer
    return the number of milliseconds user time used by this process.

date(a)
    where a is a variable of type alpha assigns the current date to a in the form `dd mmm yy'.

flush(f)
    flushes any output buffered for file f into its associated file binding.

halt
    stops execution and returns control to the parent process with a status of 0.

iaddress(x) : integer
    Returns the address of variable access x as an integer. This is equivalent to integer(address(x)).

ignore(x)
    where x is an expression of any type. Does nothing.

linelimit(f, x)
    where f is a variable of type text and x is and integer expression. Limits the number of lines of output to file f to x. If x is less than 0 no limit is imposed. By default no limit is imposed. These limits are ignored by the current release.

message(...)
    This is equivalent to writeln(...) except it writes to the unbuffered error stream stderr (file descriptor 2).

null
    Does nothing.

random(x) : real
    where x is a real expression which is evaluated but otherwise ignored returns a random number between 0.0 and 1.0 inclusive. random uses a linear congruential random number generator. Successive seeds are generated as (seed * 62605 + 113218009) mod 536870912. The initial seed is 7774755. The `random' numbers generated by this method are not very random, the preferred method is to use the external function random(3).

read(..., a, ...)

readln(..., a, ...)
    where a is a string variable reads the remainder of the text line into a. The text line is blank padded or truncated to fit the string. If the variable is of type string it is assumed that it is pointing to an allocated area large enough to hold the current line.

remove(a)
    where a is a string expression removes the file whose name is a (with trailing blanks removed).

reset(f, a)
    where f is a file variable and a is a string expression associates the filename f with the file variable and opens that file for reading. Note that there is no way of detecting an error opening a file (eg. file not found). To do this use the external function fopen(3) or stat(2).

rewrite(f, a)
    Similarly to reset, the two argument form of rewrite allows a filename to be bound to a file variable except the file is opened for writing instead of reading.

seed(x) : integer
    where x is an integer expression sets the current random number generator seed to x and returns the value of the previous seed.

shl(x1, x2) : integer
    where x1 and x2 are integers returns x1 shifted left x2 times. This is equivalent to x1 << x2 in C.

shr(x1, x2) : integer
    where x1 and x2 are integers returns x1 shifted right x2 times. This is equivalent to x1 >> x2 in C.

size(x) : integer
    where x is a variable access returns the size of variable access x in bytes.

stlimit(x)
    where x is an integer expression limits the number of statements that may be executed by the current program. By default no limit is imposed. This limit is ignored by the current release.

sysclock : integer
    returns the number of milliseconds system time used by this process.

time(a)
    where a is a variable of type alpha assigns the current local time to a in the form `hh:mm:ss'.

uand(x1, x2) : integer
    where x1 and x2 are integer returns the bitwise and of x1 and x2. This is equivalent to x1 & x2

uor(x1, x2) : integer
    where x1 and x2 are integer returns the bitwise or of x1 and x2. This is equivalent to x1 | x2 in C.

undefined(x) : boolean
    where x is a real expression returns false.

unot(x) : integer
    where x is integer returns the bitwise negation of x. This is equivalent to ~x in C.

uxor(x1, x2) : integer
    where x1 and x2 are integer returns the bitwise exclusive or of x1 and x2. This is equivalent to x1 ^ x2 in C.

write(..., x [: n] <mode>, ...)

writeln(..., x [: n] <mode>, ...)
    where x is a boolean, character or integer expression, n is an optional field width and <mode> is one of hex or oct writes the expression x in hexadecimal or octal notation respectively.

wallclock : integer
    returns the time in seconds since 00:00:00 GMT, January 1, 1970.

DIAGNOSTICS
The diagnostics produced by the Pascal compiler are intended to be self explanatory. Occasional messages may be produced by the loader. Other messages may be produced by C specific parts of the Acorn / Norcroft code generator.

FILES
file.p    Pascal source file
file.o    object file
a.out    executable
/usr/bin/pc    Pascal compiler
/usr/lib/libpc.a    Pascal library

SEE ALSO
BSI Computer Programming Language Pascal (BS 6192 : 1982)
Pascal User Manual and Report (3rd edition)
Berkley Pascal User's Manual

BUGS
Goto into block is not detected and may cause a core dump if the block at which the goto is directed is not reached by any other means.

In -iso mode applied occurences are not detected (this is normal behaviour for Berkley Pascal).

The actual parameters corresponding to formal parameters that occur in a single conformant array parameter specification may possess different types as long as they are conformable with the formal parameter type.

remove takes an argument of type alpha, not a string and does not strip trailing spaces from its argument.

address returns pointer to the type of its argument instead of the generic type pointer.

undefined is declared in one place within the Pascal compiler as a function and in another place as a procedure, therefore it can be used in neither procedure or function contexts.

This is a Beta version of pc. The compiler is know to behave badly when given syntactically incorrect source code. Support for dbx(1) is also incomplete, although the compiler will recognise the -g option if it is used it will frequently fail with an internal error on legal code. See the release notice supplied with the system for a more complete description of known problem areas.