UVAPC(1)

NAME
uvapc - University of Virginia Pascal Compiler

SYNOPSIS
uvapc [ -o file ] [ -NScgpsw ] file [ file ... ]

DESCRIPTION
Uvapc builds an executable file (by default a.out) by compiling Pascal language source files into assembly language files, assembling these into object files with as(1), and linking with ld(1) all the resulting object files and the appropriate system libraries into one executable file. Uvapc accepts the following types of input files:

•   Pascal source files whose names end with .p,

•   Assembly language files whose names end with .s,

•   Object files whose names end with .o,

•   Object libraries whose names end with .a.

Since uvapc creates files in the current directory, the user must have write permission in this directory. By default uvapc removes any intermediate files that it creates.

OPTIONS
Uvapc interprets the following options.

-N  Disable peephole optimization in the compilation phase. The peephole optimizer should only be disabled when debugging the compiler.

-S  Suppress the assembling and link editing phases of the compilation and do not remove any assembly language files. In the current directory, name each assembly language file by replacing the .p in the corresponding source file name with .s.

-c  Suppress the link editing phase of the compilation, and do not remove any object files. In the current directory, name object files by replacing the .p or .s in the corresponding source or assembly file name with .o.

-g  During the compilation phase, generate extra symbolic information to be used by a symbolic debugger such as sdb(1) or dbx(1). Invoke the assembler and link editor with any special arguments needed for debugging.

-o outfile
    Name the executable file outfile instead of a.out.

-p  During the compilation phase, generate code to count function calls, etc., for program profiling. Link the object files with profiled versions of the system libraries. See prof(1).

-s  Accept only standard ISO Pascal. Non-standard features and extensions cause error messages. (See the EXTENSIONS section below.)

-t  Do not generate extra code to perform run time checks. Using this option disables run time bounds checking on array index expressions, expressions in assignment statements, expressions being passed as parameters, return values from pred, succ, and chr, values being written to or read from files, etc.

-w  Suppress warning diagnostics during the compilation.

IMPLEMENTATION DEPENDENCIES
Uvapc implements the full programming language defined in the ISO Pascal standard, including conformant array parameters. Through extensive compile time checking, uvapc detects all violations of the standard, except for certain errors (see BUGS section). The standard does not fully specify the correct action taken by all Pascal language features, however, so here are the major implementation dependencies in uvapc.

•   When the files input and output appear in the program-heading, they are associated with standard input and standard output, respectively. By default these files are the user's terminal, but they can be manipulated via the command shell when invoking a Pascal program.

•   When reset or rewrite is called with a parameter that is an external file variable (i.e., a file listed in the program-heading), the system pathname of the file associated with the Pascal variable is the same as the name of the variable. (See the extensions to reset and rewrite below.)

•   Uvapc uses lazy input when reading files. The Pascal Standard states that after a read from a text file, the file buffer variable contains the next character in the input stream. A strict adherence to this rule would prevent the writing of interactive programs because the user would need to ``type ahead'', supplying input data before the program prompts for it. To fix this, lazy input waits until the data in the buffer variable is needed before actually reading it. When writing an interactive program note that the Pascal functions eof and eoln both do input operations when the buffer variable needs filling. An interactive Pascal program should output a prompt before the first call to either of these functions.

•   The system usually restricts the number of files that a process can have open at one time to 20 or 32. A Pascal program will abort if the combined total of external files and active local files exceeds the system limit. A local file is inactive until it is passed to the standard procedure rewrite(). A local file automatically becomes inactive (i.e., is closed and removed) when its enclosing subprogram activation terminates. Dispose() deactivates dynamic file variables created with new().

•   Set types have an efficient, but somewhat restricted implementation. The compiler supports the popular set of char, and any set can be represented provided the difference between the maximum element and the minimum element does not exceed 255. The following set operators guarantee correct results for any two set operands of compatible type: *, -, >=, <=, =, <>. The in operator also works correctly for any set operand. However, the set constructor operator [ ] and the set union operator + may attempt to construct an unrepresentable set, which halts the program.

EXTENSIONS
Uvapc provides several extensions to the Pascal standard.

•   Identifiers may contain the underscore character `_'. Underscores may appear anywhere in an identifier, and an identifier may be comprised of nothing but underscores. Note that upper case letters are not distinguished from corresponding lower case letters, in compliance with the Standard.

•   The case statement has an otherwise clause. If the case-index does not appear in any case-constant-list, the statement following otherwise is executed. The syntax for the case statement is:
    case-statement = `case' case-index `of' case-list-element { `;' case-list-element }
    [ [ `;' ] `otherwise' statement ] [ `;' ] `end' .
    case-index = expression .
    case-list-element = case-constant-list `:' statement .
    case-constant-list = case-constant { `,' case-constant } .

•   The procedures reset and rewrite take an optional second parameter. This second parameter is a string and it contains the null-terminated pathname of the file to be associated with the file variable passed as the first parameter. The file variable must be an external file. Note that uvapc automatically null-terminates string literals enclosed in single quotes. To store the null character in a packed array of char, use chr(0).

•   Similar to the file output, if the file errfile appears in the program-heading, uvapc automatically declares errfile to be type text, associates it with standard error, and opens it for writing.

•   Uvapc has a file inclusion facility that is not disabled by the -s flag. Placing the following line in the Pascal source text causes uvapc to replace the line with the text of the included file.
    #□include□"inclfile"
    where □ is an optional sequence of blanks and tabs, and inclfile is the pathname of the included file. Note that the # must be the first character on the line, that single quotes can be used instead of double quotes, and that inclfile need not end with .p. Nested file inclusions are supported.

•   Three built in parameterless functions return time information from the system. Function clock returns an integer that is the number of central processor milliseconds of user time consumed thus far by the process. Function sysclock is identical to clock except that sysclock returns the system time consumed. Function wallclock returns an integer that is the number of seconds since January 1, 1970, 00:00:00 GMT.

•   Procedure date(a) copies into string variable a the current date in a fixed length, printable format. (Note that a string variable is any packed array [ 1 .. n ] of char where n > 1.) The date string format is
    Www□Mmm□dd□hh:mm:ss□yyyy
    where Www is the first three letters of the weekday, eg, Sun; where □ is a single space; where Mmm is the first three letters of the month, eg, Nov; where dd is the two digit day of the month; hh is the hour; mm is the minute; ss is the second; and yyyy is the year. Date left justifies the date string, truncating the right side if a is too short, and padding the right side with spaces if a is too long.

•   Like any other command on the system, when a Pascal program is invoked, arguments may be specified after the command name. The built in function argc and the procedure argv make these arguments available to the Pascal program. Argc returns an integer that is the number arguments on the command line. Argc has no parameters and its return value is never less than one because the system passes the name of the command itself as the first argument. Procedure argv(i,a) copies into a the ith command line argument. The parameter i is an integer expression in the range 0 .. argc - 1 and parameter a is a string variable. Argv always null-terminates the data copied into a. If a is too large, argv puts nulls (chr(0)) in the extra space. If a is too small, argv copies the left portion of the argument and puts a null in the last character of a.

•   The parameterless function random is a pseudo-random number generator that returns a real value in the range [0.0 .. 1.0) (1.0 cannot be returned). To change the sequence of values returned by random, the seed for random can be set to i using procedure seed(i), where i is an integer expression.

•   Uvapc has a rudimentary facility for separate compilation, allowing a program to be written using more than one source file. This facility is covered in the next section.

SEPARATE COMPILATION
Uvapc accepts programs written on several independently compilable source files. For this discussion, a source file is the text of a file itself plus the text of any auxiliary files inserted via the #include facility. A uvapc program consists of one program source file and zero or more module source files. The program source file has the same syntax as a standard Pascal program. A module has the same syntax as a standard Pascal program except for the omission of 1) the program-heading at the start of the file; 2) the final compound-statement that comprises the main program's algorithm; and 3) the final `.'. Thus the first input symbol in a module must be const, type, var, function, or procedure, and the last symbol must be a semicolon.

A variable, procedure, or function identifier declared in the outermost block of any source file is global, which means that the identifier denotes the same variable, procedure, or function across all source files. A global object must be declared in each source file that refers to it. If declarations for the same object in different source files are inconsistent, the program will not run correctly. Since uvapc does not detect inconsistent declarations, global declarations are best kept in auxiliary files that the source files include with #include.

To declare a procedure or function whose algorithm is defined in another file, uvapc provides the external directive. The rules for using external are exactly the same as for the forward directive, with the following exceptions. Only functions and procedures in the outermost block of the source file may have the external directive. If a function or procedure is declared external, it need not be defined later in the same source file. A subsequent definition is legal, and like forward, the second definition may not have a formal-parameter-list, nor a function result-type.

The special files input, output, and errfile should not be declared in a module. If a module refers to one of these special files, it must appear in the program-heading of the main program or the program will not run correctly.

It is illegal for a goto statement in a module to jump to a label in the main program. To get around this restriction, in the main program's source file write a procedure that jumps to the label. In the module declare the procedure external and call it.

CALLING C LANGUAGE FUNCTIONS
It is possible to call functions written in C using the separate compilation facility. Any global C function or global C variable can be accessed in a Pascal program provided the name has been declared in the outermost Pascal block. In order for C and Pascal object files to link properly, corresponding global symbols must match exactly. (Symbols are the names of objects in assembly language files.) The C compiler emits symbols that are spelled exactly like the corresponding C identifier. Uvapc, however, emits symbols by converting upper case letters in the Pascal identifier to lower case, and if the identifier is a procedure or function, uvapc appends an underscore. Be sure the C source file takes these changes into account.

Write the Pascal external declaration of a C function with care. The order of the parameters is the same in both languages. For each parameter, decide whether to use the variable (var) parameter declaration, or the value parameter declaration. For variable parameters, uvapc passes a pointer that is the memory address of the actual parameter, so the C function should expect a pointer. For value parameters, uvapc passes the value of the actual parameter. If the actual parameter is an array or record, a copy of the entire actual parameter is passed. Since C never passes arrays in this fashion, arrays should always be variable parameters.

Uvapc uses a small subset of the many data types available in C. The Pascal types boolean, integer, and enumerations are equivalent to the C type int. The Pascal type char is equivalent to C's char and the Pascal type real is equivalent to C's double. Pointers have the same implementation in both languages. In uvapc, the set and file types are C structs defined in the uvapc run time library. Passing these types to C functions is not recommended.

Pascal records are analogous to C structs. Unfortunately, uvapc does not always store record fields in the order that they appear in the source file, so coming up with an equivalent C struct definition for a Pascal record definition may be tricky. Declare the Pascal record in a small, test program that uses all the fields of the record, and compile the program with uvapc -S. Examine the resulting assembly language to determine the field offsets, and write the C struct definition based on this information.

To build an executable file from Pascal and C source files, compile the C source files into object files with cc -c, and compile the Pascal source into object files with uvapc -c. Link all the object files together with uvapc.

FILES

LIBDIR/pcomp
    compiler,

LIBDIR/libuvapc.a
    Pascal library,

LIBDIR/libp/libuvapc.a
    profiled Pascal library,

BINDIR/as
    assembler,

BINDIR/ld
    link editor,

SYSLIB/libm.a
    standard math library,

SYSLIB/libc.a
    standard system library,

SYSLIB/crt0.o
    system start-up routine,

SYSLIB/mcrt0.o
    system start-up routine for profiling,

TMPDIR/*
    temporary files created by as(1) and ld(1),

LIBDIR
    usually /usr/lib or /usr/local/lib,

BINDIR
    usually /bin or /usr/bin,

SYSLIB
    usually /lib, /usr/lib, or /usr/lib/libp (profiled),

TMPDIR
    usually /usr/tmp or /tmp. Change this by setting the environment variable TMPDIR to a different directory.

SEE ALSO
as(1), ld(1), cc(1), prof(1), sdb(1), sh(1),
BS6192, Specification of the Computer Programming Language Pascal, British Standards Institution 1982 (also ISO 7185).

BUGS
The Pascal standard defines an error to be a violation of the standard that the processor may leave undetected. The standard usually gives error status to those violations that are most easily detected at run time. Uvapc never detects the following errors:

•   Integer arithmetic overflow/underflow,

•   Use of an inactive record variant,

•   Return value from trunc or round outside of the range -maxint .. maxint,

•   A case statement where the case-index does not appear in any case-constant-list. Execution silently resumes at the next statement (unless the case statement has an otherwise clause).

Through system error signals and compile time checking of variable usage, uvapc sometimes (but not always) detects the following errors:

•   Use of an undefined variable,

•   Function returning an undefined value,

•   Dereferencing a nil, undefined, or deallocated pointer,

•   Illegal use of new and dispose,

•   Illegal use of pack and unpack,